@akira-tl/forgerelay 1.1.2 → 1.2.0

package/docs/configuration.md

@@ -1,7 +1,54 @@
 # Configuration Reference
 
 ForgeRelay can be configured through `forgerelay init`, persisted config files,
-or environment variables.
+or environment variables. ForgeRelay v1.2 uses one Config System v2 model for General Config, External MCP, Language Servers, Lifecycle Hooks, and Subagent Profiles.
+
+## Config System v2
+
+Canonical precedence is:
+
+```text
+runtime > project-local > project > user > built-in
+```
+
+Runtime CLI overrides environment values. A field participates only in scopes allowed by its Config Definition. Project Local is machine-private ForgeRelay state keyed by canonical Project identity; it is separate from Workspace identity and is not written into the checkout.
+
+Canonical v1.2 sources are:
+
+| Domain | User | Project | Project Local |
+| --- | --- | --- | --- |
+| General | `~/.forgerelay/config.json` | `<project>/.forgerelay/config.json` | `~/.forgerelay/projects/<project-id>/config.json` |
+| External MCP | `~/.forgerelay/mcp.json` | `<project>/.forgerelay/mcp.json` | `~/.forgerelay/projects/<project-id>/mcp.json` |
+| Language Servers | `~/.forgerelay/language-servers.json` | `<project>/.forgerelay/language-servers.json` | `~/.forgerelay/projects/<project-id>/language-servers.json` |
+| Lifecycle Hooks | `~/.forgerelay/hooks/*.json` | `<project>/.forgerelay/hooks/*.json` | `~/.forgerelay/projects/<project-id>/hooks/*.json` |
+| Subagent Profiles | `~/.forgerelay/subagents/*.md` | `<project>/.forgerelay/subagents/*.md` | `~/.forgerelay/projects/<project-id>/subagents/*.md` |
+
+The active config directory replaces `~/.forgerelay` when `FORGERELAY_CONFIG_DIR` is set. Credentials such as `auth.json` and `mcp-auth.json` are separate from ordinary Config Resolver precedence.
+
+Use the packaged v1 schemas under `schemas/v1/` for canonical JSON files. Supported sensitive fields may reference environment variables with `${ENV_NAME}`; interpolation is definition-controlled, not arbitrary string templating. Secret-safe diagnostics retain configured references where useful but redact resolved sensitive values.
+
+Canonical MCP, Language Server, Hook, and Subagent sources refresh on demand from content fingerprints rather than mtime. A previously valid source that becomes invalid keeps its in-process last-known-good value until repaired; deleting the source clears that contribution. Restart-required General settings expose configured-versus-applied state and never auto-restart ForgeRelay.
+
+Startup never rewrites legacy configuration. Inspect configuration with:
+
+```bash
+forgerelay config check
+forgerelay config sources
+forgerelay config explain <logical-path>
+```
+
+Use `--global`, `--project <path>`, and `--json` as needed. Explicit migration is separate:
+
+```bash
+forgerelay config migrate --dry-run --global
+forgerelay config migrate --dry-run --project /path/to/project
+forgerelay config migrate --global
+forgerelay config migrate --project /path/to/project
+```
+
+Migration is limited to ForgeRelay-owned legacy formats, creates backups, uses atomic writes, and preserves canonical shadowing/effective behavior. It does not import private Claude, Codex, Cursor, or other product configuration, and it does not move ForgeRelay-owned Skills into `.agents/skills`.
+
+Legacy ForgeRelay-owned parsers/paths remain readable with deprecation diagnostics through v1.2.x, receive stronger removal warnings in v1.3.x, and are removed in v1.4.0.
 
 ## Config directory
 
@@ -34,6 +81,10 @@ FORGERELAY_CONFIG_DIR=/path/to/config npx @akira-tl/forgerelay serve
 npx @akira-tl/forgerelay init
 npx @akira-tl/forgerelay serve
 npx @akira-tl/forgerelay doctor
+npx @akira-tl/forgerelay config check
+npx @akira-tl/forgerelay config sources
+npx @akira-tl/forgerelay config explain <logical-path>
+npx @akira-tl/forgerelay config migrate --dry-run --global
 npx @akira-tl/forgerelay config get
 npx @akira-tl/forgerelay config set publicBaseUrl https://forge.example.com/forgerelay/main,https://forge-alt.example.com/relay
 npx @akira-tl/forgerelay mcp list
