@akira-tl/forgerelay 0.2.6 → 0.3.1

package/docs/configuration.md

@@ -123,6 +123,35 @@ MCP clients discover metadata from:
 explicit tool mode is unset. The corresponding legacy `DEVSPACE_*` names are
 also accepted.
 
+The selected mode controls the real `tools/list` surface. ForgeRelay does not
+hide callable tools behind capability documentation. In every mode,
+`open_workspace` returns a `capabilityFingerprint` containing the package
+version, tool mode, and stable semantic capability names. The fingerprint also
+reports enabled optional domains such as subagent profile discovery, native
+artifact download, MCP App UI, or aggregate `show_changes` review when those
+features are actually available; it remains a semantic summary rather than a
+copy of `tools/list`.
+
+Bootstrap responses also return `capabilityGuides`, which are compact descriptors
+for built-in ForgeRelay documentation that the Agent can explicitly load with
+`read` when a task needs that domain. Current built-in domains cover lifecycle
+Hooks, managed worktrees, subagents, artifact/change-review workflows, Host/OAuth/
+MCP App integration, and long-running shell/PTY/process behavior. Optional-domain
+descriptors such as `subagents` and `artifacts-review` are advertised only when
+the corresponding feature is enabled, so disabled features do not add bootstrap
+context.
+
+There is no separate progressive-disclosure configuration switch. Capability
+Guide discovery is built in, while actual tool exposure continues to be
+controlled by `FORGERELAY_TOOL_MODE` and feature-specific settings. If the
+fingerprint reports a capability that is missing from the Host's current tool
+snapshot, treat that as stale Host MCP metadata: reconnect/refresh the integration
+or use a Host context that reloads `tools/list`. The ForgeRelay process cannot
+force a Host to invalidate its cached schema.
+
+`rename` is the canonical move/rename primitive for files and directories; there
+is no separate `move` MCP tool.
+
 Codex-mode commands run without a PTY by default. `tty: true` enables interactive
 programs when the optional `node-pty` dependency is available.
 
@@ -182,7 +211,7 @@ Hooks v1 是自动生命周期规则。规则由用户或 Agent 主动写入；
   "event": "BeforeTool",
   "matcher": {
     "tool": "bash",
-    "commandRegex": "^git\\s+push\\s+origin\\s+v\\d+\\.\\d+\\.\\d+$"
+    "commandRegex": "git\\s+push\\s+origin\\s+v\\d+\\.\\d+\\.\\d+"
   },
   "command": "npm run release:verify",
   "timeoutSeconds": 300,
@@ -226,7 +255,7 @@ forgerelay hooks check --project /path/to/project
 | 字段 | 匹配方式 |
 | --- | --- |
 | `tool` | 精确匹配 MCP tool 名称。 |
-| `commandRegex` | 对 tool payload 中的 `command` 做 JavaScript 正则匹配。 |
+| `commandRegex` | 对 tool payload 中的 `command` 做 JavaScript 正则匹配；命中后 Hook 收到的 `payload.command` 是实际匹配片段，完整原命令在片段不等于整串命令时保留为 `payload.originalCommand`。 |
 | `pathRegex` | 对 payload 中的 `path` 或 `paths` 做正则匹配。 |
 | `provider` | 精确匹配 subagent provider。 |
 | `workspaceMode` | `checkout` 或 `worktree`。 |
@@ -316,7 +345,8 @@ When subagents are enabled, profiles are discovered from:
 - active legacy config directory `~/.devspace/agents/*.md` when reused;
 - project `.devspace/agents/*.md` for migration compatibility.
 
-The bundled `subagent-delegation` skill teaches the current CLI workflow:
+The ForgeRelay-owned `subagents` capability guide teaches the current CLI
+workflow on demand:
 
 ```bash
 forgerelay agents ls
@@ -324,6 +354,11 @@ forgerelay agents run <profile-or-provider-or-id> "<prompt>"
 forgerelay agents show <id>
 ```
 
