diff --git a/.github/workflows/pinvou-fork-ci.yml b/.github/workflows/pinvou-fork-ci.yml
index 64ae079dee..3f37a14153 100644
--- a/.github/workflows/pinvou-fork-ci.yml
+++ b/.github/workflows/pinvou-fork-ci.yml
@@ -18,6 +18,18 @@ env:
   CARGO_INCREMENTAL: 0
 
 jobs:
+  secrets:
+    name: Gitleaks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Scan repository and history
+        uses: docker://ghcr.io/gitleaks/gitleaks:v8.30.1
+        with:
+          args: detect --source=/github/workspace --redact --verbose
+
   check:
     runs-on: ubuntu-latest
     timeout-minutes: 45
diff --git a/.gitleaks.toml b/.gitleaks.toml
new file mode 100644
index 0000000000..26a3621d6c
--- /dev/null
+++ b/.gitleaks.toml
@@ -0,0 +1,16 @@
+[extend]
+useDefault = true
+
+[[allowlists]]
+description = "Upstream security tests use explicit non-production credential fixtures"
+targetRules = ["generic-api-key"]
+condition = "AND"
+regexTarget = "line"
+paths = [
+  '''^crates/tui/src/runtime_api/web\.rs$''',
+  '''^crates/tui/src/tui/onboarding/api_key\.rs$''',
+]
+regexes = [
+  '''let session_token = "cwws_0123456789abcdef0123456789abcdef";''',
+  '''app\.api_key_input = "sk-1234567890abcdef"\.to_string\(\);''',
+]
diff --git a/PINVOU_FORK.md b/PINVOU_FORK.md
new file mode 100644
index 0000000000..8137f49be9
--- /dev/null
+++ b/PINVOU_FORK.md
@@ -0,0 +1,73 @@
+# Pinvou Fork Baseline
+
+This repository is the public CodeWhale fork embedded by
+[Pinvou Agent](https://github.com/Pinvou/pinvou-agent). CodeWhale remains an
+independent upstream project; general-purpose fixes should be contributed to
+[Hmbown/CodeWhale](https://github.com/Hmbown/CodeWhale) whenever possible.
+
+## Pinned baseline
+
+- Upstream release: `v0.9.0`
+- Upstream commit: `d167c07c96282411956ea7f35ddb8227afa1402f`
+- Pinvou maintenance branch: `pinvou3-clean`
+- Pinvou baseline tag: `pinvou-v0.9.0-r1`
+
+Pinvou Agent pins the exact commit identified by the baseline tag. It does not
+follow the maintenance branch automatically.
+
+The fork was rebuilt on the public upstream release history. It preserves
+upstream commits, authorship, copyright, and the MIT license; it does not reuse
+the history of Pinvou's former private fork.
+
+## Maintained patch themes
+
+Pinvou keeps six long-lived patch themes:
+
+1. A library facade for embedding CodeWhale in a desktop host.
+2. Host-specific tool exposure, bounded file writes, and execution safety.
+3. A sealed prompt composer with host-controlled context and skill sources.
+4. Automation scheduling, stable conversation identity, and run retention.
+5. Host orchestration, structured workflow completion, cancellation, and OAuth
+   cancellation.
+6. Runtime route, context-budget, and shared automation APIs for the host.
+
+Small fixes are folded into the nearest theme instead of creating an
+unbounded patch stack. Product UI, platform integration, connectors, and
+distribution logic stay in Pinvou Agent rather than this fork.
+
+## Sync policy
+
+For an upstream update:
+
+1. Fetch upstream tags and select a public release baseline.
+2. Compare each Pinvou theme with the new upstream behavior.
+3. Remove patches already implemented upstream.
+4. Move host-only behavior to Pinvou Agent when it does not require an atomic
+   CodeWhale lifecycle change.
+5. Reapply the remaining themes as reviewable commits on the new baseline.
+6. Run formatting, all-target checks, `forkguard_` tests, and a full history
+   secret scan.
+7. Create a new immutable `pinvou-v<upstream>-r<N>` tag and update Pinvou
+   Agent's submodule pointer in a separate pull request.
+
+Never move or reuse an existing Pinvou baseline tag.
+
+## Verification
+
+The fork CI runs:
+
+```bash
+cargo fmt --all -- --check
+cargo check --workspace --all-targets --locked
+cargo test -p codewhale-tui --lib forkguard_ --locked
+gitleaks detect --source=. --redact --verbose
+```
+
+The parent repository additionally verifies that the pinned gitlink is
+reachable from this public repository and that a recursive clone succeeds.
+
+## License and attribution
+
+CodeWhale and these fork changes are available under the repository's
+[MIT License](LICENSE). Upstream copyright and contributor attribution are
+preserved.
diff --git a/README.md b/README.md
index 41aa53d175..cb1c3c0381 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,12 @@ commands, checks the results, and keeps going until the task is done or it
 needs you. TUI for interactive work, `codewhale exec` for scripts and CI.
 Rust, MIT, runs entirely on your machine.
 
+> **Pinvou fork notice:** the `pinvou3-clean` branch contains the small,
+> documented patch set used by
+> [Pinvou Agent](https://github.com/Pinvou/pinvou-agent). See
+> [PINVOU_FORK.md](PINVOU_FORK.md) for the upstream baseline, maintained patch
+> themes, sync policy, and verification commands.
+
 It started as `deepseek-tui`. The community that formed around it needed more
 providers, so now DeepSeek, Claude, GPT, Kimi, GLM, and 30+ others run through
 the same runtime and tools.
diff --git a/crates/tui/src/command_safety.rs b/crates/tui/src/command_safety.rs
index 5e99c5583f..1aab1adada 100644
--- a/crates/tui/src/command_safety.rs
+++ b/crates/tui/src/command_safety.rs
@@ -1707,7 +1707,7 @@ mod tests {
 
     // pinvou3-fork: 多行命令逐行分析,不再一刀切 Dangerous。
     // 原硬规则 (commit b2f6ef56 在 pinvou3-patches 上加的 careful hook) 误伤
-    // LLM 用 `\n` 串多个 cp / mkdir / mv 的合理批量操作 — h3c-ppt P7 阶段
+    // LLM 用 `\n` 串多个 cp / mkdir / mv 的合理批量产物操作
     // "拷贝 5 个 template 文件" 被无差别拦死。改成逐行 recurse 评估,任一行
     // Dangerous 才拦。
     #[test]