@@ -184,13 +235,19 @@ New configuration uses a dedicated `mcp.json` file. The machine-wide registry is
 ~/.forgerelay/mcp.json
 ```
 
-or the equivalent path below `FORGERELAY_CONFIG_DIR`. A Workspace may add or override servers in:
+or the equivalent path below `FORGERELAY_CONFIG_DIR`. A Project may add or override servers in:
 
 ```text
-<workspace>/.forgerelay/mcp.json
+<project>/.forgerelay/mcp.json
+```
+
+Machine-private Project Local overrides live in:
+
+```text
+~/.forgerelay/projects/<project-id>/mcp.json
 ```
 
-Both files use this shape:
+All canonical MCP files use this shape:
 
 ```json
 {
@@ -213,9 +270,11 @@ Server names are stable lowercase identifiers matching `^[a-z][a-z0-9._-]{0,63}$
 Effective configuration is merged by server name in this order:
 
 ```text
-Project mcp.json > global mcp.json > legacy config.json.mcpServers
+Project Local > Project > User > legacy config.json.mcpServers
 ```
 
+Project Local lives under the ForgeRelay-private `projects/<project-id>/mcp.json` path and is never written into the checkout.
+
 A Project entry may explicitly hide an inherited server:
 
 ```json
@@ -228,15 +287,15 @@ A Project entry may explicitly hide an inherited server:
 }
 ```
 
-`disabled` defaults to `false` and normally does not need to be written. Removing the Project entry exposes the lower-precedence global/legacy server again. A complete server entry may also contain `"disabled": true`; ForgeRelay validates the entry but does not activate it.
+`disabled` defaults to `false` and normally does not need to be written. Removing a higher-scope entry exposes the lower-precedence Project/User/legacy server again. A complete server entry may also contain `"disabled": true`; ForgeRelay validates the entry but does not activate it.
 
-The historical `config.json -> mcpServers` object remains a deprecated read-compatible source. New configuration and documentation use `mcp.json`; the legacy source is retained for at least the next two feature-release compatibility windows and should not be used for new setups.
+The historical `config.json -> mcpServers` object remains a deprecated read-compatible source. New configuration and documentation use `mcp.json`. It remains readable with deprecation diagnostics in v1.2.x, receives stronger removal warnings in v1.3.x, and its legacy parser/path is removed in v1.4.0.
 
-ForgeRelay reloads global and Project `mcp.json` on demand before External MCP operations. A valid changed file becomes visible to the next `servers`, `tools`, or `call` operation without restarting ForgeRelay. Each operation uses one immutable snapshot, so an in-flight call is not switched underneath itself. If a previously valid source becomes invalid, that running ForgeRelay process keeps the whole previous valid source as last-known-good and reports a bounded diagnostic; no partially parsed subset is activated. A fresh CLI process cannot reconstruct another process's in-memory last-known-good snapshot, so it reports the invalid source while noting that an existing runtime may still be using its prior valid snapshot.
+ForgeRelay reloads canonical User, Project, and Project Local `mcp.json` sources on demand before External MCP operations. A valid changed file becomes visible to the next `servers`, `tools`, or `call` operation without restarting ForgeRelay. Each operation uses one immutable snapshot, so an in-flight call is not switched underneath itself. If a previously valid source becomes invalid, that running ForgeRelay process keeps the whole previous valid source as last-known-good and reports a bounded diagnostic; no partially parsed subset is activated. A fresh CLI process cannot reconstruct another process's in-memory last-known-good snapshot, so it reports the invalid source while noting that an existing runtime may still be using its prior valid snapshot.
 
 ### External MCP transports and authentication
 
-A stdio server supports `command`, optional `args`, `env`, and `cwd`. It is launched directly, not through a shell. Its process still runs with the operating-system authority of the user running ForgeRelay. A Project `.forgerelay/mcp.json` can therefore introduce executable project configuration; opening an allowed project is the trust boundary, and ForgeRelay does not add a second per-server approval prompt.
+A stdio server supports `command`, optional `args`, `env`, and `cwd`. It is launched directly, not through a shell. Its process still runs with the operating-system authority of the user running ForgeRelay. A Project `.forgerelay/mcp.json` can therefore introduce executable project configuration. Allowed roots grant filesystem/Workspace authority, not Project Trust approval. v1.2.0 routes this execution through the shared Project trust seam under compatibility-allow; there is no second per-server prompt and no claim of a complete interactive Project Trust UX.
 
 A Streamable HTTP server supports `url` and optional static `headers`:
 
@@ -260,7 +319,7 @@ ForgeRelay does not require every HTTP MCP server to use OAuth. The effective mo
 - static credentials: user-managed `headers` for HTTP or `env` for stdio;
 - interactive OAuth: explicitly initiated by a human through the CLI.
 
-Do not commit static secrets in Project `mcp.json`. ForgeRelay does not move project-defined header/env secrets into a separate secret manager in v1.1.1.
+Do not commit static secrets in Project `mcp.json`. Config v2 supports definition-controlled `${ENV_NAME}` references in supported sensitive fields, but ForgeRelay does not turn arbitrary project-defined header/env values into a separate secret manager.
 
 Interactive OAuth state is stored only in the machine-private:
 
@@ -319,7 +378,7 @@ forgerelay mcp test <server>
 forgerelay doctor
 ```
 