+0.3 no longer auto-discovers or seeds the package's historical bundled
+`subagent-delegation` Skill for new setups. An existing or user-authored Skill
+with that name remains an ordinary Skill and is still discovered from the normal
+Skill paths when subagents are enabled; ForgeRelay does not delete or rewrite it.
+
 ## Logging
 
 | Variable | Default |
@@ -334,7 +369,7 @@ forgerelay agents show <id>
 | `FORGERELAY_LOG_ASSETS` | `0` |
 | `FORGERELAY_LOG_TOOL_CALLS` | `1` |
 | `FORGERELAY_LOG_SHELL_COMMANDS` | `1` in `pretty`, `0` in `json` |
-| `FORGERELAY_TRUST_PROXY` | `0` |
+| `FORGERELAY_TRUST_PROXY` | auto: `1` only for loopback bind + non-loopback public URL; otherwise `0` |
 
 `pretty` is the human-facing local console format. It uses terminal-aware color,
 short timestamps, workspace-first context, and compact operation results while
@@ -351,6 +386,14 @@ overridden, JSON mode preserves request logging and omits shell command previews
 `FORGERELAY_LOG_REQUESTS` and `FORGERELAY_LOG_SHELL_COMMANDS` always override
 these format-specific defaults when set.
 
+When ForgeRelay binds to loopback (`127.0.0.1`, `::1`, or `localhost`) but is
+configured with a non-loopback public URL, it automatically trusts exactly one
+upstream proxy hop. This matches the normal tunnel/reverse-proxy topology and
+keeps OAuth rate limiting aligned with Express client-IP resolution. Set
+`FORGERELAY_TRUST_PROXY=0` to disable this inference, or `=1` to enable one-hop
+trust explicitly. ForgeRelay never auto-enables proxy trust when binding to
+`0.0.0.0` or another directly reachable interface.
+
 ## Environment-only example
 
 ```bash

package/docs/debugging.md

@@ -60,7 +60,7 @@ The acceptance checks:
 4. dynamic OAuth client registration, PKCE Owner-password approval, and access-token exchange;
 5. MCP `initialize`, including package/server version consistency and the shell mutation safety contract;
 6. `tools/list` for the full debug tool surface, including `close_workspace`, `write_stdin`, canonical `processId` plus the deprecated `sessionId` compatibility alias, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, workspace resume/stale-workspace schema, and MCP App tool metadata;
-7. the full MCP App template chain: `resources/list`, `resources/templates/list`, current content-hashed `resources/read`, legacy/historical template compatibility reads, `text/html;profile=mcp-app`, CSP resource domains, and an HTTP fetch of the JavaScript asset referenced by the template;
+7. the full MCP App template chain: `resources/list`, `resources/templates/list`, current content-hashed `resources/read`, legacy/historical template compatibility reads, `text/html;profile=mcp-app`, the unique app domain plus CSP resource domains, and an HTTP fetch of the JavaScript asset referenced by the template;
 8. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash` through `ProcessManager`, and a deliberate failed `edit`;
 9. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP transport session, plus rejection of an arbitrary path outside the workspace/temp roots;
 10. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;

package/docs/roadmap.md

@@ -102,7 +102,79 @@ Hooks v1 的目标是给用户和 Agent 一个很小、自动、可组合的生
 - 后台命令句柄以 `processId` / process handle 为 canonical 名称，旧 `sessionId` 在 0.2.x 保留 deprecated alias 兼容窗口；
 - 为 stateless MCP transport 做准备，同时保留旧协议兼容 adapter，避免把 transport 生命周期重新提升成 ForgeRelay 会话模型。
 
