> ## Documentation Index
> Fetch the complete documentation index at: https://forgekit-docs-mintlify-9e781f1d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Core 命令

> 用 init、sync、doctor、catalog、docs 与 update 引导并维护 Forge 仓库，涵盖 profile、settings、可逆卸载相关标志，无效 profile 中止行为，以及 FORGE_GUARD_STRICT 严格模式的说明。

Core 分组用于引导一个仓库并保持它的健康。

## `forge init`

搭起本仓库的配置 —— 从同一份共享来源为每个工具输出配置。

```bash theme={null}
forge init
```

输出 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等文件
（外加给 Roo Code 和 VS Code 的 MCP 服务器配置），以及账本所需的
`.gitattributes` union-merge 规则。

`forge init` 还会把 Forge 的 hooks 和 permissions 合并进**全局**的
`~/.claude/settings.json`，所以它会在写入前先声明这次合并。这次合并是幂等的、
带标记守护的，永远不会覆盖用户自己的条目。

### Init 标志

| 标志                  | 作用                                                                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile <name>`  | 为本仓库挑选策略 profile。可取 `minimal` 或 `standard`（默认）。无效值会在任何脚手架、`.forge/` 写入或合并动作之前直接中止。                                                     |
| `--no-settings`     | 完全跳过对全局 `~/.claude/settings.json` 的合并 —— 只写仓库级配置。                                                                                      |
| `--remove-settings` | 撤销以往的一次 settings 合并。Forge 形状的 hooks、permissions、statusline 和 `_forge` 标记会被移除；会先写入一份带时间戳的备份，你自己的条目保持不动。也会被 `install.sh --uninstall` 调用。 |
| `--settings-only`   | 只合并全局 settings —— 不动仓库。被 `install.sh` 用来接线 hooks 和 permissions。                                                                        |

如果 settings 合并被拒绝或出错，`forge init` 会以 exit 1 失败并把原因写到 stderr，
而不是谎报成功。

### 策略 profile

`--profile` 用来选那套规则集，`forge sync` 会把它编译成每个工具的原生配置。
只支持两种 profile：

* **`standard`**（默认）—— 完整包：共享记忆规则、影响分析，以及完整的护栏 hook 集。
* **`minimal`** —— 更精简的规则集，给小仓库或贡献者 fork 用。

旧名字 `web-app`、`backend-service`、`library` 和 `regulated` 都是 `standard` 的
弃用别名。它们仍然能用：`forge init` 会警告一次、把 `standard` 存下来，已有的、
仍然拿旧名字的配置会按 standard 同步。新仓库应直接用 `standard`。其它任何值都是
无效的，会在 Forge 动仓库之前中止。

```bash theme={null}
forge init --profile minimal            # leaner ruleset
forge init --no-settings                # per-repo only, skip the global merge
forge init --remove-settings            # reverse a past global merge
```

## `forge sync`

把规范来源重新编译成每个工具的原生配置文件。

```bash theme={null}
forge sync
```

幂等 —— 只重写发生变化的部分。在编辑 `source/rules.json` 或
仓库级的 `.forge/rules.json` 之后运行它。

## `forge doctor`

对已安装工具、护栏、MCP 认证和配置漂移做健康检查。

```bash theme={null}
forge doctor
```

对工具、护栏、MCP 接线、配置漂移和更新状态做通过/失败检查。所有路径
都是 fail-open。当配置了自定义网关时，**gateway models** 一行会打印
出解析后的 `tier → model` 映射。

## `forge catalog`

Start Here —— 列出每个工具、crew 和护栏，附上一行原因。

```bash theme={null}
forge catalog
```

## `forge docs`

文档 ↔ 代码漂移。

```bash theme={null}
forge docs check     # registry reconcile — commands, env vars, MCP tools, CHANGELOG
forge docs sync      # diff-driven stale-docs sweep
```

<Note>
  当命令、环境变量、MCP 工具或 CHANGELOG 相对代码发生漂移时，`docs check` 会让 CI
  失败。`docs sync` 扫描 diff，并报告 UPDATED / STALE / VERIFIED-UNAFFECTED。
</Note>

## `forge update`

跨三种安装方式的自更新。

```bash theme={null}
forge update              # apply the update (git checkout or npm/copy install)
forge update --check      # report whether a newer version is available
forge update --to <version>   # pin or downgrade to a specific version (v0.19+)
```

所有路径都是 fail-open —— 离线、无上游或 detached HEAD 都会返回"unknown"，
永远不会报错。`FORGE_NO_UPDATE_CHECK=1` 让 doctor 的提示安静下来。