-`mcp list` is passive: it reports the resolved Project/global/legacy sources, disabled entries, authentication state, credential-store health, and invalid/last-known-good configuration diagnostics. With no explicit scope it uses the active Workspace root when supplied by ForgeRelay, otherwise walks upward from the current directory for the nearest `.forgerelay/mcp.json`; `--project` selects a Project explicitly and `--global` excludes Project configuration.
+`mcp list` is passive: it reports the resolved Project Local/Project/User/legacy sources, disabled entries, authentication state, credential-store health, and invalid/last-known-good configuration diagnostics. With no explicit scope it uses the active Workspace root when supplied by ForgeRelay, otherwise walks upward from the current directory for the nearest `.forgerelay/mcp.json`; `--project` selects a Project explicitly and `--global` excludes Project and Project Local configuration.
 
 `mcp test` is the active probe. It connects to the selected server and performs tool discovery, reporting source, transport, auth state, negotiated MCP era/version, tool count, and actionable failures such as authentication required, unreachable transport, or tool discovery failure.
 
@@ -458,12 +517,14 @@ while semantic work is active. Debug `runtime_resources` telemetry includes only
 aggregate Language-service/process/request/document/diagnostic/stderr counts; it
 does not log source contents or source paths.
 
-Effective Language-server definitions resolve in this order:
+Effective Language-server definitions resolve through Config v2 in this order:
+
+1. Project Local `projects/<project-id>/language-servers.json`;
+2. Project `.forgerelay/language-servers.json`;
+3. User `language-servers.json` in the active ForgeRelay config directory;
+4. built-in discovery for known executables.
 
-1. project configuration in `.forgerelay/language-servers.json`;
-2. global definitions from the `languageServers` object in
-   `~/.forgerelay/config.json`;
-3. built-in discovery for known executables.
+Legacy `config.json.languageServers` remains read-compatible with deprecation diagnostics in v1.2.x and is removed in v1.4.0.
 
 A project configuration file is an object keyed by definition name. Definitions
 use structured process launch and never go through a shell:
@@ -487,25 +548,11 @@ use structured process launch and never go through a shell:
 }
 ```
 
-Global configuration uses the same definition shape under `languageServers`. ForgeRelay can also keep optional npm-managed Language Servers under its private config directory. Agent-triggered installation is disabled by default and must be explicitly enabled:
-
-```json
-{
-  "languageServers": {
-    "typescript": {
-      "command": "/absolute/path/to/typescript-language-server",
-      "args": ["--stdio"]
-    }
-  },
-  "allowAgentLanguageServerInstall": false
-}
-```
+User configuration uses the same definition shape in the active config directory's `language-servers.json`. ForgeRelay can also keep optional npm-managed Language Servers under its private config directory. Agent-triggered installation is disabled by default and must be explicitly enabled through General Config, for example `"allowAgentLanguageServerInstall": false` in `config.json`.
 
-`forgerelay init` can manage TypeScript/JavaScript and Pyright installations without touching global npm. When `allowAgentLanguageServerInstall` is `true`, an Agent may use `code.intelligence` operations `managed.status` and `managed.install`; successful installs become discoverable by the same running ForgeRelay process on the next semantic request, with no restart required. Rust Analyzer, `gopls`, and `clangd` remain external toolchain/system installations.
+`forgerelay init --advanced` can manage TypeScript/JavaScript and Pyright installations without touching global npm. Basic `forgerelay init` does not install Language Servers. When `allowAgentLanguageServerInstall` is `true`, an Agent may use `code.intelligence` operations `managed.status` and `managed.install`; successful installs become discoverable by the same running ForgeRelay process on the next semantic request, with no restart required. Rust Analyzer, `gopls`, and `clangd` remain external toolchain/system installations.
 
-Explicit configuration can set `"enabled": false` to suppress the matching
-built-in definition. Project values override global values, and both override
-built-in defaults. ForgeRelay resolves a Language project by walking ancestors of
+Explicit legacy configuration can still normalize historical `"enabled": false`; canonical keyed definitions use the current Config v2 shape and scope semantics. Project Local overrides Project, Project overrides User, and all canonical explicit definitions override built-in defaults. ForgeRelay resolves a Language project by walking ancestors of
 the requested source file according to that definition's `projectMarkers`; it does
 not recursively scan the Workspace.
 
@@ -703,7 +750,7 @@ change the Activity snapshot/query contract.
 
 ## Lifecycle hooks
 
-Hooks v1 是自动生命周期规则。规则由用户或 Agent 主动写入；命中后 ForgeRelay 直接执行，不再增加批准步骤。
+Hooks v1.2 是自动生命周期规则。规则由用户或 Agent 主动写入；Project Hook 属于 executable project configuration，并在 v1.2.0 通过统一 Project execution trust seam 后按 compatibility-allow 执行。当前版本没有完整交互式 Project Trust approval UI。
 
 首选格式是 **一个 Hook 一个 JSON 文件**。全局 Hook 放在当前 ForgeRelay 配置目录的 `hooks/` 下，新安装通常是：
 
@@ -711,15 +758,21 @@ Hooks v1 是自动生命周期规则。规则由用户或 Agent 主动写入；
 ~/.forgerelay/hooks/<hook-name>.json
 ```
 
-项目 Hook 放在工作区根目录：
+Project Hook 放在项目根目录：
+
+```text
+<project>/.forgerelay/hooks/<hook-name>.json
+```
+
+Project Local Hook 位于机器私有：
 
 ```text
-<workspace>/.forgerelay/hooks/<hook-name>.json
+~/.forgerelay/projects/<project-id>/hooks/<hook-name>.json
 ```
 
 文件名去掉 `.json` 后就是 Hook 名，也是日志和 Agent-visible report 中显示的名称。例如 `release-tag-gate.json` 会显示为 `release-tag-gate`。目录内按文件名字典序执行；需要显式排序时可以使用 `10-release-verify.json`、`20-package-inspection.json` 这样的前缀。ForgeRelay 只读取普通 `*.json` 文件，所以临时停用某条 Hook 时可以把扩展名改掉。
 
-全局 Hook 在 server 启动时读取，修改后需要重启 ForgeRelay；项目目录在每次事件时重新读取，所以 Agent 修改项目 Hook 后不需要重启。全局规则先执行，项目规则随后执行，两边都只做追加，不互相覆盖。
+Canonical User / Project / Project Local Hook sources all refresh on demand in v1.2. Changes do not require a ForgeRelay restart. Resolution follows Config v2 scope precedence, while directory entries keep deterministic file ordering. A previously valid Hook file that becomes invalid keeps its per-file in-process last-known-good until repaired; deleting the file removes that contribution.
 
 每个独立 Hook 文件只描述一条规则：
 
@@ -750,7 +803,7 @@ Hooks v1 是自动生命周期规则。规则由用户或 Agent 主动写入；
 
 独立文件不写 `name`：文件名就是唯一的 Hook 名。一个逻辑 Hook 如果需要多个独立步骤，拆成多个文件；这样可以单独启停、重命名、排序和审查每一步。
 
-为兼容已有配置，ForgeRelay 仍接受旧的 `config.json -> hooks`、全局 `hooks.json` 和项目 `.forgerelay/hooks.json` 聚合格式。执行顺序是旧配置在前、`hooks/*.json` 独立文件在后。新配置应优先使用独立文件。
+为兼容已有配置，ForgeRelay 在 v1.2.x 仍接受旧的 `config.json -> hooks`、全局 `hooks.json` 和项目 `.forgerelay/hooks.json` 聚合格式，并通过同一个 Config Resolver 规范化后产生 deprecation diagnostics；canonical `hooks/*.json` 在同 scope 下优先于对应 legacy source。v1.3.x 会加强 removal warning，legacy parser/path 在 v1.4.0 移除。新配置应只使用独立文件。
 
 若某个项目 Hook 文件 JSON 或 schema 无效，ForgeRelay 会返回 `Project hooks config` diagnostic，同时继续加载其他有效项目 Hook，并保持 workspace/tool 可用，让 Agent 可以直接修复出错文件。
 