-## 0.3 — LSP code intelligence v1
+## 0.3 — MCP loading 与渐进式能力披露
+
+0.3 的目标是把 ForgeRelay 的 MCP interface 做成一个深而稳定的模型接口：普通编码 primitive 始终直接可见，低频知识与低频 action 都按需披露，新增 ForgeRelay 能力不再线性扩大 Host 首次加载的 `tools/list` 与 instructions。
+
+0.3.0 已完成第一阶段：压缩 server instructions、由 `open_workspace` 返回 version/capability fingerprint、通过 advertised path + `read` 按需加载 ForgeRelay-owned capability guide，并用 fingerprint 与 Host `tools/list` 的差异诊断 stale Host metadata。Capability guide 与 Skill 的语义所有权保持区分：Skill 描述用户、项目或生态工作流；Capability guide 描述 ForgeRelay 自身、与版本绑定的产品能力。
+
+0.3 后续阶段采用 ADR-0002 的接口形状。Canonical Core tool surface 最终固定为：
+
+```text
+open_workspace
+close_workspace
+read
+write
+edit
+rename
+delete
+bash
+capability
+```
+
+其中 `open_workspace` 负责 Workspace 生命周期入口与轻量 Capability catalog；`capability` 是唯一低频 Capability gateway；`bash` 同时承担命令启动与后续 process interaction；Managed worktree 是 Workspace 的 backing mode，由 `close_workspace` 统一完成关闭/finalize lifecycle。Capability registry 只能暴露显式注册、带输入约束、可用性和 guide metadata 的 ForgeRelay capability，不能退化成任意 RPC、URL dispatcher 或 shell 后门。
+
+### 0.3.1 — MCP App 与诊断补丁
+
+在不改变主 tool surface 的前提下先修 0.3.0 发布后真实 Host 暴露的问题：
+
+- 为 MCP App resource 补齐 Host submission 所需的 widget/app domain metadata，并保持现有 CSP、content-hash URI 与 compatibility resource contract；
+- `forgerelay doctor` 显示解析后的 MCP 运行形态，例如 tool mode、widgets、public URL、proxy trust 与可选 capability 开关，避免“功能代码存在但当前实例未启用”只能靠源码排查；
+- 补齐 release/Host integration 的诊断与验收用例，但不在这一版重塑 tool schema。
+
+### 0.3.2 — Capability Registry 与 Gateway
+
+建立新的低频 action seam，但保留现有公开工具作为迁移兼容：
+
+- 新建 ForgeRelay-owned Capability registry，每项至少声明稳定 name、简短 description、availability、input contract、guide metadata 与 handler；
+- 新增唯一 MCP tool `capability`，提供紧凑的 `describe` / `run` 语义；
+- `open_workspace` 返回轻量 Capability catalog，只做发现，不复制完整 schema、示例或 guide 正文；
+- Agent 已熟悉某项 capability 时可以直接执行；不熟悉时先 `describe`，再按返回的 guide path 使用 `read` 获取详细说明；
+- 选择一组低风险、当前主要依赖 CLI 的检查型能力作为 tracer bullet，验证 registry、Hooks、日志、错误和 Host card contract，而不是一开始迁移所有功能。
+
+### 0.3.3 — 低频 Action 迁入 Gateway
+
+用真实现有能力验证 Gateway 能承载持续扩展，而不是只做一层转发：
+
+- 将 change review 收口为如 `review.changes` 的 registered capability；
+- 将 native artifact ingress 收口为如 `artifact.download` 的 registered capability；
+- 适合 Agent 主动调用的 Hook inspection/check 等低频操作进入同一 namespace model；
+- Capability guide 与 catalog/registry 建立一一可追踪关系，availability 由运行时条件决定；
+- `show_changes`、`download_artifact` 等旧 dedicated MCP tools 在迁移窗口内只作为兼容入口，不再作为长期接口设计。
+
+### 0.3.4 — Workspace 与 Process 生命周期收敛
+
+移除两个泄漏内部实现的 public lifecycle tool：
+
+- `bash` 成为 Process Manager 的唯一公开 interface；`action="run"` 启动命令，`action="process"` 使用 `processId` 查看、等待、输入、调整 PTY 或中断已有进程；内部 ProcessManager 可以继续保留更细的方法，但 Host 不再需要学习 `write_stdin`；
+- `close_workspace` 成为唯一 workspace 关闭入口；checkout 直接释放，managed-worktree-backed Workspace 在同一接口内执行 BeforeWorktreeClose、commit/integrate/cleanup、AfterWorktreeClose 并关闭 Workspace；
+- 从 canonical MCP surface 删除 `write_stdin` 与 `close_worktree`，同时清理对应 server instructions、fingerprint 和 capability guide 中的旧心智模型；
+- 保留 `processId` 作为运行中进程的 opaque handle，保留 worktree 作为 Workspace 的可观察 backing metadata，而不是第二套 Host lifecycle。
+
+### 0.3.5 — Canonical MCP Surface 收口
+
+完成 0.3 的接口稳定化与真实 Host 验收：
+
+- regular ForgeRelay MCP surface 收口为 9 个 canonical tools；`minimal/full` 不再通过增减 `grep/glob/ls` 改变主产品心智模型，搜索与目录检查可由 `bash` 承担；
+- 评估并隔离 `codex` compatibility surface，使其作为明确 adapter 存在，而不是反向定义 ForgeRelay canonical interface；
+- 删除已经完成迁移的 dedicated low-frequency tool aliases，确保新增 Capability 不再扩大常驻 tool count；
+- 简化 fingerprint，使其用于版本/运行时能力摘要与 stale-Host 诊断，而不是重新枚举 tool implementation；
+- 对 `open_workspace → catalog → capability describe/read/run`、managed worktree close、长进程 interaction、review/artifact capability、MCP App 与 stale-schema 情况做 7677 acceptance 和新 Host 会话验收；
+- 0.3.5 通过后，0.3 的 MCP progressive-disclosure 主题视为完成，0.4 回到原定 LSP code intelligence v1。
+
+必要安全语义始终留在 Core tool interface、Capability contract 或自动 Hook report 中；渐进式披露不能成为隐藏权限、隐式 autonomous workflow 或绕过 allowed roots/auth 的机制。`rename` 继续作为文件和目录 move/rename 的统一 primitive。
+
+## 0.4 — LSP code intelligence v1
 
 LSP is moderate implementation complexity if ForgeRelay does not become a
 language-server installer.
