agents-gitflow-guard 0.0.19 → 0.0.21

package/README.md

@@ -40,48 +40,58 @@ You define your own branches —
 
 ```bash
 # DSH — in-process plugin; restart DSH afterwards (plugins load at startup)
-dsh plugin --profile web add agents-gitflow-guard@0.0.19
+dsh plugin --profile web add agents-gitflow-guard@0.0.21
 ```
 
 ```bash
 # Claude Code · Codex · OpenCode · Antigravity — standalone hooks, no DSH needed
-npm i -g agents-gitflow-guard@0.0.19
+npm i -g agents-gitflow-guard@0.0.21
 ```
 
 ```bash
 # Pi — in-process extension
-npm i -D agents-gitflow-guard@0.0.19
+npm i -D agents-gitflow-guard@0.0.21
 ```
 
 > **Version gotcha**: a bare `add` or unpinned `npm i` resolves whatever `latest` is at install time — on machines behind a stale npm/pnpm registry cache or mirror it may install an old version. If the installed version looks wrong, pin it explicitly. (DSH users: the pnpm peer-dependency *warning* is expected — DSH supplies `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools` through its shared profile module fallback at startup; the plugin works normally.)
 >
-> The hook clients (Claude Code · Codex · OpenCode · Antigravity) and Pi need one wiring step after install — walk the per-agent table in [Installation in detail](#installation-in-detail).
+> The hook clients (Claude Code · Codex · OpenCode · Antigravity) need one wiring step after install — **one command per client** (below). Pi needs a copy step; DSH is already wired by install.
 
-**Step 2 — configure**, create `gitflow-guard.config.json` in your **project root**:
+**Step 2 — wire your client (no config file needed).** The guard ships with **built-in defaults that protect `develop` (integration) + `main` (archive)** — zero configuration, on by default. The only thing you need is to tell your AI client to invoke the guard, with one command per stdin-hook client (DSH is wired automatically; Pi just copies a file, see below):
 
-```jsonc
-{
-  "enabled": true,
-  "featurePattern": "feature/[\\w-]+",
-  "branches": {
-    "integration": ["develop"],   // integration: features merge in via PR, protected
-    "archive": ["main"]           // archive: archived by you after release
-  }
-}
+```bash
+# Claude Code → this repo's .claude/settings.json
+gitflow-guard wire --client claude --project --yes
+```
+
+```bash
+# Codex / OpenCode / Antigravity (each its own config file; --yes skips the y/N prompt)
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes     # experimental
+```
+
+```bash
+# Preview (no writes) / remove / interactive guide:
+gitflow-guard wire --client claude --dry-run
+gitflow-guard wire --client claude --unwire
+gitflow-guard setup
 ```
 
-This one file is the entire setup: `integration` is the **only required** role; `preview` / `production` / `archive` are optional — add them only if your flow needs them. The plugin is opt-in per project — absent or `enabled: false`, it does nothing.
+`wire` merges into your existing config **non-destructively** (already-present hooks are left untouched), and writes to your **project dir by default** — `--global` (all repos on this machine) always asks first or needs `--yes`. Per-client files and formats are mirrored in [Installation in detail](#installation-in-detail).
+
+> ⚠️ **main is protected by default.** Trunk / single-branch users (everyone pushes straight to one branch) will get blocked on direct `main` pushes until they opt out — create `gitflow-guard.config.json` with `{ "enabled": false }`, or map your own branches (see [Configuration Reference](#configuration-reference)). `gitflow-guard status` repeats this notice whenever the built-in defaults are in effect.
 
-**Step 3 — verify.** Ask the agent (or run in a DSH session) to `git push origin develop`. Expect the tool call to be denied:
+**Step 3 — verify.** Ask the agent to `git push origin develop`. Expect the tool call to be denied:
 
 ```text
 Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
 Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
 ```
 
-Messages are English by default; add `"locale": "zh"` to the config to switch to Chinese (see [Configuration Reference](#configuration-reference)).
+Messages are English by default; create a config with `"locale": "zh"` to switch to Chinese — messages then read like: *已拦截:受保护分支「develop」禁止直推 / 下一步:集成分支(develop)由 PR/MR 合入 feature……* (see [Configuration Reference](#configuration-reference)).
 
-**Done.** The guard is live for this repo. Keep reading for the [Configuration](#configuration-reference) to map your own branches, or the [Gate Matrix](#gate-matrix--what-gets-blocked-what-passes) for the full decision table.
+**Done.** The guard is live for this repo with the built-in defaults. Want more stages (`preview` / `production`) or different branch names? Write a `gitflow-guard.config.json` and only the fields you care about — everything else keeps the built-in defaults. For the full decision table, see the [Gate Matrix](#gate-matrix--what-gets-blocked-what-passes).
 
 ### Full walkthrough — one feature, end to end
 
@@ -139,7 +149,7 @@ Nobody has to remember the rules — the rules are enforced.
 ## What it does — capabilities
 
 - **Blocks, before execution**: direct push / force-push / delete of protected role branches (integration / preview / production / archive); agent merging into production or archive.
-- **Role-driven, fully configurable**: `integration` is the only required role; `preview` / `production` / `archive` are optional arrays of branch names or regexes, each with its own update rules (`pr` / `flexible`, `mergeBy`).
+- **Role-driven, fully configurable**: `integration` (built-in default: `develop`) is the core role; `preview` / `production` / `archive` are optional arrays of branch names or regexes, each with its own update rules (`pr` / `flexible`, `mergeBy`).
 - **Merge-by-user where it matters**: production & archive merges stay in your hands — the plugin blocks the agent from clicking merge, so your action *is* the confirmation.
 - **Works with any naming**: branch names are mapped by your config, never hard-coded (see [Configuration](#configuration-reference)).
 - **Fully audited**: every deny is appended to an audit log under your user state directory (`~/.local/state/gitflow-guard/`, `%LOCALAPPDATA%\gitflow-guard` on Windows) — outside the repository, never committed, outside the agent's writable sandbox, and shared across all linked worktrees of one repository.
@@ -186,7 +196,7 @@ No chat-confirmation or permit store: sensitive merges (production / archive) ar
 
 #### 1. Config is the single source of truth
 
-Nothing about branch names or rules is hard-coded. `integration` is the only required role; `preview` / `production` / `archive` are optional arrays of exact names or regexes, each with its own `update` and `mergeBy`. The same binary scales from a solo `develop` to an enterprise multi-env pipeline.
+Nothing about branch names or rules is hard-coded. `integration` ships as a built-in default (`develop`); `preview` / `production` / `archive` are optional arrays of exact names or regexes, each with its own `update` and `mergeBy` — deep-merged over the defaults. The same binary scales from a solo `develop` to an enterprise multi-env pipeline.
 
 #### 2. Blocking happens before execution, not after
 
@@ -200,9 +210,28 @@ No plugin code decides "is this merge OK?" for production or archive. The gate s
 
 ## Configuration Reference
 
+### Built-in defaults & deep-merge override
+
+The guard is **on by default** — no `gitflow-guard.config.json` needed. It protects:
+
+| default | role | rule |
+|---|---|---|
+| `develop` | **integration** | no direct push; updates via PR/MR (`update: "pr"`) |
+| `main` | **archive** | no direct push / no agent merge; the archive merge is yours (`mergeBy: "user"`) |
+
+When you do create `gitflow-guard.config.json`, its fields are **deep-merged over the defaults**: each field/role you write replaces the default for that field/role, everything you don't write keeps the default. Write only what you want to change:
+
+```jsonc
+{
+  "branches": { "production": ["release-[\\w-]+"] }  // defaults keep develop+main; production is added
+}
+```
+
+**Disable entirely** (trunk / single-branch flows): `{ "enabled": false }`. Fixing an accidental block is a one-file change, and `gitflow-guard status` always explains what is in effect (including when it is the built-in defaults).
+
 ### Branch roles — the model behind the checks
 
-Only **`integration`** is required. Every other role is optional — configure what your flow actually uses, and each entry is an exact branch name **or** a regex pattern.
+A **role** maps branch names (or regexes) to a rule set. `integration` is provided by the defaults; every other role is optional.
 
 ```text
 feature branches ──(free)──> integration (integration branch; updates via PR/MR)
@@ -216,10 +245,10 @@ archive (optional; you archive after release)
 | role | config key | required? | enforced behavior |
 |---|---|---|---|
 | **feature** | `featurePattern` | — | free: commit / push / sync / rebase |
-| **integration** | `branches.integration` | always | no direct push (default `pr`); features merge in via PR/MR |
+| **integration** | `branches.integration` | default (`develop`) | no direct push (default `pr`); features merge in via PR/MR |
 | **preview** | `branches.preview` (array) | optional | no direct push; updates via PR/MR only (env endpoints) |
 | **production** | `branches.production` (array) | optional | PR/MR only; merge by user only (`mergeBy: "user"`) |
-| **archive** | `branches.archive` (array) | optional | archive PR/MR may be created by agents; the merge stays user-hand only |
+| **archive** | `branches.archive` (array) | default (`main`) | archive PR/MR may be created by agents; the merge stays user-hand only |
 
 ### Customizing branch names & rules — any naming works
 
@@ -259,10 +288,10 @@ archive (optional; you archive after release)
 
 ```jsonc
 {
-  "enabled": true,                     // opt-in: file exists AND enabled=true
+  "enabled": true,                     // default true — set false to turn the guard off
   "featurePattern": "feature/[\\w-]+", // JS regex matching your working/feature branches
   "branches": {
-    "integration": { "branches": ["develop"], "update": "pr" },  // REQUIRED
+    "integration": { "branches": ["develop"], "update": "pr" },  // default: ["develop"] — omit to keep
     "preview":     { "branches": ["ita1"], "update": "pr" },     // optional
     "production":  { "branches": ["prd"], "update": "pr", "mergeBy": "user" }, // optional
     "archive":     ["main"]                                      // optional
@@ -288,8 +317,8 @@ archive (optional; you archive after release)
   registerLocale('fr', fr)
   ```
 - **Unknown locales**: an unregistered `"locale"` value falls back to English during interception (by design — hooks never stall on wording), so a typo is easy to miss; the one-line warning shows up in `gitflow-guard status`.
-- **Validation**: `integration` is required; overlapping role entries are rejected; invalid regex is rejected. **Any error disables the plugin for that project** (reported) rather than applying a half-guessed setup.
-- **Strict mode**: by default a broken config warns on stderr once and lets the command pass (fail-open, so a typo can't wedge your tooling). `"strict": true` flips config errors and internal errors to **block** (fail-closed) — for high-risk repos. A missing file or explicit `enabled: false` stays silent either way.
+- **Validation**: overlapping role entries are rejected; invalid regex is rejected. **Any config error reverses the project to "not enabled"** (reported) rather than applying a half-guessed setup; watch out that a role you override with the same branch name as a default role (e.g. mapping `main` to integration while the default archive is still `main`) is an overlap error — cover or drop the other role too.
+- **Strict mode**: by default a broken config warns on stderr once and lets the command pass (fail-open, so a typo can't wedge your tooling). `"strict": true` flips config errors and internal errors to **block** (fail-closed) — for high-risk repos. An explicit `enabled: false` stays silent; a *missing* file is not an error anymore — the built-in defaults (develop+main) are in effect.
 
 ---
 
@@ -327,14 +356,14 @@ The PR/MR target is resolved via `gh pr view` (GitHub) or `glab mr view` (GitLab
 
 | Agent | Install command | After that |
 |---|---|---|
-| DSH | `dsh plugin --profile web add agents-gitflow-guard@0.0.19` | restart DSH — the plugin auto-mounts as a profile layer |
-| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard@0.0.19` | wire a hook to the `gitflow-guard` binary (below) |
-| Pi | `npm i -D agents-gitflow-guard@0.0.19` | copy `pi/gitflow-guard.ts` into `.pi/extensions/` (below) |
+| DSH | `dsh plugin --profile web add agents-gitflow-guard@0.0.21` | restart DSH — the plugin auto-mounts as a profile layer |
+| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard@0.0.21` | `gitflow-guard wire --client <name>` — one command per client (below) |
+| Pi | `npm i -D agents-gitflow-guard@0.0.21` | copy `pi/gitflow-guard.ts` into `.pi/extensions/` (below) |
 
 **DSH — in-process plugin** (the standard path, already covered in [Quick Start](#quick-start--30-seconds-to-a-guarded-repo)):
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard@0.0.19    # pin recommended, see note above
+dsh plugin --profile web add agents-gitflow-guard@0.0.21    # pin recommended, see note above
 ```
 
 Then restart DSH. Upgrades are the same command, followed by another restart.
@@ -348,13 +377,17 @@ dsh plugin --profile web add file:/path/to/agents-gitflow-guard
 
 The package declares `dsh.bundle.patch`, so `dsh plugin add` automatically makes it a profile layer — no manual profile editing.
 
-**Standalone agent hooks** — Claude Code / Codex / OpenCode / Antigravity, no DSH required. Install the CLI once, then reference the `gitflow-guard` binary in each hook config:
+**Standalone agent hooks** — Claude Code / Codex / OpenCode / Antigravity, no DSH required. Install the CLI once, then wire one client per command (the guard is on by default via its built-in config, so wiring is all that remains):
 
 ```bash
-npm i -g agents-gitflow-guard@0.0.19   # provides the `gitflow-guard` binary
+npm i -g agents-gitflow-guard@0.0.21   # provides the `gitflow-guard` binary
+gitflow-guard wire --client claude --project --yes
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes   # experimental
 ```
 
-This repo ships project configs at `.claude/settings.json` (Claude Code), `.codex/hooks.json` (Codex), `.opencode/hook/hooks.yaml` (OpenCode) and `.agents/hooks.json` (Antigravity / Google); any other repo adds its own:
+`wire` reads the existing config file (if any), merges the hook entry in without touching anything else, is idempotent (already wired → skipped), supports `--dry-run` to preview and `--unwire` to remove, and asks before touching `--global` files. The exact files it writes (for reference, and for hand-writing instead of `wire`) are:
 
 ```jsonc
 // Claude Code — .claude/settings.json
@@ -407,7 +440,7 @@ hooks:
 Pi loads extensions in-process (no stdin payload, no subprocess hook). Install the shipped entry point into the project and keep the package in devDependencies:
 
 ```bash
-npm i -D agents-gitflow-guard@0.0.19
+npm i -D agents-gitflow-guard@0.0.21
 mkdir -p .pi/extensions
 cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-guard.ts
 ```
@@ -421,7 +454,8 @@ cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-
 - The hook reads the payload on stdin and answers with that platform's protocol: Claude Code / OpenCode → `exit 2` (stderr is the reason + "next step" hint); Codex → JSON `{"hookSpecificOutput":{"permissionDecision":"deny",...}}` on stdout; Antigravity → JSON `{"decision":"deny","reason":...}` on stdout with `exit 0` (Antigravity requires exit 0 and rejects `hookSpecificOutput` / non-allow values). Pi has no stdin protocol: the in-process extension listens to the official `tool_call` event and denies via its return value `{ block: true, reason }` (the CLI subprocess only speaks the internal exit-2 contract).
 - Only the pre-tool event is needed: the guard blocks *before* the command runs. There is no permit to consume afterwards, so no post-tool hooks are required.
 - The examples above call the globally-installed `gitflow-guard` (`npm i -g`). If a hook subprocess can't see it on its `PATH`, point at the full binary path from `npm bin -g` — hook subprocesses may not inherit your interactive shell `PATH`. The `bin/gitflow-guard.mjs` paths in this repo's shipped configs only work from a checkout.
-- Fully opt-in: the hook does nothing unless the repo has `gitflow-guard.config.json` with `enabled: true`.
+- **On by default**: the built-in config (integration=`develop`, archive=`main`) is active without any file. Trunk / single-branch repos: create `gitflow-guard.config.json` with `{ "enabled": false }`, or map your own branches. A custom config **deep-merges** over the defaults — write only the fields you want to change.
+- `wire` never removes or rewrites your existing hook entries — it only adds its own command (deduped) and, with `--unwire`, removes exactly that command again.
 
 ---
 
@@ -429,7 +463,7 @@ cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-
 
 ### My branches don't follow the default names — can I use it?
 
-Yes — nothing about the branch names is fixed. `integration` is the only required role; its entries (and those of `preview` / `production` / `archive`) are any exact branch names or regex patterns you like. `featurePattern` tells the plugin how to recognize your working branches.
+Yes — nothing about the branch names is fixed. `integration` ships as a built-in default (`develop`) and any custom config deep-merges over it; its entries (and those of `preview` / `production` / `archive`) are any exact branch names or regex patterns you like. `featurePattern` tells the plugin how to recognize your working branches.
 
 A team that calls its integration branch `master`, adds a `beta` preview, and prefixes feature branches with `fix/` writes exactly that into the config; every block, report, and audit then speaks those names. There is no convention you must adopt — only a mapping you declare. See [Customizing branch names & rules](#customizing-branch-names--rules--any-naming-works).
 
@@ -475,7 +509,7 @@ The blocks are reserved for: (1) direct writes to protected role branches, and (
 
 A half-guessed setup is never applied by accident: any validation error disables the guard for that project and reports the errors.
 
-Common mistakes: missing `integration` (required), overlapping a branch across two roles (rejected explicitly), and a `featurePattern` that doesn't compile (rejected as invalid regex). The failure is loud and the file is one JSON object, so the fix is usually a thirty-second correction.
+Common mistakes: overriding a role with the same branch name as a default role (e.g. `main` as integration while the default archive is still `main` — an explicit overlap error; cover or drop the other role too), overlapping a branch across two roles (rejected), and a `featurePattern` that doesn't compile (rejected as invalid regex). The failure is loud and the file is one JSON object, so the fix is usually a thirty-second correction.
 
 ---
 
@@ -498,10 +532,10 @@ If it saves your team from a shortcut gone wrong, the coffee button at the top o
 
 | term | meaning |
 |---|---|
-| **integration** | the branch and only required role (`branches.integration`); features merge in via PR/MR; protected |
+| **integration** | the core role (built-in default: `develop`); features merge in via PR/MR; protected |
 | **preview** | optional env-endpoint branches (`branches.preview`, array); updates via PR/MR only |
 | **production** | optional production branches (`branches.production`, array); PR/MR + merge by user only |
-| **archive** | optional post-release archive branch (`branches.archive`); user-hand only |
+| **archive** | optional post-release archive branch (`branches.archive`, array); agents may create PR/MRs into it, but the merge stays user-hand only |
 | **feature branch** | your working branch, matched by `featurePattern`; free zone |
 | **gate matrix** | the decision table mapping each classified command to allow/deny |
 | **pre-execute** | the tool-pipeline hook where denial happens — before the command runs |

package/README.zh.md

@@ -39,37 +39,47 @@
 
 ```bash
 # DSH —— 进程内插件(装完重启 DSH; 插件在进程启动时加载)
-dsh plugin --profile web add agents-gitflow-guard@0.0.19
+dsh plugin --profile web add agents-gitflow-guard@0.0.21
 ```
 
 ```bash
 # Claude Code · Codex · OpenCode · Antigravity —— 独立 hook,不需要 DSH
-npm i -g agents-gitflow-guard@0.0.19
+npm i -g agents-gitflow-guard@0.0.21
 ```
 
 ```bash
 # Pi —— 进程内扩展
-npm i -D agents-gitflow-guard@0.0.19
+npm i -D agents-gitflow-guard@0.0.21
 ```
 
 > **版本坑**: 裸 `add` 或不带版本的 `npm i` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。(DSH 用户: pnpm 打印的 peer 依赖 *警告* 属预期——DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`,插件正常工作。)
 >
-> hook 客户端(Claude Code · Codex · OpenCode · Antigravity)和 Pi 装完还要各做一步接线——见[安装详解](#安装详解)的逐客户端表。
+> hook 客户端(Claude Code · Codex · OpenCode · Antigravity)装完还要各做一步接线——**每个客户端一条命令**(见下)。Pi 拷贝一个文件;DSH 装完即已接线。
 
-**第 2 步——配置**,在**项目根目录**创建 `gitflow-guard.config.json`:
+**第 2 步——接线(无需配置文件)。** 守卫内置**默认配置,开箱即用:默认保护 `develop`(integration)+ `main`(archive)**,零配置。你要做的只是让 AI 客户端去调用守卫——每个 stdin-hook 客户端一条命令(DSH 自动接线;Pi 拷文件,见下):
 
-```jsonc
-{
-  "enabled": true,
-  "featurePattern": "feature/[\\w-]+",
-  "branches": {
-    "integration": ["develop"],   // 集成分支: feature 经 PR 合入, 受保护
-    "archive": ["main"]           // 归档分支: 发布后由你亲手合入
-  }
-}
+```bash
+# Claude Code → 本仓库 .claude/settings.json
+gitflow-guard wire --client claude --project --yes
+```
+
+```bash
+# Codex / OpenCode / Antigravity(各写各的配置文件; --yes 跳过 y/N 确认)
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes     # 实验支持
+```
+
+```bash
+# 只预览不写入 / 移除 / 交互向导:
+gitflow-guard wire --client claude --dry-run
+gitflow-guard wire --client claude --unwire
+gitflow-guard setup
 ```
 
-这一个文件就是全部配置:其中的 **`integration` 是唯一必填**角色;`preview` / `production` / `archive` 都是可选,只有你配了才启用对应关卡。插件按项目 opt-in——文件不存在或 `enabled: false` 时什么都不做。
+`wire` 对已有配置**非破坏性合并**(已存在的 hook 不动),默认只写**当前工程目录**;`--global`(本机所有仓库)写入前必先确认或需 `--yes`。各客户端的文件与格式见[安装详解](#安装详解)。
+
+> ⚠️ **main 默认受保护。** trunk / 单分支工作流(所有人直推同一条分支)的用户,装完第一次直推 `main` 就会被拦——创建 `gitflow-guard.config.json` 写 `{ "enabled": false }`,或自行映射分支(见[配置参考](#配置参考))。`gitflow-guard status` 在默认配置生效时也会反复提示这一点。
 
 **第 3 步——验证**。让 agent 执行 `git push origin develop`,预期工具调用被拒绝:
 
@@ -78,9 +88,9 @@ Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
 Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
 ```
 
-**文案默认是英文**(面向国际化)。要在你的项目里看中文,在 `gitflow-guard.config.json` 里加 `"locale": "zh"`;中文效果是:*已拦截:受保护分支「develop」禁止直推 / 下一步:集成分支(develop)由 PR/MR 合入 feature……*
+**文案默认是英文**(面向国际化)。要在你的项目里看中文,创建配置并加 `"locale": "zh"`;中文效果是:*已拦截:受保护分支「develop」禁止直推 / 下一步:集成分支(develop)由 PR/MR 合入 feature……*
 
-**完成。** 守卫对该仓库生效。继续往下看[配置参考](#配置参考)映射自己的分支,或看[门禁矩阵](#门禁矩阵拦什么放什么)的完整判定表。
+**完成。** 守卫已用内置默认配置生效。想要更多关卡(`preview` / `production`)或改分支名?写一个 `gitflow-guard.config.json`,只写你在意的字段,其余保持内置默认。完整判定表见[门禁矩阵](#门禁矩阵拦什么放什么)。
 
 ### 完整实战示例——一个 feature 的端到端旅程
 
@@ -105,7 +115,9 @@ AI 编码 agent 在你的仓库里工作。它通过系统提示词、项目智
 
 **这是软规则。** Agent 会跳过、重排、干脆"忘记"它——不是因为恶意,而是因为软指令对模型来说本来就是可选的。
 
-这个插件把软规则变成**硬机制**。agent 每次尝试的 git 操作都会对照*本地仓库的真实状态*检查;违规在命令执行前就被拦截,并给出原因和下一步。没人需要记得规则——规则被强制执行。
+这个插件把软规则变成**硬机制**。agent 每次尝试的 git 操作都会对照*本地仓库的真实状态*检查;违规在命令执行前就被拦截,并给出原因和下一步。
+
+没人需要记得规则——规则被强制执行。
 
 ---
 
@@ -136,7 +148,7 @@ AI 编码 agent 在你的仓库里工作。它通过系统提示词、项目智
 ## 它能做什么
 
 - **执行前拦截**:直推 / 强推 / 删除受保护角色分支(integration / preview / production / archive);agent 试图合入生产或归档。
-- **角色驱动、完全可配**:`integration` 是唯一必填;`preview` / `production` / `archive` 是可选数组(精确名或正则),每个角色独立 `update`(`pr` / `flexible`)与 `mergeBy`。
+- **角色驱动、完全可配**:`integration`(内置默认 `develop`)是核心角色;`preview` / `production` / `archive` 是可选数组(精确名或正则),每个角色独立 `update`(`pr` / `flexible`)与 `mergeBy`,自定义配置深度合并于默认之上。
 - **在关键处保留人的操作权**:生产与归档合并始终在你手上——插件阻止 agent 点击合并,于是你的动作*就是*确认。
 - **任何命名都行**:分支名全由配置映射,绝无硬编码(见[配置参考](#配置参考))。
 - **全程审计**:每次拦截都追加到用户级状态目录(macOS/Linux `~/.local/state/gitflow-guard/`,Windows `%LOCALAPPDATA%\gitflow-guard`)下的审计日志——在仓库外、绝不进版本库、位于 agent 可写沙箱之外,且同一仓库的所有 worktree 共享一份日志。
@@ -183,7 +195,7 @@ AI 编码 agent 在你的仓库里工作。它通过系统提示词、项目智
 
 #### 1. 配置是唯一事实来源
 
-分支名和规则没有任何硬编码。`integration` 是唯一必填角色;`preview` / `production` / `archive` 是可选数组(精确名或正则),每个都有自己的 `update` 与 `mergeBy`。同一个二进制从单条 `develop` 一直可扩到企业多环境流水线。
+分支名和规则没有任何硬编码。`integration` 以内置默认(`develop`)提供;`preview` / `production` / `archive` 是可选数组(精确名或正则),每个都有自己的 `update` 与 `mergeBy` — 在默认之上深度合并。同一个二进制从单条 `develop` 一直可扩到企业多环境流水线。
 
 #### 2. 拦截发生在执行前,不是执行后
 
@@ -197,9 +209,28 @@ AI 编码 agent 在你的仓库里工作。它通过系统提示词、项目智
 
 ## 配置参考
 
+### 内置默认配置 + 深度合并覆盖
+
+守卫**默认开启**——不需要 `gitflow-guard.config.json`。默认保护:
+
+| 默认值 | 角色 | 规则 |
+|---|---|---|
+| `develop` | **integration** | 禁直推;只经 PR/MR 合入(`update: "pr"`) |
+| `main` | **archive** | 禁直推 / 禁 agent 合并;归档合并留给你(`mergeBy: "user"`) |
+
+当你创建 `gitflow-guard.config.json` 时,它的字段会**深度合并覆盖默认**:写到的字段/角色替换默认,没写的保持默认。只写你想改的:
+
+```jsonc
+{
+  "branches": { "production": ["release-[\\w-]+"] }  // 默认的 develop+main 不变;新增 production
+}
+```
+
+**完全关闭**(trunk / 单分支流程):`{ "enabled": false }`。误拦时改一个文件即可恢复;`gitflow-guard status` 始终说明当前生效的是内置默认还是自定义配置。
+
 ### 分支角色——插件校验的模型
 
-只有 **`integration`** 是必填。其余全部可选——按你的流程配就好,每条目可以是精确分支名**或**正则。
+**角色**把分支名(或正则)映射到规则集。`integration` 由内置默认提供;其余角色全部可选。
 
 ```text
 feature 分支 ──(自由)──> integration(集成分支, PR/MR 合入)
@@ -213,10 +244,10 @@ archive(可选, 发布后你亲手归档)
 | 角色 | 配置键 | 必填? | 强制行为 |
 |---|---|---|---|
 | **feature** | `featurePattern` | — | 自由: commit / push / 同步 / rebase |
-| **integration** | `branches.integration` | 必填 | 禁直推(默认 `pr`);feature 只经 PR/MR 合入 |
+| **integration** | `branches.integration` | 默认(`develop`) | 禁直推(默认 `pr`);feature 只经 PR/MR 合入 |
 | **preview** | `branches.preview`(数组) | 可选 | 禁直推;只走 PR/MR(环境终点) |
 | **production** | `branches.production`(数组) | 可选 | 只走 PR/MR;合并仅限你(`mergeBy: "user"`) |
-| **archive** | `branches.archive`(数组) | 可选 | 允许 agent 创建指向它的 PR/MR; 合并仍限用户亲手 |
+| **archive** | `branches.archive`(数组) | 默认(`main`) | 允许 agent 创建指向它的 PR/MR; 合并仍限用户亲手 |
 
 ### 自定义分支名与规则——任何命名都可以
 
@@ -256,10 +287,10 @@ archive(可选, 发布后你亲手归档)
 
 ```jsonc
 {
-  "enabled": true,                     // opt-in: 文件存在且 enabled=true
+  "enabled": true,                     // 默认 true — 写 false 即关闭守卫
   "featurePattern": "feature/[\\w-]+", // 识别工作/feature 分支的 JS 正则
   "branches": {
-    "integration": { "branches": ["develop"], "update": "pr" },  // 必填
+    "integration": { "branches": ["develop"], "update": "pr" },  // 默认 ["develop"] — 省略即保持默认
     "preview":     { "branches": ["ita1"], "update": "pr" },     // 可选
     "production":  { "branches": ["prd"], "update": "pr", "mergeBy": "user" }, // 可选
     "archive":     ["main"]                                      // 可选
@@ -284,8 +315,8 @@ archive(可选, 发布后你亲手归档)
   registerLocale('fr', fr)
   ```
 - **未注册语言**:拦截路径对未注册的 `"locale"` 静默回退英文(设计如此——hook 不因文案缺失卡死),笔误因此容易被忽略;一行告警在 `gitflow-guard status` 中可见。
-- **校验**:`integration` 必填;角色条目重叠会被拒;非法正则会报错。**任何错误都会让该项目的插件禁用并上报**(而不是用半吊子配置)。
-- **strict 模式**:默认配置损坏时 stderr 告警一次后放行(fail-open,避免一个笔误卡死工具管道);`"strict": true` 把配置异常与内部错误翻转为**拦截**(fail-closed)——供高风险仓库选用。文件不存在或显式 `enabled: false` 两种模式下都保持静默。
+- **校验**:角色条目重叠会被拒;非法正则会报错。**任何配置错误都会让该项目的守卫回退为"未启用"并上报**(而不是用半吊子配置)。注意:你覆盖的角色若与默认角色同名(如把 `main` 映射为 integration 而默认 archive 仍是 `main`)会触发重叠报错——需一并覆盖或去掉另一角色。
+- **strict 模式**:默认配置损坏时 stderr 告警一次后放行(fail-open,避免一个笔误卡死工具管道);`"strict": true` 把配置异常与内部错误翻转为**拦截**(fail-closed)——供高风险仓库选用。显式 `enabled: false` 保持静默;而*文件不存在*不再是"未启用"——内置默认(develop+main)直接生效。
 
 ---
 
@@ -323,14 +354,14 @@ PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有
 
 | 客户端 | 安装命令 | 装完再做什么 |
 |---|---|---|
-| DSH | `dsh plugin --profile web add agents-gitflow-guard@0.0.19` | 重启 DSH——插件自动挂为 profile 层 |
-| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard@0.0.19` | 在各自 hook 配置里指向 `gitflow-guard` 二进制(见下) |
-| Pi | `npm i -D agents-gitflow-guard@0.0.19` | 把 `pi/gitflow-guard.ts` 拷进 `.pi/extensions/`(见下) |
+| DSH | `dsh plugin --profile web add agents-gitflow-guard@0.0.21` | 重启 DSH——插件自动挂为 profile 层 |
+| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard@0.0.21` | `gitflow-guard wire --client <名>`——每个客户端一条命令(见下) |
+| Pi | `npm i -D agents-gitflow-guard@0.0.21` | 把 `pi/gitflow-guard.ts` 拷进 `.pi/extensions/`(见下) |
 
 **DSH —— 进程内插件**(标准路径,已在[快速开始](#快速开始30-秒用上)覆盖):
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard@0.0.19    # 建议锁版本, 见上文提示
+dsh plugin --profile web add agents-gitflow-guard@0.0.21    # 建议锁版本, 见上文提示
 ```
 
 然后重启 DSH。升级用同一命令,再重启一次。
@@ -344,13 +375,17 @@ dsh plugin --profile web add file:/path/to/agents-gitflow-guard
 
 包自带 `dsh.bundle.patch` 声明,`dsh plugin add` 自动把它挂为 profile 层,无需手工编辑 profile。
 
-**各 agent 独立 hook**——Claude Code / Codex / OpenCode / Antigravity,不依赖 DSH。全局装一次 CLI,然后引用 `gitflow-guard` 二进制:
+**各 agent 独立 hook**——Claude Code / Codex / OpenCode / Antigravity,不依赖 DSH。全局装一次 CLI,然后**每客户端一条命令接线**(守卫凭内置默认配置已默认开启,接线是唯一剩下的事):
 
 ```bash
-npm i -g agents-gitflow-guard@0.0.19   # 提供 `gitflow-guard` 二进制
+npm i -g agents-gitflow-guard@0.0.21   # 提供 `gitflow-guard` 二进制
+gitflow-guard wire --client claude --project --yes
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes   # 实验支持
 ```
 
-本仓库已自带 `.claude/settings.json`(Claude Code)、`.codex/hooks.json`(Codex)、`.opencode/hook/hooks.yaml`(OpenCode)和 `.agents/hooks.json`(Antigravity / Google);其他仓库加自己的 hooks:
+`wire` 读取已有配置文件(如有)并把 hook 条目合入——不碰其他内容、幂等(已接则跳过)、支持 `--dry-run` 预览与 `--unwire` 移除、写 `--global` 前必先询问。它写入的准确文件(供参考,也可代替 `wire` 手写)是:
 
 ```jsonc
 // Claude Code — .claude/settings.json
@@ -403,7 +438,7 @@ hooks:
 Pi 以进程内扩展装载(没有 stdin payload,也没有子进程 hook)。把随包发布的入口装进项目、包留在 devDependencies:
 
 ```bash
-npm i -D agents-gitflow-guard@0.0.19
+npm i -D agents-gitflow-guard@0.0.21
 mkdir -p .pi/extensions
 cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-guard.ts
 ```
@@ -417,7 +452,8 @@ cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-
 - hook 读 stdin payload,按**各平台协议**作答:Claude Code / OpenCode → `exit 2`(stderr 展示原因 + "下一步"提示);Codex → stdout 输出 JSON `{"hookSpecificOutput":{"permissionDecision":"deny",...}}`;Antigravity → stdout 输出 `{"decision":"deny","reason":...}` 且 **exit 0**(Antigravity 要求 exit 0,拒绝 hookSpecificOutput/非 allow 值)。Pi 没有 stdin 协议:进程内扩展监听官方 `tool_call` 事件,经返回值 `{ block: true, reason }` 拒绝(守卫 CLI 子进程只承载内部 exit-2 契约)。
 - 只需要**执行前事件**:守卫在命令执行*之前*拦截;没有特许可事后消费,因此无需执行后钩子。
 - 上面示例调的是全局安装的 `gitflow-guard`(`npm i -g`)。若 hook 子进程在它的 `PATH` 里找不到,就指向 `npm bin -g` 给出的完整二进制路径——hook 子进程不一定继承你交互 shell 的 PATH。本仓库自带配置里的 `bin/gitflow-guard.mjs` 路径只对 checkout 贡献者有效。
-- 完全 opt-in:仓库没有 `gitflow-guard.config.json`(或 `enabled` 非 true)时 hook 什么都不做。
+- **默认开启**:内置默认配置(integration=`develop`, archive=`main`)无需任何文件即生效。trunk / 单分支仓库:建 `gitflow-guard.config.json` 写 `{ "enabled": false }`,或自行映射分支。自定义配置在默认之上**深度合并**——只写你想改的字段。
+- `wire` 从不删除或重写你已有的 hook 条目——只添加自己的命令(去重);`--unwire` 精确移除同一条命令。
 
 ---
 
@@ -425,7 +461,7 @@ cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-
 
 ### 我的分支不叫默认名字,能用吗?
 
-能用——分支名没有任何写死。`integration` 是唯一必填;它的条目(以及 `preview`/`production`/`archive` 的)可以是任意精确分支名或正则。`featurePattern` 告诉插件怎么认你的工作分支。
+能用——分支名没有任何写死。`integration` 由内置默认提供(`develop`),自定义配置在默认之上深度合并;它的条目(以及 `preview`/`production`/`archive` 的)可以是任意精确分支名或正则。`featurePattern` 告诉插件怎么认你的工作分支。
 
 把集成分支叫 `master`、加一个 `beta` 预览、feature 前缀用 `fix/`——写进配置即可;拦截、报告、审计都跟着你的命名走。没有任何你必须遵守的约定,只有你声明的映射。见[自定义分支名与规则](#自定义分支名与规则任何命名都可以)。
 
@@ -471,7 +507,7 @@ cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-
 
 半吊子配置绝不会意外生效:任何校验错误都会让该项目的守卫禁用并上报错误。
 
-常见错误:`integration` 缺失(必填)、同一个分支被配到两个角色里(显式拒绝)、`featurePattern` 写不成合法正则(报错)。失败提示很明确,文件又是一个 JSON 对象,通常三十秒改好。
+常见错误:覆盖的角色与默认角色同名(如把 `main` 设为 integration 而默认 archive 仍是 `main`——显式重叠报错,需一并覆盖或去掉另一角色)、同一个分支被配到两个角色里(显式拒绝)、`featurePattern` 写不成合法正则(报错)。失败提示很明确,文件又是一个 JSON 对象,通常三十秒改好。
 
 ---
 
@@ -494,7 +530,7 @@ MIT,免费,无条件。随便用、随便改、随便发,唯一义务是保留
 
 | 术语 | 含义 |
 |---|---|
-| **integration** | 集成分支,唯一必填角色(`branches.integration`);feature 经 PR/MR 合入;受保护 |
+| **integration** | 集成分支,核心角色(内置默认 `develop`);feature 经 PR/MR 合入;受保护 |
 | **preview** | 可选环境终点分支(`branches.preview`,数组);只走 PR/MR 更新 |
 | **production** | 可选生产分支(`branches.production`,数组);PR/MR + 合并仅限用户 |
 | **archive** | 可选的发布后归档分支(`branches.archive`,数组);允许 agent 创建指向它的 PR/MR,合并仍限用户亲手 |

package/lib/cli.mjs

@@ -1,6 +1,8 @@
-import { _ as resolveLocale, d as gitRunner, f as loadConfig, h as makeT, i as formatDeny, l as currentBranch, o as stateDir, p as roleMatches, r as evaluateCommand, u as findRepoRoot, v as classify } from "./src-CL6uB3oo.mjs";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { _ as resolveLocale, d as gitRunner, f as loadConfig, h as makeT, i as formatDeny, l as currentBranch, o as stateDir, p as roleMatches, r as evaluateCommand, u as findRepoRoot, v as classify } from "./src-DPJRoEJq.mjs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
 //#region src/platform.ts
 function str(v) {
 	return typeof v === "string" ? v : "";
@@ -84,6 +86,213 @@ function encodeDeny(platform, reason) {
 	}
 }
 //#endregion
+//#region src/wire.ts
+const CLIENTS = [
+	"dsh",
+	"claude",
+	"codex",
+	"opencode",
+	"antigravity",
+	"pi"
+];
+function isWireClient(v) {
+	return CLIENTS.includes(v);
+}
+/** 各客户端的 hook 落位规格(dsh/pi 无 hook 文件, 仅输出接入引导) */
+const WIRE_CLIENTS = [
+	{
+		client: "claude",
+		projectPath: ".claude/settings.json",
+		globalPath: () => join(homedir(), ".claude", "settings.json")
+	},
+	{
+		client: "codex",
+		projectPath: ".codex/hooks.json",
+		globalPath: () => join(homedir(), ".codex", "hooks.json")
+	},
+	{
+		client: "opencode",
+		projectPath: ".opencode/hook/hooks.yaml",
+		globalPath: () => join(homedir(), ".config", "opencode", "hook", "hooks.yaml")
+	},
+	{
+		client: "antigravity",
+		projectPath: ".agents/hooks.json",
+		globalPath: () => join(homedir(), ".gemini", "config", "hooks.json"),
+		experimental: true
+	},
+	{
+		client: "dsh",
+		projectPath: "",
+		globalPath: () => ""
+	},
+	{
+		client: "pi",
+		projectPath: "",
+		globalPath: () => ""
+	}
+];
+/** 各 stdin-hook 客户端的 hook 命令(与 references/*.md 逐一对应; codex/antigravity 用相对 bin/...) */
+const COMMANDS = {
+	claude: "node ${CLAUDE_PROJECT_DIR}/bin/gitflow-guard.mjs check --platform claude",
+	codex: "node bin/gitflow-guard.mjs check --platform codex",
+	opencode: "node \"$OPENCODE_PROJECT_DIR/bin/gitflow-guard.mjs\" check --platform opencode",
+	antigravity: "node bin/gitflow-guard.mjs check --platform antigravity"
+};
+/** OpenCode YAML 模板(顶层 hooks: + 语义 id gitflow-guard) */
+const OPENCODE_TEMPLATE = [
+	"hooks:",
+	"  - id: gitflow-guard",
+	"    event: tool.before.bash",
+	"    actions:",
+	"      - bash: |",
+	`          ${COMMANDS.opencode}`
+].join("\n");
+const YAML_ID_GUARD = /^\s*- id: gitflow-guard\s*$/m;
+const YAML_ID_ANY = /^\s*- id:/m;
+/** 读取文本文件; 缺失返回 null(其余异常也视为缺失, 决策保守) */
+async function readText(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch {
+		return null;
+	}
+}
+async function writeText(path, content) {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, content, "utf8");
+}
+/** JSON 递归搜索: 是否已含该命令(任意形状, 幂等判重) */
+function jsonContains(obj, needle) {
+	if (typeof obj === "string") return obj === needle;
+	if (Array.isArray(obj)) return obj.some((x) => jsonContains(x, needle));
+	if (obj !== null && typeof obj === "object") return Object.values(obj).some((x) => jsonContains(x, needle));
+	return false;
+}
+function parseJsonOrThrow(path, raw) {
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("not an object");
+		return parsed;
+	} catch {
+		throw new Error(`invalid JSON in ${path} — refusing to modify it`);
+	}
+}
+async function writeJson(path, obj) {
+	await writeText(path, `${JSON.stringify(obj, null, 2)}\n`);
+}
+/** JSON 客户端(claude/codex/antigravity)新增 hook 条目; 非破坏性合并, 同命令已存在则跳过 */
+async function addJsonEntry(path, client, dryRun) {
+	const cmd = COMMANDS[client];
+	const raw = await readText(path);
+	const obj = raw === null ? {} : parseJsonOrThrow(path, raw);
+	if (jsonContains(obj, cmd)) return "exists";
+	const entry = client === "antigravity" ? {
+		matcher: "run_command",
+		hooks: [{
+			type: "command",
+			command: cmd
+		}]
+	} : {
+		matcher: client === "codex" ? "^Bash$" : "Bash",
+		hooks: [{
+			type: "command",
+			command: cmd
+		}]
+	};
+	if (client === "antigravity") {
+		const block = obj["gitflow-guard"] ??= { PreToolUse: [] };
+		if (!Array.isArray(block.PreToolUse)) throw new Error(`invalid ${path}: gitflow-guard.PreToolUse must be an array`);
+		block.PreToolUse.push(entry);
+	} else {
+		const hooksObj = obj["hooks"] ??= {};
+		const arr = hooksObj["PreToolUse"] ??= [];
+		if (!Array.isArray(arr)) throw new Error(`invalid ${path}: hooks.PreToolUse must be an array`);
+		arr.push(entry);
+	}
+	if (!dryRun) await writeJson(path, obj);
+	return "added";
+}
+/** JSON 客户端移除本插件条目; 不动其他内容 */
+async function removeJsonEntry(path, client, dryRun) {
+	const cmd = COMMANDS[client];
+	const raw = await readText(path);
+	if (raw === null) return "absent";
+	const obj = parseJsonOrThrow(path, raw);
+	if (!jsonContains(obj, cmd)) return "absent";
+	if (client === "antigravity") delete obj["gitflow-guard"];
+	else {
+		const hooksObj = obj["hooks"];
+		const arr = hooksObj?.["PreToolUse"];
+		if (Array.isArray(arr)) {
+			const rest = arr.filter((e) => !(e?.hooks ?? []).some((h) => h?.command === cmd));
+			if (rest.length === 0) delete hooksObj["PreToolUse"];
+			else hooksObj["PreToolUse"] = rest;
+			if (hooksObj && Object.keys(hooksObj).length === 0) delete obj["hooks"];
+		}
+	}
+	if (!dryRun) await writeJson(path, obj);
+	return "removed";
+}
+/** OpenCode YAML: hooks: 列表按语义 id gitflow-guard 判重/落位 */
+async function addYamlEntry(path, dryRun) {
+	const raw = await readText(path);
+	if (raw !== null) {
+		if (YAML_ID_GUARD.test(raw)) return "exists";
+		const lines = raw.split("\n");
+		const hooksIdx = lines.findIndex((l) => /^hooks:\s*$/.test(l));
+		const block = OPENCODE_TEMPLATE.split("\n").slice(1);
+		if (hooksIdx === -1) {
+			const joined = [
+				...lines,
+				"",
+				...block
+			].join("\n");
+			if (!dryRun) await writeText(path, joined);
+			return "added";
+		}
+		lines.splice(hooksIdx + 1, 0, ...block);
+		if (!dryRun) await writeText(path, lines.join("\n"));
+		return "added";
+	}
+	if (!dryRun) await writeText(path, OPENCODE_TEMPLATE);
+	return "added";
+}
+/** OpenCode YAML: 移除 gitflow-guard 块; 若列表清空则连顶层 hooks: 一并清理 */
+async function removeYamlEntry(path, dryRun) {
+	const raw = await readText(path);
+	if (raw === null) return "absent";
+	if (!YAML_ID_GUARD.test(raw)) return "absent";
+	const lines = raw.split("\n");
+	const start = lines.findIndex((l) => YAML_ID_GUARD.test(l));
+	let end = lines.length;
+	for (let i = start + 1; i < lines.length; i++) if (YAML_ID_ANY.test(lines[i])) {
+		end = i;
+		break;
+	}
+	let rest = [...lines.slice(0, start), ...lines.slice(end)];
+	if (!rest.some((l) => YAML_ID_ANY.test(l))) rest = rest.filter((l) => !/^hooks:\s*$/.test(l));
+	const text = rest.join("\n");
+	if (!dryRun) await writeText(path, text);
+	return "removed";
+}
+/** 执行一次 wire 落位/移除/预览; dsh/pi 由上层直接短路, 不进这里 */
+async function applyWire(client, path, unwire, dryRun) {
+	if (client === "opencode") return unwire ? removeYamlEntry(path, dryRun) : addYamlEntry(path, dryRun);
+	return unwire ? removeJsonEntry(path, client, dryRun) : addJsonEntry(path, client, dryRun);
+}
+/** 只读探测: 该配置文件是否已含本插件 hook(status 的接线提示用) */
+async function isWired(client, path) {
+	const raw = await readText(path);
+	if (raw === null) return false;
+	if (client === "opencode") return YAML_ID_GUARD.test(raw);
+	try {
+		return jsonContains(JSON.parse(raw), COMMANDS[client]);
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/cli.ts
 function parseFlags(argv) {
 	const flags = {};
@@ -95,11 +304,18 @@ function parseFlags(argv) {
 		else if (a === "--platform") flags.platform = next();
 		else if (a === "--command") flags.command = next();
 		else if (a === "--locale") flags.locale = next();
+		else if (a === "--client") flags.client = next();
+		else if (a === "--global") flags.global = true;
+		else if (a === "--project") flags.project = true;
+		else if (a === "--unwire") flags.unwire = true;
+		else if (a === "--dry-run") flags.dryRun = true;
+		else if (a === "--yes") flags.yes = true;
 		else if (a.startsWith("--repo=")) flags.repo = a.slice(7);
 		else if (a.startsWith("--lines=")) flags.lines = Number(a.slice(8));
 		else if (a.startsWith("--platform=")) flags.platform = a.slice(11);
 		else if (a.startsWith("--command=")) flags.command = a.slice(10);
 		else if (a.startsWith("--locale=")) flags.locale = a.slice(9);
+		else if (a.startsWith("--client=")) flags.client = a.slice(9);
 	}
 	return flags;
 }
@@ -131,6 +347,8 @@ async function main(argv, opts = {}) {
 		if (cmd === "status") return await status(flags, runner);
 		if (cmd === "audit") return await audit(flags, runner);
 		if (cmd === "check") return await check(flags);
+		if (cmd === "wire") return await wire(flags, runner);
+		if (cmd === "setup") return await setup(flags, runner);
 		const t = makeT(await resolveFrameworkLocale(flags, runner));
 		console.error(`${t("cli.unknownCommand", { cmd: cmd ?? "" })}\n\n${t("usage.text")}`);
 		return 1;
@@ -145,7 +363,8 @@ async function status(flags, runner) {
 		console.error(makeT(resolveLocale(flags.locale))("cli.cannotLocate"));
 		return 1;
 	}
-	const { config, errors, warnings } = await loadConfig(repoRoot);
+	const loaded = await loadConfig(repoRoot);
+	const { config, errors, warnings } = loaded;
 	const enabled = config?.enabled === true;
 	const t = makeT(cliLocale(flags, config?.locale));
 	console.log(t("cli.statusTitle", { repo: repoRoot }));
@@ -173,6 +392,10 @@ async function status(flags, runner) {
 		merge: c.branches.production.mergeBy || "user"
 	}));
 	if (c.branches.archive) console.log(t("cli.statusArchive", { list: c.branches.archive.branches.join(", ") }));
+	if (loaded.usingDefaults) {
+		console.log(t("cli.statusUsingDefaults"));
+		console.log(t("cli.statusMainProtected"));
+	}
 	console.log(t("cli.statusCurrentBranch", { branch: branch ?? t("cli.statusUnknownBranch") }));
 	const r = await runner.run([
 		"for-each-ref",
@@ -190,6 +413,15 @@ async function status(flags, runner) {
 	};
 	console.log(t("cli.statusLocalBranches"));
 	for (const b of localBranches) console.log(`  ${b} → ${classifyBranch(b)}`);
+	const hints = [];
+	for (const spec of WIRE_CLIENTS) {
+		if (spec.client === "dsh" || spec.client === "pi") continue;
+		if (!await isWired(spec.client, join(repoRoot, spec.projectPath))) hints.push(spec.client);
+	}
+	if (hints.length > 0) {
+		console.log(t("cli.statusWireHints"));
+		for (const c of hints) console.log(t("cli.statusWireHint", { client: c }));
+	}
 	return 0;
 }
 async function audit(flags, runner) {
@@ -214,6 +446,147 @@ async function audit(flags, runner) {
 	}
 	return 0;
 }
+/** 交互提问(仅 TTY 可用); 返回小写化、去空格的答案 */
+function askLine(question) {
+	return new Promise((resolve) => {
+		const rl = createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		rl.question(question, (ans) => {
+			rl.close();
+			resolve(ans.trim().toLowerCase());
+		});
+	});
+}
+/** 作用域解析: 显式旗标 > 交互询问(仅 TTY) > 非交互默认 project(安全) */
+async function resolveScope(flags, t) {
+	if (flags.global) return "global";
+	if (flags.project) return "project";
+	if (process.stdin.isTTY) {
+		const ans = await askLine(t("cli.wireScopeAsk"));
+		if (ans === "project" || ans === "p") return "project";
+		if (ans === "global" || ans === "g") return "global";
+		console.log(t("cli.wireScopeInvalid"));
+		return null;
+	}
+	return "project";
+}
+/** wire/setup 共用落位核心: dsh/pi 只打印引导; 其余客户端读取/合并/写入对应配置文件(非破坏性) */
+async function wireCore(client, scope, opts, t) {
+	const spec = WIRE_CLIENTS.find((s) => s.client === client);
+	if (client === "dsh") {
+		console.log(t("cli.wireDshGuide"));
+		return 0;
+	}
+	if (client === "pi") {
+		console.log(t("cli.wirePiGuide"));
+		return 0;
+	}
+	if (spec.experimental) console.log(t("cli.wireExperimental", { client }));
+	const path = scope === "project" ? join(opts.repoRoot, spec.projectPath) : spec.globalPath();
+	console.log(t("cli.wireTarget", {
+		client,
+		path
+	}));
+	if (opts.dryRun) {
+		const res = await applyWire(client, path, !!opts.unwire, true);
+		if (res === "added") console.log(t("cli.wireDryRunAdd", {
+			client,
+			path
+		}));
+		else if (res === "removed") console.log(t("cli.wireDryRunRemove", {
+			client,
+			path
+		}));
+		else console.log(t("cli.wireDryRunNoOp", {
+			client,
+			path
+		}));
+		return 0;
+	}
+	if (!opts.yes) {
+		if (scope === "global" && !process.stdin.isTTY) {
+			console.error(t("cli.wireRefuseGlobal"));
+			return 1;
+		}
+		if (process.stdin.isTTY) {
+			const ans = await askLine(t("cli.wireConfirmWrite", { path }));
+			if (ans !== "y" && ans !== "yes") return 1;
+		}
+	}
+	const res = await applyWire(client, path, !!opts.unwire, false);
+	if (res === "added") console.log(t("cli.wireCreated", {
+		client,
+		path
+	}));
+	else if (res === "exists") console.log(t("cli.wireAlready", {
+		client,
+		path
+	}));
+	else if (res === "removed") console.log(t("cli.wireRemoved", {
+		client,
+		path
+	}));
+	else console.log(t("cli.wireNotWired", {
+		client,
+		path
+	}));
+	return 0;
+}
+/** wire: 单客户端非交互/半交互落位(--client 必填; 作用域默认交互询问) */
+async function wire(flags, runner) {
+	const t = makeT(await resolveFrameworkLocale(flags, runner));
+	const client = (flags.client ?? "").toLowerCase();
+	if (!isWireClient(client)) {
+		console.error(t("cli.wireUnknownClient", { client }));
+		return 1;
+	}
+	const scope = await resolveScope(flags, t);
+	if (!scope) return 1;
+	let repoRoot = null;
+	if (scope === "project") {
+		repoRoot = await resolveRepo(flags, runner);
+		if (!repoRoot) {
+			console.error(t("cli.wireNeedRepo"));
+			return 1;
+		}
+	}
+	return wireCore(client, scope, {
+		unwire: flags.unwire,
+		dryRun: flags.dryRun,
+		yes: flags.yes,
+		repoRoot
+	}, t);
+}
+/** setup: 交互向导(客户端 → 作用域 → 确认), 安装后一步式接线; 非交互终端拒绝并指路 wire */
+async function setup(flags, runner) {
+	const t = makeT(await resolveFrameworkLocale(flags, runner));
+	if (!process.stdin.isTTY) {
+		console.error(t("cli.setupNoTty"));
+		return 1;
+	}
+	console.log(t("cli.setupIntro"));
+	const client = (await askLine(t("cli.setupClientAsk"))).trim().toLowerCase();
+	if (!isWireClient(client)) {
+		console.error(t("cli.setupClientInvalid"));
+		return 1;
+	}
+	const scope = await resolveScope(flags, t);
+	if (!scope) return 1;
+	let repoRoot = null;
+	if (scope === "project") {
+		repoRoot = await resolveRepo(flags, runner);
+		if (!repoRoot) {
+			console.error(t("cli.wireNeedRepo"));
+			return 1;
+		}
+	}
+	return wireCore(client, scope, {
+		yes: flags.yes,
+		repoRoot
+	}, t);
+}
 function readStdin() {
 	return new Promise((resolve) => {
 		let data = "";

package/lib/index.mjs

@@ -1,2 +1,2 @@
-import { a as name, c as createPiExtension, g as registerLocale, i as formatDeny, m as MESSAGE_KEYS, n as apply, o as stateDir, r as evaluateCommand, s as userStateRoot, t as appendAudit } from "./src-CL6uB3oo.mjs";
+import { a as name, c as createPiExtension, g as registerLocale, i as formatDeny, m as MESSAGE_KEYS, n as apply, o as stateDir, r as evaluateCommand, s as userStateRoot, t as appendAudit } from "./src-DPJRoEJq.mjs";
 export { MESSAGE_KEYS, appendAudit, apply, createPiExtension, evaluateCommand, formatDeny, name, registerLocale, stateDir, userStateRoot };

package/lib/{src-CL6uB3oo.mjs → src-DPJRoEJq.mjs}

@@ -688,6 +688,31 @@ const en = {
 	"cli.auditEmpty": () => "  No audit entries yet",
 	"cli.checkInternalError": (v) => `[gitflow-guard] check internal error, allowed through: ${v.msg}`,
 	"cli.guardDisabledInvalidConfig": (v) => `[gitflow-guard] guard disabled: invalid config: ${v.err}`,
+	"cli.wireUnknownClient": (v) => `unknown client: ${v.client} (expected dsh|claude|codex|opencode|antigravity|pi)`,
+	"cli.wireNeedRepo": () => "project scope needs a git repository — run inside a repo or pass --repo <path>",
+	"cli.wireScopeAsk": () => "Scope — project (this repo only) or global (all repos on this machine)? [project/global] ",
+	"cli.wireScopeInvalid": () => "invalid scope (expected project or global)",
+	"cli.wireTarget": (v) => `${v.client}: wiring → ${v.path}`,
+	"cli.wireAlready": (v) => `${v.client}: hook already wired (${v.path})`,
+	"cli.wireCreated": (v) => `${v.client}: hook written → ${v.path}`,
+	"cli.wireRemoved": (v) => `${v.client}: hook removed → ${v.path}`,
+	"cli.wireNotWired": (v) => `${v.client}: no hook entry found (${v.path})`,
+	"cli.wireConfirmWrite": (v) => `Write ${v.path}? [y/N] `,
+	"cli.wireRefuseGlobal": () => "Refusing to modify a global config without confirmation — pass --yes to allow",
+	"cli.wireDshGuide": () => "DSH is an in-process plugin — no hook file to write. Mount it with: dsh plugin --profile web add agents-gitflow-guard",
+	"cli.wirePiGuide": () => "Pi is an in-process extension — no hook file to write. Copy pi/gitflow-guard.ts into .pi/extensions/ and list it in .pi/settings.json (see README).",
+	"cli.wireExperimental": (v) => `${v.client}: experimental support — verify the hook on a real device before relying on it`,
+	"cli.wireDryRunAdd": (v) => `${v.client}: [dry-run] would add hook → ${v.path}`,
+	"cli.wireDryRunRemove": (v) => `${v.client}: [dry-run] would remove hook → ${v.path}`,
+	"cli.wireDryRunNoOp": (v) => `${v.client}: [dry-run] nothing to do (${v.path})`,
+	"cli.statusUsingDefaults": () => "Config: built-in defaults (no gitflow-guard.config.json) — integration=develop, archive=main",
+	"cli.statusMainProtected": () => "  main is protected by default. Trunk / single-branch users: create gitflow-guard.config.json with \"enabled\": false, or map your own branches.",
+	"cli.statusWireHints": () => "Wiring:",
+	"cli.statusWireHint": (v) => `  ${v.client}: not wired — run: gitflow-guard wire --client ${v.client}`,
+	"cli.setupIntro": () => "gitflow-guard setup — wire one client for this project. (Ctrl+C to cancel)",
+	"cli.setupClientAsk": () => "Which client? [dsh|claude|codex|opencode|antigravity|pi] ",
+	"cli.setupClientInvalid": () => "invalid client (expected dsh|claude|codex|opencode|antigravity|pi)",
+	"cli.setupNoTty": () => "setup needs an interactive terminal — use: gitflow-guard wire --client <name> --yes",
 	"guardStrictConfigBroken.why": () => "Guard config is invalid while strict mode is enabled",
 	"guardStrictConfigBroken.next": () => "Fix gitflow-guard.config.json (or remove \"strict\": true) before retrying.",
 	"guardStrictInternalError.why": (v) => `Guard internal error while strict mode is enabled: ${v.msg}`,
@@ -698,13 +723,18 @@ Usage:
   gitflow-guard status [--repo <path>] [--locale <en|zh>]
   gitflow-guard audit [--lines <count>] [--repo <path>] [--locale <en|zh>]
   gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <path>] [--locale <en|zh>]
+  gitflow-guard wire --client <dsh|claude|codex|opencode|antigravity|pi> [--project|--global] [--unwire] [--dry-run] [--yes] [--repo <path>] [--locale <en|zh>]
+  gitflow-guard setup [--repo <path>] [--locale <en|zh>]
   gitflow-guard --help
 
 Notes:
   status/audit are read-only; the agent can self-inspect.
   --locale overrides the message language for this invocation (flag > project config > English).
   check reads the hook payload on stdin (platform-specific protocol: claude/opencode exit 2,
-  codex/antigravity JSON on stdout) and is meant for pre/post hooks of AI agents.`
+  codex/antigravity JSON on stdout) and is meant for pre/post hooks of AI agents.
+  wire writes each client's hook config into the project (default) or global scope; dsh/pi are
+  in-process and only print guidance. No config file needed — built-in defaults (develop+main)
+  apply out of the box; create gitflow-guard.config.json to override, or set "enabled": false to turn off.`
 };
 const zh = {
 	"role.integration": () => "集成分支",
@@ -765,6 +795,31 @@ const zh = {
 	"cli.auditEmpty": () => "  暂无审计记录",
 	"cli.checkInternalError": (v) => `[gitflow-guard] check 内部错误, 已放行: ${v.msg}`,
 	"cli.guardDisabledInvalidConfig": (v) => `[gitflow-guard] 守卫未启用: 配置无效: ${v.err}`,
+	"cli.wireUnknownClient": (v) => `未知客户端: ${v.client}(应为 dsh|claude|codex|opencode|antigravity|pi)`,
+	"cli.wireNeedRepo": () => "项目级作用域需要一个 git 仓库 — 请在仓库内运行, 或传 --repo <路径>",
+	"cli.wireScopeAsk": () => "作用域 — project(仅当前仓库) 还是 global(本机所有仓库)? [project/global] ",
+	"cli.wireScopeInvalid": () => "无效作用域(应为 project 或 global)",
+	"cli.wireTarget": (v) => `${v.client}: 接线 → ${v.path}`,
+	"cli.wireAlready": (v) => `${v.client}: hook 已接线(${v.path})`,
+	"cli.wireCreated": (v) => `${v.client}: hook 已写入 → ${v.path}`,
+	"cli.wireRemoved": (v) => `${v.client}: hook 已移除 → ${v.path}`,
+	"cli.wireNotWired": (v) => `${v.client}: 未找到 hook 条目(${v.path})`,
+	"cli.wireConfirmWrite": (v) => `写入 ${v.path}? [y/N] `,
+	"cli.wireRefuseGlobal": () => "拒绝在未确认时改动全局配置 — 传 --yes 允许",
+	"cli.wireDshGuide": () => "DSH 是进程内插件, 无需写入 hook 文件。挂载: dsh plugin --profile web add agents-gitflow-guard",
+	"cli.wirePiGuide": () => "Pi 是进程内扩展, 无需写入 hook 文件。把 pi/gitflow-guard.ts 拷到 .pi/extensions/ 并在 .pi/settings.json 登记(见 README)",
+	"cli.wireExperimental": (v) => `${v.client}: 实验支持 — 请在真机核验后再依赖它`,
+	"cli.wireDryRunAdd": (v) => `${v.client}: [dry-run] 将添加 hook → ${v.path}`,
+	"cli.wireDryRunRemove": (v) => `${v.client}: [dry-run] 将移除 hook → ${v.path}`,
+	"cli.wireDryRunNoOp": (v) => `${v.client}: [dry-run] 无需改动(${v.path})`,
+	"cli.statusUsingDefaults": () => "配置: 内置默认(无 gitflow-guard.config.json)— integration=develop, archive=main",
+	"cli.statusMainProtected": () => "  main 默认受保护。Trunk/单分支用户: 创建 gitflow-guard.config.json 写 \"enabled\": false, 或自行映射分支",
+	"cli.statusWireHints": () => "接线:",
+	"cli.statusWireHint": (v) => `  ${v.client}: 未接线 — 运行: gitflow-guard wire --client ${v.client}`,
+	"cli.setupIntro": () => "gitflow-guard setup — 为本项目接线一个客户端。(Ctrl+C 取消)",
+	"cli.setupClientAsk": () => "选哪个客户端? [dsh|claude|codex|opencode|antigravity|pi] ",
+	"cli.setupClientInvalid": () => "无效客户端(应为 dsh|claude|codex|opencode|antigravity|pi)",
+	"cli.setupNoTty": () => "setup 需要交互终端 — 请用: gitflow-guard wire --client <名字> --yes",
 	"guardStrictConfigBroken.why": () => "守卫配置无效, 且已启用 strict 模式",
 	"guardStrictConfigBroken.next": () => "请先修复 gitflow-guard.config.json(或移除 \"strict\": true)后重试",
 	"guardStrictInternalError.why": (v) => `守卫内部错误, 且已启用 strict 模式: ${v.msg}`,
@@ -775,13 +830,17 @@ const zh = {
   gitflow-guard status [--repo <路径>] [--locale <en|zh>]
   gitflow-guard audit [--lines <数量>] [--repo <路径>] [--locale <en|zh>]
   gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <路径>] [--locale <en|zh>]
+  gitflow-guard wire --client <dsh|claude|codex|opencode|antigravity|pi> [--project|--global] [--unwire] [--dry-run] [--yes] [--repo <路径>] [--locale <en|zh>]
+  gitflow-guard setup [--repo <路径>] [--locale <en|zh>]
   gitflow-guard --help
 
 说明:
   status/audit 只读, agent 可自查。
   --locale 可临时覆盖本次调用的文案语言(旗标 > 项目配置 > 英文)。
   check 读 stdin hook payload 做门禁(平台协议: claude/opencode exit 2, codex/antigravity stdout JSON),
-  供 Claude Code / Codex / OpenCode 等 agent 的 pre/post hook 调用。`
+  供 Claude Code / Codex / OpenCode 等 agent 的 pre/post hook 调用。
+  wire 把各客户端默认 hook 写入工程(默认)或全局作用域; dsh/pi 为进程内接入, 仅打印引导。
+  无需配置文件 — 内置默认(develop+main)开箱即用; 建 gitflow-guard.config.json 可覆盖, 或写 "enabled": false 关闭。`
 };
 /** 内置文案注册表: en 为兜底语言; 下游可经 registerLocale 追加 */
 const dicts = /* @__PURE__ */ new Map([["en", en], ["zh", zh]]);
@@ -821,10 +880,26 @@ function resolveLocale(v) {
 //#endregion
 //#region src/config.ts
 const CONFIG_FILE = "gitflow-guard.config.json";
-/** 默认配置(分支角色必须由项目显式配置, 无默认) */
+/**
+* 内置默认配置(零门槛开箱即用): 没有 gitflow-guard.config.json 也生效。
+* 默认保护 develop(integration, 只走 PR/MR) + main(archive, 归档合并在人)。
+* 用户 config 存在时按字段深度合并覆盖——只写想改的字段, 其余沿用默认。
+*/
 const DEFAULT_CONFIG = {
-	enabled: false,
+	enabled: true,
 	featurePattern: "feature/[\\w-]+",
+	branches: {
+		integration: {
+			branches: ["develop"],
+			update: "pr",
+			mergeBy: "anyone"
+		},
+		archive: {
+			branches: ["main"],
+			update: "pr",
+			mergeBy: "user"
+		}
+	},
 	ci: { enabled: true },
 	locale: "en"
 };
@@ -882,32 +957,30 @@ function mergeConfig(raw) {
 	if (typeof raw !== "object" || raw === null) return {
 		config: null,
 		errors: ["Config file must be a JSON object"],
-		warnings
+		warnings,
+		usingDefaults: false
 	};
 	const r = raw;
 	const strict = r.strict === true ? true : r.strict === false ? false : void 0;
 	if (r.strict !== void 0 && typeof r.strict !== "boolean") errors.push("strict must be a boolean");
-	const config = {
-		...DEFAULT_CONFIG,
-		ci: { ...DEFAULT_CONFIG.ci },
-		branches: { integration: {
-			branches: [],
-			update: "pr",
-			mergeBy: "anyone"
-		} }
-	};
+	const config = structuredClone(DEFAULT_CONFIG);
 	if (typeof r.enabled === "boolean") config.enabled = r.enabled;
 	if (typeof r.featurePattern === "string" && r.featurePattern !== "") config.featurePattern = r.featurePattern;
 	if (typeof r.locale === "string" && r.locale !== "") {
 		config.locale = r.locale;
 		if (resolveLocale(r.locale) !== r.locale) warnings.push(`unknown locale "${r.locale}"; falling back to en`);
 	} else if (r.locale !== void 0) errors.push("locale must be a string");
+	if (typeof r.ci === "object" && r.ci !== null) {
+		const ci = r.ci;
+		if (typeof ci.enabled === "boolean") config.ci.enabled = ci.enabled;
+	}
+	if (r.branches !== void 0 && (typeof r.branches !== "object" || r.branches === null)) errors.push("branches must be an object");
 	const b = r.branches ?? {};
 	if ("integration" in b) {
 		const { role, errors: e } = normalizeRole(b.integration, "integration", "pr", "anyone");
 		config.branches.integration = role;
 		errors.push(...e);
-	} else errors.push("branches.integration is required");
+	}
 	if (b.preview !== void 0) {
 		const { role, errors: e } = normalizeRole(b.preview, "preview", "pr", "anyone");
 		config.branches.preview = role;
@@ -923,14 +996,13 @@ function mergeConfig(raw) {
 		config.branches.archive = role;
 		errors.push(...e);
 	}
-	const ci = r.ci ?? {};
-	if (typeof ci.enabled === "boolean") config.ci.enabled = ci.enabled;
 	if (strict !== void 0) config.strict = strict;
 	errors.push(...validateConfig(config));
 	return {
 		config: errors.length > 0 ? null : config,
 		errors,
 		warnings,
+		usingDefaults: false,
 		...strict !== void 0 ? { strict } : {}
 	};
 }
@@ -960,21 +1032,23 @@ function validateConfig(config) {
 	}
 	return errors;
 }
-/** 从项目根加载配置; 无文件 = 未启用(opt-in) */
+/** 从项目根加载配置; 无文件 = 使用内置默认配置(开箱即用, develop/main 已受保护) */
 async function loadConfig(repoRoot) {
 	let text;
 	try {
 		text = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
 	} catch (e) {
 		if (e.code === "ENOENT") return {
-			config: null,
+			config: structuredClone(DEFAULT_CONFIG),
 			errors: [],
-			warnings: []
+			warnings: [],
+			usingDefaults: true
 		};
 		return {
 			config: null,
 			errors: [`Failed to read config file: ${e.message}`],
-			warnings: []
+			warnings: [],
+			usingDefaults: false
 		};
 	}
 	let raw;
@@ -986,6 +1060,7 @@ async function loadConfig(repoRoot) {
 			config: null,
 			errors: [`Failed to read config file: ${e.message}`],
 			warnings: [],
+			usingDefaults: false,
 			...strict ? { strict } : {}
 		};
 	}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agents-gitflow-guard",
-  "version": "0.0.19",
-  "description": "A configurable branch-role guard for AI coding agents (DSH / Claude Code / Codex / OpenCode / Antigravity / Pi) — integration/preview/production/archive, each with its own update rules",
+  "version": "0.0.21",
+  "description": "A configurable branch-role guard for AI coding agents (DSH / Claude Code / Codex / OpenCode / Antigravity / Pi) — zero-config defaults (develop+main) out of the box, deep-merge override, and per-client native hooks via gitflow-guard wire/setup; integration/preview/production/archive, each with its own update rules",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -42,7 +42,11 @@
     "git",
     "workflow",
     "guard",
-    "agent"
+    "agent",
+    "zero-config",
+    "onboarding",
+    "wire",
+    "setup"
   ],
   "repository": {
     "type": "git",