@@ -868,12 +921,17 @@ Standard Agent Skills are discovered in precedence order from:
 - `FORGERELAY_AGENT_DIR/skills`
 - paths from `FORGERELAY_SKILL_PATHS`
 
+The ownership boundaries are different even though all of these are readable Skill sources. Project/global `.agents/skills` belong to the open Agent Skills ecosystem and may contain files or symlinks installed by other Agent tooling. ForgeRelay-owned Skills stay under the active ForgeRelay config directory (`~/.forgerelay/skills` by default); ForgeRelay does not migrate or install its private Skills into `~/.agents/skills`.
+
 When the same Skill name appears in more than one source, the first source wins. Project Skills therefore override same-named global `~/.agents/skills` entries, matching ForgeRelay's project-over-global configuration model.
 
-When subagents are enabled, profiles are discovered from:
+When subagents are enabled, canonical v1.2 profiles are discovered from:
+
+- the active ForgeRelay config directory's `subagents/*.md`;
+- project `.forgerelay/subagents/*.md`;
+- machine-private Project Local `projects/<project-id>/subagents/*.md`.
 
-- the active ForgeRelay config directory's `agents/*.md`;
-- project `.forgerelay/agents/*.md`.
+Legacy `agents/*.md` remains read-compatible in v1.2.x with deprecation diagnostics and is scheduled for removal in v1.4.0. ForgeRelay does not import provider-private profile/config directories.
 
 
 ForgeRelay does not install or bundle coding-agent executors. Subagent providers

package/docs/gotchas.md

@@ -120,6 +120,20 @@ Regenerate setup intentionally with:
 forgerelay init --force
 ```
 
+## Config v2 says a value is invalid, shadowed, or missing
+
+Use the Config v2 inspection surface before editing files by guesswork:
+
+```bash
+forgerelay config check --project /path/to/project
+forgerelay config sources --project /path/to/project
+forgerelay config explain <logical-path> --project /path/to/project
+```
+
+Project Local sources are machine-private under the ForgeRelay config directory and can override Project/User sources without appearing in the checkout. Running ForgeRelay may keep an in-memory last-known-good value for a hot-reload source that has since become invalid; a fresh offline CLI process cannot reconstruct another process's LKG.
+
+Startup does not rewrite old formats. Preview migration with `forgerelay config migrate --dry-run --global` or `--project <path>`, then run the same command without `--dry-run` only after reviewing the backup-preserving plan. ForgeRelay-owned legacy parsers/paths remain in v1.2.x, warn more strongly in v1.3.x, and are removed in v1.4.0.
+
 ## Unknown `workspaceId`
 
 Reopen the project with `open_workspace` and use the returned ID. Active
@@ -180,12 +194,14 @@ FORGERELAY_SKILLS=1 forgerelay serve
 
 Standard paths include:
 
-- `~/.agents/skills`
 - project `.agents/skills`
-- active ForgeRelay config `skills` directory
+- `~/.agents/skills`
+- active ForgeRelay config `skills` directory (`~/.forgerelay/skills` by default)
 - `FORGERELAY_AGENT_DIR/skills`
 - additional `FORGERELAY_SKILL_PATHS`
 
+`.agents/skills` is an external/open Agent Skill source and may contain symlinks managed by other Agent tooling. ForgeRelay-owned Skills belong under its own config `skills` directory and must not be migrated into `.agents/skills`.
+
 ## Subagent profiles do not appear
 
 Enable subagents:
@@ -194,13 +210,16 @@ Enable subagents:
 FORGERELAY_SUBAGENTS=1 forgerelay serve
 ```
 
-New profile locations include:
+Canonical v1.2 profile locations are:
 
 ```text
-~/.forgerelay/agents/*.md
-.forgerelay/agents/*.md
+~/.forgerelay/subagents/*.md
+<project>/.forgerelay/subagents/*.md
+~/.forgerelay/projects/<project-id>/subagents/*.md
 ```
 