@@ -110,7 +182,7 @@ language-server installer.
 The first version should launch only language servers already available on the
 user's machine or explicitly configured by the user/project.
 
-During 0.3 development, MCP App UI hardening can land alongside the LSP work when
+During 0.4 development, MCP App UI hardening can land alongside the LSP work when
 it does not distort the code-intelligence scope. In particular, evaluate a more
 self-contained template/bootstrap bundle, reduce avoidable external chunk fetches,
 and keep the current content-hash/compatibility-resource contract intact. This is
@@ -125,47 +197,19 @@ Initial operations:
 - workspace symbols;
 - hover/type information.
 
-Prefer one deep MCP capability such as:
-
-```text
-code_intelligence({
-  workspaceId,
-  operation,
-  path,
-  line,
-  column,
-  query
-})
-```
-
-rather than one MCP tool per language or language-server method.
+Expose code intelligence through the Capability Gateway established in 0.3 rather than adding another top-level MCP tool. A representative registered capability may look like `code.intelligence`, with its language-server operation/path/position/query fields carried inside the capability arguments. The exact LSP contract remains 0.4 work; the stable Core tool surface does not change per language or language-server method.
 
 Candidate servers include `typescript-language-server`/tsserver, Pyright,
 `rust-analyzer`, `gopls`, and `clangd`, but ForgeRelay should treat server
 commands/configuration as external dependencies.
 
-## 0.4 — First-class subagent MCP
+## 0.5 — First-class subagent MCP
 
 ForgeRelay already owns provider adapters and resumable local agent sessions.
 The next step is to remove the current `bash -> forgerelay agents ...` indirection
 for MCP hosts.
 
-A compact interface should reuse the existing provider adapter registry:
-
-```text
-subagent({
-  action: "run" | "list" | "show" | "cancel",
-  workspaceId,
-  profile,
-  provider,
-  prompt,
-  agentId
-})
-```
-
-The parent agent chooses an available provider/profile such as Codex or Claude.
-ForgeRelay launches, tracks, resumes, and cancels the provider-backed worker when
-the underlying provider supports those operations.
+First-class subagent operations should reuse the Capability Gateway established in 0.3 rather than add another top-level MCP tool. The exact registered names, action semantics and provider/session contract remain 0.5 design work. The parent agent will continue choosing from available provider/profile metadata while ForgeRelay owns provider-backed worker lifecycle state.
 
 This is intentionally provider-backed delegation, not an attempt to emulate a
 host-native subagent implementation.

package/docs/security.md

@@ -28,6 +28,17 @@ Filesystem-oriented tools canonicalize existing path segments before access so
 symlinks inside either the workspace or OS temp directory cannot escape to
 arbitrary filesystem locations.
 
+`read` has one narrow additional path class for explicitly advertised documents.
+`open_workspace` may advertise a Skill entry file or a ForgeRelay capability
+Guide outside the normal workspace/temp roots. Only that advertised entry file is
+readable initially; after it is read, files inside that advertised document's
+own directory may be read as supporting material. This does not expand write,
+edit, rename, delete, shell working-directory, or workspace-open roots.
+
+Capability Guides are ForgeRelay-owned, versioned package documentation. Their
+paths are surfaced by the running server rather than guessed by the Agent. This
+keeps progressive disclosure from becoming a general arbitrary-file read escape.
+
 ## Owner-password OAuth
 
 New installations store local configuration in:
@@ -100,13 +111,19 @@ for dynamically crossing such a boundary.
 The Agent-facing shell contract therefore does not ban every command that can
 change files. Commands may modify ordinary project files when that is a natural
 part of the user's requested development task, including package managers,
-generators, formatters, and similar tooling. The contract does prohibit shell
-mutation of security- or privilege-sensitive operating-system files and
-credential material such as `/etc/sudoers`, `/etc/passwd`, `/etc/shadow`, PAM or
-authentication policy, SSH private keys, and equivalent privileged targets.
-Configuration files may be changed through shell only when the user's request
-explicitly calls for that configuration change rather than merely making it a
-convenient implementation detail.
+generators, formatters, and similar tooling. Shell commands may also perform
+external device or hardware mutations when the user's current request explicitly
+asks for the actual device-changing operation. ForgeRelay does not assume a
+particular flashing protocol, transport, device path, or firmware workflow. A
+check, audit, probe, backup, verification, dry-run, or build-only request must not
+be treated as authorization for a later persistent hardware write.
+
+The contract does prohibit shell mutation of security- or privilege-sensitive
+operating-system files and credential material such as `/etc/sudoers`,
+`/etc/passwd`, `/etc/shadow`, PAM or authentication policy, SSH private keys, and
+equivalent privileged targets. Configuration files may be changed through shell
+only when the user's request explicitly calls for that configuration change
+rather than merely making it a convenient implementation detail.
 
 This is an Agent execution policy, not an OS-level sandbox or command parser.
 Operators that need a stronger project-specific runtime gate can use blocking

package/docs/setup.md

@@ -120,7 +120,9 @@ npx @akira-tl/forgerelay doctor
 ```
 
 The doctor command reports the resolved config, Node runtime, platform, Git,
-Bash, public URL, allowed hosts, and native SQLite dependency status.
+Bash, public URL, allowed hosts, native SQLite dependency status, and the MCP
+shape ForgeRelay will expose: tool mode, widget mode, one-hop proxy trust, and
+whether optional artifact, subagent, and Skill capabilities are enabled.
 
 ## Running from a local checkout
 

package/docs/versioning.md

@@ -168,7 +168,9 @@ npm publishing token.
    git push origin v0.2.0
    ```
 