+Legacy `agents/*.md` remains read-compatible in v1.2.x with deprecation diagnostics and is removed in v1.4.0.
+
 `forgerelay agents ls` lists sessions, not profile definitions. The compact
 profile catalog is returned through `open_workspace`.
 

package/docs/security.md

@@ -39,6 +39,17 @@ 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.
 
+Allowed roots are filesystem/Workspace authority, not a Project Trust approval.
+They determine which projects ForgeRelay may open; they do not by themselves mean
+that executable project configuration has passed a separate trust prompt.
+
+v1.2.0 routes executable Project Hooks, stdio External MCP entries, Project
+Language Servers, and Project Subagent Profiles through one Project execution
+trust seam. The initial policy is deliberately **compatibility-allow**: v1.2.0
+does not ship a full interactive Project Trust approval UI. Later v1.2.x work can
+strengthen approval/enforcement at this seam without giving each execution
+subsystem a different trust model.
+
 ## Owner-password OAuth
 
 New installations store local configuration in:
@@ -149,9 +160,9 @@ policy because they are lifecycle gates rather than user-command execution.
 
 ## External MCP configuration and credentials
 
-External MCP extends the same local-authority model rather than creating a sandbox. Machine-wide servers live in the ForgeRelay config directory's `mcp.json`; Project servers may live in `<workspace>/.forgerelay/mcp.json`. A Project stdio entry can launch a configured executable with the same operating-system user authority as ForgeRelay, so Project MCP configuration is executable project configuration. ForgeRelay does not add a second per-server approval prompt after the operator has allowed and opened that project root.
+External MCP extends the same local-authority model rather than creating a sandbox. Machine-wide servers live in the ForgeRelay config directory's `mcp.json`; Project servers may live in `<workspace>/.forgerelay/mcp.json`, while Project Local servers stay under ForgeRelay-private `projects/<project-id>/mcp.json`. A Project stdio entry can launch a configured executable with the same operating-system user authority as ForgeRelay, so Project MCP configuration is executable project configuration. In v1.2.0 it passes through the shared Project trust seam under compatibility-allow; ForgeRelay does not add a second per-server prompt, and this must not be confused with a full Project Trust approval UX.
 
-Static HTTP headers and stdio environment values are user-managed configuration. Do not commit secrets in Project `mcp.json`; v1.1.1 does not automatically extract project-defined secrets into a secret manager.
+Static HTTP headers and stdio environment values are user-managed configuration. Do not commit secrets in Project `mcp.json`. Config v2 supports definition-controlled `${ENV_NAME}` references for supported sensitive fields, but it does not turn project-defined secrets into a general secret manager.
 
 Interactive External MCP OAuth credentials are different. They are kept in the machine-private ForgeRelay config directory:
 
@@ -169,7 +180,7 @@ External MCP result references are not implicitly dereferenced. Paths, URLs and
 
 Hook command 是本地代码执行，使用与 ForgeRelay 相同的操作系统用户权限并继承进程环境。
 
-Hooks v1 有两个自动作用域：当前 ForgeRelay 配置目录中的 `hooks/<hook-name>.json` 全局规则，以及 workspace 根目录的 `.forgerelay/hooks/<hook-name>.json` 项目规则。项目规则不需要额外批准；打开允许根目录中的项目时，ForgeRelay 会把这些 Hook 当作该开发环境的执行约定直接使用，`WorkspaceOpen` 也可以立即触发命令。因此 allowed roots 不只是文件访问边界，也界定了你愿意让 ForgeRelay 操作的本地项目环境。
+Hooks v1.2 有三个 canonical scope：当前 ForgeRelay 配置目录中的 `hooks/<hook-name>.json` User 规则、Project 根目录的 `.forgerelay/hooks/<hook-name>.json`，以及 ForgeRelay-private `projects/<project-id>/hooks/<hook-name>.json` Project Local 规则。Project Hook 属于可执行项目配置；v1.2.0 通过统一 Project trust seam 后采用 compatibility-allow。Allowed roots 仍只是文件系统/Workspace authority，不能描述成 Project Trust approval。
 
 每个独立 Hook 文件只声明一个 event、可选 matcher 和一个 command，以及 timeout/report。文件名只决定 Hook 名和排序，不能扩大 allowed roots、修改 OAuth 配置或删除全局规则。全局与项目规则采用组合关系。若某个项目 Hook 文件损坏，ForgeRelay 返回可见 diagnostic、跳过该无效文件并继续加载其他有效 Hook，同时保持工具可用，便于 Agent 修复。旧聚合格式仍兼容。
 