-The tag push is the publication action.
+The tag push is the publication action. The release workflow publishes npm only after cloud CI passes, then extracts the matching `CHANGELOG.md` release section as the GitHub Release body. Keep `Unreleased` user-facing and structured (`Added`, `Changed`, `Fixed`, `Security`) because those notes are what users see on the Release page.
+
+Project release Hooks match the stable tag-push command as a substring of the ForgeRelay shell request. A compound command is allowed: when `commandRegex` matches `git push origin vX.Y.Z`, the Hook receives that matched command as `FORGERELAY_HOOK_PAYLOAD.command` and retains the complete shell request as `originalCommand` when they differ.
 
 ## Attribution guardrails
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -24,6 +24,7 @@
     "examples",
     "scripts",
     "skills",
+    "capabilities",
     "README.md",
     "CHANGELOG.md",
     "NOTICE.md"
@@ -34,14 +35,14 @@
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && npm run build:app && tsc -p tsconfig.build.json",
+    "build": "npm run clean && npm run build:app && tsc -p tsconfig.build.json && node scripts/ensure-cli-executable.mjs",
     "build:app": "vite build",
     "dev": "node scripts/debug/serve.mjs",
     "debug:serve": "node scripts/debug/serve.mjs",
     "debug:accept": "node scripts/debug/accept.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/logger.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/debug/accept.mjs

@@ -45,6 +45,18 @@ const { env } = createDebugEnvironment({
   hookLog,
   widgets: "full",
 });