package/docs/setup.md

@@ -8,7 +8,7 @@ projects through ForgeRelay.
 - Node `>=22.19 <27`
 - npm
 - Git
-- Bash, including Git Bash or WSL on Windows
+- a supported Command Shell Runtime: Bash/zsh/POSIX sh on Unix-like systems, or PowerShell 7 / Windows PowerShell 5.1 / `cmd.exe` on Windows
 - a public HTTPS URL when the MCP host cannot connect directly to localhost
 
 ForgeRelay does not create the public tunnel for you. Use Cloudflare Tunnel,
@@ -22,8 +22,11 @@ Run:
 npx @akira-tl/forgerelay init
 ```
 
-The setup flow asks for the allowed project roots, local port, public domains,
-and an optional routed path prefix.
+Basic setup asks only for the allowed project roots and how clients reach this ForgeRelay instance (local, SSH relay, direct LAN, or HTTPS proxy/tunnel). It asks connection-specific details only when that mode requires them.
+
+Use `npx @akira-tl/forgerelay init --advanced` for the small set of common advanced choices: port, Command Shell Runtime, Runtime Shell Instructions opt-in, ForgeRelay-managed Language Servers, and whether Agents may install managed Language Servers on demand. Runtime Shell Instructions are disabled unless explicitly enabled.
+
+`init --force` updates setup-owned fields only. It does not migrate legacy configuration or erase unrelated advanced settings.
 
 ### Project roots
 
@@ -123,12 +126,14 @@ Keep `auth.json` private.
 
 ```bash
 npx @akira-tl/forgerelay doctor