+const doctor = spawnSync(process.execPath, ["--import", "tsx", "src/cli.ts", "doctor"], {
+  cwd: repoRoot,
+  env,
+  encoding: "utf8",
+});
+assert.equal(doctor.status, 0, doctor.stderr);
+assert.match(doctor.stdout, /Public base URL: http:\/\/127\.0\.0\.1:7677/);
+assert.match(doctor.stdout, /Tool mode: full/);
+assert.match(doctor.stdout, /Widgets: full/);
+assert.match(doctor.stdout, /Trust proxy: off/);
+pass("doctor resolved MCP shape", "public URL + tool/widgets/proxy state");
+
 const server = spawn(process.execPath, ["--import", "tsx", "src/cli.ts", "serve"], {
   cwd: repoRoot,
   env,
@@ -93,6 +105,9 @@ try {
   assert.match(serverInstructions, /Shell commands may modify ordinary project files/);
   assert.match(serverInstructions, /\/etc\/sudoers/);
   assert.match(serverInstructions, /configuration files through shell only when the user's request explicitly calls for that configuration change/);
+  assert.match(serverInstructions, /managed-worktrees capability guide/);
+  assert.ok(serverInstructions.length < 3_000, `server instructions should stay compact, got ${serverInstructions.length} characters`);
+  assert.doesNotMatch(serverInstructions, /fast-forwards the original target branch/);
   assert.doesNotMatch(serverInstructions, /Do not create or modify files with bash/);
   pass(
     "MCP initialize",
@@ -118,8 +133,10 @@ try {
     assert.ok(toolNames.includes(expected), `missing debug tool ${expected}`);
   }
   const bashTool = tools.find((tool) => tool.name === "bash");
-  assert.match(bashTool?.description ?? "", /may modify ordinary project files/);
-  assert.match(bashTool?.description ?? "", /\/etc\/sudoers/);
+  assert.match(bashTool?.description ?? "", /local user's authority/);
+  assert.doesNotMatch(bashTool?.description ?? "", /may modify ordinary project files/);
+  assert.doesNotMatch(bashTool?.description ?? "", /\/etc\/sudoers/);
+  assert.doesNotMatch(bashTool?.description ?? "", /external device or hardware mutations/);
   assert.doesNotMatch(bashTool?.description ?? "", /Do not use bash to create, move, rename, or delete project files/);
   assert.equal(bashTool?.inputSchema?.properties?.timeout, undefined);
   assert.match(bashTool?.description ?? "", /waits up to 300 seconds/);
@@ -138,6 +155,8 @@ try {
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.workspaceId);
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.newWorkspace);
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.staleWorkspaces);
+  assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityFingerprint);
+  assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityGuides);
   const templateUri = bashTool?._meta?.ui?.resourceUri;
   assert.match(
     templateUri ?? "",
@@ -154,7 +173,9 @@ try {
     method: "resources/list",
     params: {},
   }).message.result.resources;
-  assert.ok(resources.some((resource) => resource.uri === templateUri));
+  const currentResource = resources.find((resource) => resource.uri === templateUri);
+  assert.ok(currentResource);
+  assert.equal(currentResource._meta?.ui?.domain, debugBaseUrl);
   assert.ok(resources.some((resource) => resource.uri === "ui://forgerelay/workspace-app.html"));
 
   const resourceTemplates = mcpRequest(oauth.accessToken, sessionId, {
@@ -178,6 +199,7 @@ try {
   assert.equal(template.uri, templateUri);
   assert.equal(template.mimeType, "text/html;profile=mcp-app");
   assert.match(template.text ?? "", /<script type="module" crossorigin src="[^"]+\/mcp-app-assets\//);
+  assert.equal(template._meta?.ui?.domain, debugBaseUrl);
   assert.ok(template._meta?.ui?.csp?.resourceDomains?.includes(debugBaseUrl));
   const scriptUrl = template.text?.match(/<script type="module" crossorigin src="([^"]+)"/)?.[1];
   assert.ok(scriptUrl);
@@ -203,7 +225,35 @@ try {
   assert.match(workspaceId, /^ws_/);
   assert.equal(opened.structuredContent.root, checkoutWorkspace);
   assert.equal(opened.structuredContent.mode, "checkout");
-  pass("open_workspace", `${workspaceId} -> ${opened.structuredContent.root}`);
+  assert.deepEqual(opened.structuredContent.capabilityFingerprint, {
+    version: packageJson.version,
+    toolMode: "full",
+    capabilities: [
+      "workspace.close",
+      "worktree.managed",
+      "filesystem.rename-move",
+      "filesystem.delete",
+      "process.write-stdin",
+      "hooks.lifecycle",
+      "capability-guides.read",
+      "inspection.search-tools",
+      "ui.mcp-app",
+    ],
+  });
+  const capabilityGuides = opened.structuredContent.capabilityGuides;
+  assert.deepEqual(capabilityGuides.map((guide) => guide.name), [
+    "lifecycle-hooks",
+    "managed-worktrees",
+    "host-integration",
+    "shell-processes",
+  ]);
+  const hooksGuide = callTool(oauth.accessToken, sessionId, 78, "read", {
+    workspaceId,
+    path: capabilityGuides[0].path,
+  });
+  assert.match(hooksGuide.structuredContent.result, /BeforeTool/);
+  assert.match(hooksGuide.structuredContent.result, /BeforeWorktreeClose/);
+  pass("open_workspace", `${workspaceId} -> fingerprint + ${capabilityGuides.length} capability guides`);
 
   const written = callTool(oauth.accessToken, sessionId, 4, "write", {
     workspaceId,
@@ -620,8 +670,9 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
     [
       'import { writeFileSync } from "node:fs";',
       'const payload = process.env.FORGERELAY_HOOK_PAYLOAD ?? "{}";',
+      'const parsed = JSON.parse(payload);',
       'writeFileSync("release-ci-ran.txt", payload);',
-      'if (JSON.parse(payload).command === "git push origin v0.2.1") process.exit(17);',
+      'if (parsed.command === "git push origin v0.2.1") process.exit(17);',
       "",
     ].join("\n"),
   );
@@ -629,7 +680,7 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
     join(releaseProject, ".forgerelay", "hooks", "release-tag-local-ci.json"),
     JSON.stringify({
       event: "BeforeTool",
-      matcher: { tool: "bash", commandRegex: "^git push origin v0\\.2\\.[01]$" },
+      matcher: { tool: "bash", commandRegex: "git push origin v0\\.2\\.[01]" },
       command: "node .forgerelay/release-check.mjs",
       timeoutSeconds: 30,
       report: true,
@@ -647,11 +698,17 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
 
   const pushed = callTool(accessToken, sessionId, 12, "bash", {
     workspaceId: releaseWorkspaceId,
-    command: "git push origin v0.2.0",
+    command: "git status --short && git push origin v0.2.0 && echo release-pushed",
   });
   assert.equal(pushed.isError, undefined);
   assert.match(toolText(pushed), /release-tag-local-ci \(BeforeTool, project\) passed/);
   assert.ok(existsSync(join(releaseProject, "release-ci-ran.txt")));
+  assert.deepEqual(JSON.parse(readFileSync(join(releaseProject, "release-ci-ran.txt"), "utf8")), {
+    tool: "bash",
+    command: "git push origin v0.2.0",
+    workingDirectory: ".",
+    originalCommand: "git status --short && git push origin v0.2.0 && echo release-pushed",
+  });
   assert.equal(
     gitOutput(releaseRemote, ["rev-parse", "refs/tags/v0.2.0"], { gitDir: true }),
     gitOutput(releaseProject, ["rev-parse", "v0.2.0"]),
@@ -659,7 +716,7 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
 
   const blocked = callTool(accessToken, sessionId, 13, "bash", {
     workspaceId: releaseWorkspaceId,
-    command: "git push origin v0.2.1",
+    command: "git status --short && git push origin v0.2.1 && echo should-not-run",
   });
   assert.equal(blocked.isError, true);
   assert.match(toolText(blocked), /release-tag-local-ci.*failed/);

package/scripts/ensure-cli-executable.mjs

@@ -0,0 +1,12 @@
+import { chmodSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+if (process.platform !== "win32") {
+  const cliPath = fileURLToPath(new URL("../dist/cli.js", import.meta.url));
+  const currentMode = statSync(cliPath).mode;
+  chmodSync(cliPath, currentMode | 0o111);
+
+  if ((statSync(cliPath).mode & 0o111) === 0) {
+    throw new Error(`ForgeRelay CLI is not executable after build: ${cliPath}`);
+  }
+}

package/scripts/release-version.mjs

@@ -46,8 +46,20 @@ switch (command) {
     await prepareRelease(state, incrementVersion(state.pkg.version, bump), dryRun);
     break;
   }
+  case "notes": {
+    checkState(state);
+    if (!value) fail("usage: node scripts/release-version.mjs notes vX.Y.Z");
+    const version = value.startsWith("v") ? value.slice(1) : value;
+    if (!stableVersionPattern.test(version)) {
+      fail(`release notes version ${JSON.stringify(value)} must be vX.Y.Z or X.Y.Z`);
+    }
+    const body = getReleaseBody(state.changelog, version);
+    if (!body) fail(`CHANGELOG.md has no release notes for ${version}`);
+    process.stdout.write(`${body}\n`);
+    break;
+  }
   default:
-    fail(`unknown release command ${JSON.stringify(command)}; expected check, tag, or next`);
+    fail(`unknown release command ${JSON.stringify(command)}; expected check, tag, next, or notes`);
 }
 
 async function readState() {
@@ -182,6 +194,17 @@ function getUnreleasedBody(changelog) {
   return changelog.slice(bodyStart, bodyEnd).trim();
 }
 
+function getReleaseBody(changelog, version) {
+  const heading = `## [${version}]`;
+  const headingIndex = changelog.indexOf(heading);
+  if (headingIndex < 0) return "";
+  const headingEnd = changelog.indexOf("\n", headingIndex);
+  const bodyStart = headingEnd < 0 ? changelog.length : headingEnd + 1;
+  const nextHeadingIndex = changelog.indexOf("\n## [", bodyStart);
+  const bodyEnd = nextHeadingIndex < 0 ? changelog.length : nextHeadingIndex;
+  return changelog.slice(bodyStart, bodyEnd).trim();
+}
+
 function incrementVersion(version, bump) {
   const match = version.match(stableVersionPattern);
   if (!match) fail(`cannot increment invalid stable version ${JSON.stringify(version)}`);