+npx @akira-tl/forgerelay config check
+npx @akira-tl/forgerelay config sources
+npx @akira-tl/forgerelay config explain <logical-path>
 ```
 
-The doctor command reports the resolved config, Node runtime, platform, Git,
-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.
+`doctor` reports the runtime and deployment summary. Config v2's `check`, `sources`, and `explain` commands validate the selected scope and show provenance without executing Hooks, starting Language Servers/stdio MCP servers, or exposing resolved sensitive values.
+
+ForgeRelay never rewrites old configuration during startup. Preview an explicit migration with `forgerelay config migrate --dry-run --global` or `--project <path>` before applying it. ForgeRelay-owned legacy sources remain compatible in v1.2.x and are removed in v1.4.0.
 
 ## Running from a local checkout
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -24,6 +24,8 @@
     "examples",
     "scripts",
     "capabilities",
+    "templates",
+    "schemas",
     "README.md",
     "CHANGELOG.md",
     "NOTICE.md"
@@ -34,7 +36,9 @@
   },
   "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 && node scripts/ensure-cli-executable.mjs",
+    "build": "npm run config:schema:check && npm run clean && npm run build:app && tsc -p tsconfig.build.json && node scripts/ensure-cli-executable.mjs",
+    "config:schema:generate": "node --import tsx scripts/config/schema.mjs write",
+    "config:schema:check": "node --import tsx scripts/config/schema.mjs check",
     "build:app": "vite build",
     "dev": "node scripts/debug/serve.mjs",
     "debug:serve": "node scripts/debug/serve.mjs",
@@ -48,9 +52,14 @@
     "powershell51:accept": "node scripts/ci/powershell51-acceptance.mjs",
     "cmd:accept": "node scripts/ci/cmd-acceptance.mjs",
     "windows:product-accept": "node scripts/ci/windows-product-acceptance.mjs",
+    "config:product-accept": "node scripts/ci/config-v2-product-acceptance.mjs",
     "wiki:check": "node scripts/wiki/sync.mjs check",
     "wiki:publish": "node scripts/wiki/sync.mjs publish",
     "architecture:check": "node scripts/ci/architecture.mjs",
+    "ci:contract": "node scripts/ci/gates/core-contract.mjs",
+    "ci:test-shard": "node scripts/ci/gates/test-shard.mjs",
+    "ci:platform-tests": "node scripts/ci/gates/platform-tests.mjs",
+    "ci:prepare-windows-product": "node scripts/ci/gates/prepare-windows-product.mjs",
     "ci:verify": "node scripts/ci/verify.mjs",
     "release:parity": "node scripts/release-parity.mjs",
     "release:pack": "node scripts/release/pack.mjs",
@@ -58,7 +67,7 @@
     "release:push-ready": "node scripts/release/push-ready.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/workspaces/relay/tests/recovery.test.ts && tsx src/workspaces/relay/tests/checkpoint.test.ts && tsx src/runtime/config/config.test.ts && tsx src/runtime/config/external-mcp-registry.test.ts && tsx src/runtime/config/external-mcp-auth-store.test.ts && tsx src/mcp/operations/external-mcp/external-mcp-oauth.test.ts && tsx src/cli/mcp/status.test.ts && tsx src/cli/mcp/diagnostics.test.ts && tsx src/cli/mcp/external-mcp.test.ts && tsx src/runtime/shell/command-shell-runtime.test.ts && tsx src/runtime/instructions/shell-instructions.test.ts && tsx src/runtime/instructions/powershell-skill.test.ts && tsx src/cli/shell/setup.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/runtime/state/runtime-lease.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-context.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/mcp/server/operations/hooks.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/git/worktree-recovery.test.ts && tsx src/mcp/server/workspace/workspace-inventory.test.ts && tsx src/mcp/server/workspace/workspace-recovery.test.ts && tsx src/mcp/server/workspace/workspace-checkpoint.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/maintenance.test.ts && tsx src/cli/maintenance-prune.test.ts && tsx src/cli/cli.test.ts",
+    "test": "node --test scripts/debug/runtime.test.mjs scripts/config/schema-text.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/workspaces/relay/tests/recovery.test.ts && tsx src/workspaces/relay/tests/checkpoint.test.ts && tsx src/runtime/config/definition/schema.test.ts && tsx src/runtime/config/resolution/resolver.test.ts && tsx src/runtime/security/project-execution-trust.test.ts && tsx src/runtime/config/resolution/hooks.test.ts && tsx src/workspaces/state/project-context.test.ts && tsx src/runtime/config/config.test.ts && tsx src/runtime/config/external-mcp-registry.test.ts && tsx src/runtime/config/external-mcp-auth-store.test.ts && tsx src/mcp/operations/external-mcp/external-mcp-oauth.test.ts && tsx src/cli/mcp/status.test.ts && tsx src/cli/mcp/diagnostics.test.ts && tsx src/cli/mcp/external-mcp.test.ts && tsx src/runtime/shell/command-shell-runtime.test.ts && tsx src/runtime/instructions/shell-instructions.test.ts && tsx src/runtime/instructions/powershell-skill.test.ts && tsx src/cli/shell/setup.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/operations/project-trust.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/runtime/state/runtime-lease.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/hooks/hooks-trust.test.ts && tsx src/mcp/operations/external-mcp/external-mcp-transform.test.ts && tsx src/mcp/hooks/external-mcp-transform-trust.test.ts && tsx src/mcp/operations/external-mcp/external-mcp-trust.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-context.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/mcp/server/operations/hooks.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/project-trust.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/git/worktree-recovery.test.ts && tsx src/mcp/server/workspace/workspace-inventory.test.ts && tsx src/mcp/server/workspace/workspace-recovery.test.ts && tsx src/mcp/server/workspace/workspace-checkpoint.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/maintenance.test.ts && tsx src/cli/maintenance-prune.test.ts && tsx src/cli/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/schemas/v1/config.project-local.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "Editor-only JSON Schema URL. Ignored by ForgeRelay resolution.",
+      "type": "string"
+    }
+  },
+  "additionalProperties": false,
+  "$id": "https://raw.githubusercontent.com/Akira-TL/forgerelay/main/schemas/v1/config.project-local.schema.json",
+  "title": "ForgeRelay general configuration (project-local)",
+  "description": "Canonical ForgeRelay general configuration. Domain-specific MCP, Language Server, Hook, Subagent, and credential settings use separate sources."
+}

package/schemas/v1/config.project.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "Editor-only JSON Schema URL. Ignored by ForgeRelay resolution.",
+      "type": "string"
+    }
+  },
+  "additionalProperties": false,
+  "$id": "https://raw.githubusercontent.com/Akira-TL/forgerelay/main/schemas/v1/config.project.schema.json",
+  "title": "ForgeRelay general configuration (project)",
+  "description": "Canonical ForgeRelay general configuration. Domain-specific MCP, Language Server, Hook, Subagent, and credential settings use separate sources."
+}