From 588dd58c0343a5b877f6f85c71b1dd47134fd27c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sun, 19 Jul 2026 05:11:00 +0000 Subject: [PATCH 1/2] docs: document init flags, policy profiles, and FORGE_GUARD_STRICT --- mintlify/cli/core.mdx | 36 ++++++++++++++++++++++++++++++++++++ mintlify/cli/overview.mdx | 11 +++++++++++ 2 files changed, 47 insertions(+) diff --git a/mintlify/cli/core.mdx b/mintlify/cli/core.mdx index 2fa9ac4..d65a39c 100644 --- a/mintlify/cli/core.mdx +++ b/mintlify/cli/core.mdx @@ -17,6 +17,42 @@ Emits `AGENTS.md`, `CLAUDE.md`, `.gemini/settings.json`, `.aider.conf.yml`, and (plus MCP server config for Roo Code and VS Code), and the `.gitattributes` union-merge rule the ledger needs. +`forge init` also merges Forge's hooks and permissions into the **global** +`~/.claude/settings.json`, so it announces the merge before writing. The merge is +idempotent, marker-guarded, and never clobbers user entries. + +### Init flags + +| Flag | What it does | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--profile ` | Pick the policy profile for this repo. Accepts `minimal` or `standard` (default). An invalid value aborts before any scaffold, `.forge/` write, or merge. | +| `--no-settings` | Skip the global `~/.claude/settings.json` merge entirely — only the per-repo config is written. | +| `--remove-settings` | Reverse a past settings merge. Forge-shaped hooks, permissions, statusline, and the `_forge` marker are removed; a timestamped backup is written first, and your own entries are preserved. Also invoked by `install.sh --uninstall`. | +| `--settings-only` | Only merge the global settings — don't touch the repo. Used by `install.sh` to wire hooks and permissions. | + +If the settings merge is refused or errors, `forge init` fails with exit 1 and writes the +reason to stderr rather than reporting success. + +### Policy profiles + +`--profile` selects the ruleset that `forge sync` compiles into each tool's native +config. Only two profiles are supported: + +- **`standard`** (default) — the full pack: shared memory rules, impact analysis, and the + complete guardrail hook set. +- **`minimal`** — a leaner ruleset for small repos or contributor forks. + +The legacy names `web-app`, `backend-service`, `library`, and `regulated` are deprecated +aliases of `standard`. They still work — `forge init` warns once, stores `standard`, and +existing configs holding a legacy name still sync as standard — but new repos should use +`standard` directly. Any other value is invalid and aborts before Forge touches the repo. + +```bash +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` Recompile the canonical source into each tool's native config files. diff --git a/mintlify/cli/overview.mdx b/mintlify/cli/overview.mdx index 490cef2..1f63d51 100644 --- a/mintlify/cli/overview.mdx +++ b/mintlify/cli/overview.mdx @@ -39,6 +39,17 @@ noticing. Commands are organized into five groups. and confidence meters. `NO_COLOR` turns color off, `FORCE_COLOR=1` forces it on. - **`--json`** is available on the substrate and most analysis commands for scripting. +## Environment variables + +| Variable | Effect | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `FORGE_ENFORCE=1` | Turn the substrate's strongest advisory signals into a hard block. | +| `FORGE_GUARD_STRICT=1` | Escalate the secret redactor's `DEGRADED` warning into a blocking exit. By default a redaction failure prints `secret redaction DEGRADED` to stderr and lets output through; strict mode refuses to emit anything the redactor couldn't fully scrub. Use it in CI or on shared boxes where an unredacted line is worse than a failed command. | +| `FORGE_NO_UPDATE_CHECK=1` | Silence the "commits behind upstream" notice in `forge doctor`. | +| `FORGE_NO_HINT=1` | Mute the one-time init tip that prompts you to run `forge init`. | +| `FORGE_VERBOSE=1` | Show the per-command banner (`Forge — …`) that is hidden by default. | +| `FORGE_EMBED=1` | Opt in to the embedding tier for memory recall (MinHash stays the zero-dependency default). | + Run `forge --help` for the always-current list, or `forge catalog` for the Start-Here index of every tool, crew, and guard with a one-line why. From 6239e1285b0e732d06e9b60ce68200cda1b048a3 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sun, 19 Jul 2026 05:19:17 +0000 Subject: [PATCH 2/2] docs: mirror init flags, profiles, and FORGE_GUARD_STRICT into translations --- mintlify/ar/cli/core.mdx | 41 +++++++++++++++++++++++++++++-- mintlify/ar/cli/overview.mdx | 13 +++++++++- mintlify/cli/core.mdx | 8 +++--- mintlify/cli/overview.mdx | 2 +- mintlify/cn/cli/core.mdx | 37 +++++++++++++++++++++++++++- mintlify/cn/cli/overview.mdx | 13 +++++++++- mintlify/hi/cli/core.mdx | 39 ++++++++++++++++++++++++++++- mintlify/hi/cli/overview.mdx | 13 +++++++++- mintlify/zh-CN/cli/core.mdx | 32 ++++++++++++++++++++++-- mintlify/zh-CN/cli/overview.mdx | 13 +++++++++- mintlify/zh-Hans/cli/core.mdx | 34 ++++++++++++++++++++++++- mintlify/zh-Hans/cli/overview.mdx | 13 +++++++++- 12 files changed, 241 insertions(+), 17 deletions(-) diff --git a/mintlify/ar/cli/core.mdx b/mintlify/ar/cli/core.mdx index a4e5d43..8e12984 100644 --- a/mintlify/ar/cli/core.mdx +++ b/mintlify/ar/cli/core.mdx @@ -1,13 +1,13 @@ --- title: "أوامر Core" -description: "تهيئة المستودع والحفاظ عليه: init وsync وdoctor وcatalog وdocs وupdate." +description: "تهيئة مستودع Forge والحفاظ عليه عبر init وsync وdoctor وcatalog وdocs وupdate — إضافةً إلى ملف السياسة والإعدادات وعلامات إلغاء التثبيت القابل للعكس." --- تُهيّئ مجموعة Core المستودع وتحافظ على صحته. ## `forge init` -بناء إعداد المستودع — يُصدر لكل أداة من مصدر مشترك. +بناء إعداد هذا المستودع — يُصدر لكل أداة من مصدر مشترك واحد. ```bash forge init @@ -17,6 +17,43 @@ forge init (إضافةً إلى إعداد خادم MCP لأدوات Roo Code وVS Code)، وقاعدة الدمج الاتحادي في `.gitattributes` التي يحتاجها السجل. +كما يدمج `forge init` خطّافات Forge وأذوناتها في ملف `~/.claude/settings.json` +**العام**، لذا يُعلن عن الدمج قبل الكتابة. الدمج عديم الأثر، محميّ بعلامة، ولا يُلغي +مطلقًا مدخلات المستخدم. + +### علامات init + +| العلامة | ماذا تفعل | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--profile ` | اختيار ملف السياسة لهذا المستودع. يقبل `minimal` أو `standard` (الافتراضي). قيمة غير صالحة تُجهض قبل أي بناء أو كتابة `.forge/` أو دمج. | +| `--no-settings` | تخطّي دمج ملف `~/.claude/settings.json` العام كليًا — تُكتب فقط الإعدادات الخاصة بالمستودع. | +| `--remove-settings` | عكس دمج إعدادات سابق. تُزال الخطّافات والأذونات وسطر الحالة ذات شكل Forge وعلامة `_forge`؛ تُكتب نسخة احتياطية موسومة بالوقت أولًا، وتُحفظ مدخلاتك. يُستدعى أيضًا من `install.sh --uninstall`. | +| `--settings-only` | دمج الإعدادات العامة فقط — لا يمسّ المستودع. يستخدمه `install.sh` لتوصيل الخطّافات والأذونات. | + +إذا رُفض دمج الإعدادات أو أخفق، يفشل `forge init` بخروج 1 ويكتب السبب إلى stderr بدلًا +من الإبلاغ عن النجاح. + +### ملفات السياسة + +تختار `--profile` مجموعة القواعد التي يُصرّفها `forge sync` إلى إعداد كل أداة الأصلي. +يُدعم ملفان اثنان فقط: + +- **`standard`** (الافتراضي) — الحزمة الكاملة: قواعد الذاكرة المشتركة، وتحليل الأثر، + ومجموعة الخطّافات الحارسة الكاملة. +- **`minimal`** — مجموعة قواعد أخفّ للمستودعات الصغيرة أو تفريعات المساهمين. + +الأسماء الموروثة `web-app` و`backend-service` و`library` و`regulated` أسماء بديلة +مهجورة لـ `standard`. لا تزال تعمل: يُحذّر `forge init` مرة واحدة، ويحفظ `standard`، +وتتزامن الإعدادات الحالية التي تحمل اسمًا موروثًا كما لو كانت standard. على المستودعات +الجديدة استخدام `standard` مباشرةً. أي قيمة أخرى غير صالحة وتُجهض قبل أن يمسّ Forge +المستودع. + +```bash +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` إعادة تصريف المصدر القانوني إلى ملفات الإعداد الأصلية لكل أداة. diff --git a/mintlify/ar/cli/overview.mdx b/mintlify/ar/cli/overview.mdx index 3d073f3..41a4e0d 100644 --- a/mintlify/ar/cli/overview.mdx +++ b/mintlify/ar/cli/overview.mdx @@ -1,6 +1,6 @@ --- title: "نظرة عامة على CLI" -description: "كل أمر من أوامر forge مُصنَّف حسب المجموعات Core وMemory وSubstrate وQuality وConfig — سطح الأوامر بيانات، ويتم توفيقه مع التوثيق بفحص انحراف صارم." +description: "كل أمر من أوامر forge مُصنَّف حسب المجموعات Core وMemory وSubstrate وQuality وConfig، إضافةً إلى متغيرات البيئة التي تتحكم في التنفيذ والمخرجات." --- يُعرَّف سطح أوامر `forge` كبيانات (`src/commands.js`)، ويتم توفيقه مع التوثيق عبر @@ -39,6 +39,17 @@ description: "كل أمر من أوامر forge مُصنَّف حسب المجم التجارية ومقاييس الثقة. `NO_COLOR` يوقف اللون، `FORCE_COLOR=1` يُفرضه. - **`--json`** متاح للركيزة ومعظم أوامر التحليل للسكربتات. +## متغيرات البيئة + +| المتغيّر | الأثر | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `FORGE_ENFORCE=1` | تحويل أقوى إشارات الركيزة الإرشادية إلى حجب صارم. | +| `FORGE_GUARD_STRICT=1` | ترقية تحذير `DEGRADED` لمُنقّي الأسرار إلى خروج حاجب. افتراضيًا، يطبع فشل الإخفاء `secret redaction DEGRADED` إلى stderr ويترك المخرَج يمرّ؛ الوضع الصارم يرفض إصدار أي شيء لم يستطع المنقّي تنظيفه كاملًا. استخدمه في CI أو على الأجهزة المشتركة حيث سطر غير مُخفَى أسوأ من أمر فاشل. | +| `FORGE_NO_UPDATE_CHECK=1` | إسكات إشعار "commits behind upstream" في `forge doctor`. | +| `FORGE_NO_HINT=1` | كتم تلميح init المُعروض لمرة واحدة الذي يدفعك إلى تشغيل `forge init`. | +| `FORGE_VERBOSE=1` | إظهار عنوان الأمر (`Forge — …`) المخفي افتراضيًا. | +| `FORGE_EMBED=1` | تفعيل طبقة التضمينات لاسترجاع الذاكرة (يبقى MinHash افتراضًا بدون تبعيات). | + شغّل `forge --help` للقائمة المحدَّثة دائمًا، أو `forge catalog` لفهرس البدء لكل أداة وطاقم وحاجز مع سبب موجز. diff --git a/mintlify/cli/core.mdx b/mintlify/cli/core.mdx index d65a39c..b2ef8fc 100644 --- a/mintlify/cli/core.mdx +++ b/mintlify/cli/core.mdx @@ -1,6 +1,6 @@ --- title: "Core commands" -description: "Bootstrap and maintain a repo: init, sync, doctor, catalog, docs, and update." +description: "Bootstrap and maintain a Forge repo with init, sync, doctor, catalog, docs, and update — plus profile, settings, and reversible-uninstall flags." --- The Core group bootstraps a repo and keeps it healthy. @@ -43,9 +43,9 @@ config. Only two profiles are supported: - **`minimal`** — a leaner ruleset for small repos or contributor forks. The legacy names `web-app`, `backend-service`, `library`, and `regulated` are deprecated -aliases of `standard`. They still work — `forge init` warns once, stores `standard`, and -existing configs holding a legacy name still sync as standard — but new repos should use -`standard` directly. Any other value is invalid and aborts before Forge touches the repo. +aliases of `standard`. They still work: `forge init` warns once, stores `standard`, and +existing configs holding a legacy name sync as standard. New repos should use `standard` +directly. Any other value is invalid and aborts before Forge touches the repo. ```bash forge init --profile minimal # leaner ruleset diff --git a/mintlify/cli/overview.mdx b/mintlify/cli/overview.mdx index 1f63d51..14e274d 100644 --- a/mintlify/cli/overview.mdx +++ b/mintlify/cli/overview.mdx @@ -1,6 +1,6 @@ --- title: "CLI overview" -description: "Every forge command, grouped by Core, Memory, Substrate, Quality, and Config — the command surface is data, reconciled against the docs by a strict drift check." +description: "Every forge command grouped by Core, Memory, Substrate, Quality, and Config, plus the environment variables that control enforcement and output." --- The `forge` command surface is defined as data (`src/commands.js`) and reconciled against diff --git a/mintlify/cn/cli/core.mdx b/mintlify/cn/cli/core.mdx index 68e14fc..c6f9304 100644 --- a/mintlify/cn/cli/core.mdx +++ b/mintlify/cn/cli/core.mdx @@ -1,6 +1,6 @@ --- title: "Core 命令" -description: "引导并维护一个仓库：init、sync、doctor、catalog、docs 和 update。" +description: "用 init、sync、doctor、catalog、docs、update 引导并维护 Forge 仓库 —— 加上 profile、settings 与可逆卸载相关标志。" --- Core 分组用于引导一个仓库并保持它的健康。 @@ -17,6 +17,41 @@ forge init （外加给 Roo Code 和 VS Code 的 MCP 服务器配置），以及账本所需的 `.gitattributes` union-merge 规则。 +`forge init` 还会把 Forge 的 hooks 和 permissions 合并进**全局**的 +`~/.claude/settings.json`，所以它会在写入前先声明这次合并。这次合并是幂等的、 +带标记守护的，永远不会覆盖用户自己的条目。 + +### Init 标志 + +| 标志 | 作用 | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--profile ` | 为本仓库挑选策略 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 +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` 把规范来源重新编译成每个工具的原生配置文件。 diff --git a/mintlify/cn/cli/overview.mdx b/mintlify/cn/cli/overview.mdx index 733bd81..ddf36d2 100644 --- a/mintlify/cn/cli/overview.mdx +++ b/mintlify/cn/cli/overview.mdx @@ -1,6 +1,6 @@ --- title: "CLI 概览" -description: "每个 forge 命令，按 Core、Memory、Substrate、Quality 和 Config 分组 —— 命令表本身就是数据，会被严格的漂移检查对着文档核对。" +description: "每个 forge 命令，按 Core、Memory、Substrate、Quality 和 Config 分组，外加控制强制执行与输出的环境变量。" --- `forge` 命令表以数据形式定义在 `src/commands.js` 里，并由 `forge docs check` @@ -39,6 +39,17 @@ description: "每个 forge 命令，按 Core、Memory、Substrate、Quality 和 置信度条。`NO_COLOR` 关闭颜色，`FORCE_COLOR=1` 强制打开。 - **`--json`** 在基底和大多数分析类命令上都可用，方便脚本化。 +## 环境变量 + +| 变量 | 作用 | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `FORGE_ENFORCE=1` | 把基底最强的建议性信号变成硬阻塞。 | +| `FORGE_GUARD_STRICT=1` | 把秘密脱敏器的 `DEGRADED` 警告升级为阻塞式退出。默认情况下，一次脱敏失败会把 `secret redaction DEGRADED` 打到 stderr 并放行输出；严格模式则拒绝输出任何脱敏器没能完全清洗干净的内容。适合在 CI 或共享机器上使用 —— 那里一行未脱敏内容比一次失败的命令更糟。 | +| `FORGE_NO_UPDATE_CHECK=1` | 让 `forge doctor` 里的"落后上游若干次提交"提示安静下来。 | +| `FORGE_NO_HINT=1` | 静音那条一次性、提示你去跑 `forge init` 的初始化提示。 | +| `FORGE_VERBOSE=1` | 显示每条命令默认隐藏的横幅（`Forge — …`）。 | +| `FORGE_EMBED=1` | 为记忆召回选择接入 embedding 层（MinHash 仍是零依赖的默认方案）。 | + 运行 `forge --help` 得到永远最新的命令列表，或 `forge catalog` 得到 一份"Start Here"索引，列出每个工具、crew 和护栏，附上一行简介。 diff --git a/mintlify/hi/cli/core.mdx b/mintlify/hi/cli/core.mdx index fd6630a..22c7abc 100644 --- a/mintlify/hi/cli/core.mdx +++ b/mintlify/hi/cli/core.mdx @@ -1,6 +1,6 @@ --- title: "Core कमांड्स" -description: "रेपो बूटस्ट्रैप और रखरखाव करें: init, sync, doctor, catalog, docs, और update।" +description: "Forge रेपो को init, sync, doctor, catalog, docs, और update से बूटस्ट्रैप और रखरखाव करें — साथ ही profile, settings, और reversible-uninstall फ़्लैग।" --- Core समूह एक रेपो को बूटस्ट्रैप करता है और उसे स्वस्थ रखता है। @@ -17,6 +17,43 @@ forge init निकालता है (साथ ही Roo Code और VS Code के लिए MCP सर्वर कॉन्फ़िग), और लेजर के लिए आवश्यक `.gitattributes` यूनियन-मर्ज नियम। +`forge init` Forge के हुक्स और अनुमतियों को **ग्लोबल** `~/.claude/settings.json` +में भी मर्ज करता है, इसलिए यह लिखने से पहले मर्ज की घोषणा करता है। मर्ज +idempotent है, मार्कर-गार्डेड है, और उपयोगकर्ता की प्रविष्टियों को कभी नहीं मिटाता। + +### Init फ़्लैग + +| फ़्लैग | यह क्या करता है | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--profile ` | इस रेपो के लिए पॉलिसी प्रोफ़ाइल चुनें। `minimal` या `standard` (डिफ़ॉल्ट) स्वीकार करता है। अमान्य मान किसी भी स्कैफ़ोल्ड, `.forge/` राइट, या मर्ज से पहले ही निरस्त कर देता है। | +| `--no-settings` | ग्लोबल `~/.claude/settings.json` मर्ज को पूरी तरह छोड़ दें — केवल प्रति-रेपो कॉन्फ़िग लिखा जाता है। | +| `--remove-settings` | किसी पिछले settings मर्ज को उलटें। Forge-आकार के हुक्स, अनुमतियाँ, statusline, और `_forge` मार्कर हटा दिए जाते हैं; पहले एक टाइमस्टैम्प वाला बैकअप लिखा जाता है, और आपकी अपनी प्रविष्टियाँ संरक्षित रहती हैं। `install.sh --uninstall` द्वारा भी आह्वान किया जाता है। | +| `--settings-only` | केवल ग्लोबल settings मर्ज करें — रेपो को न छुएँ। `install.sh` द्वारा हुक्स और अनुमतियाँ वायर करने के लिए उपयोग किया जाता है। | + +यदि settings मर्ज अस्वीकार किया जाता है या त्रुटि होती है, तो `forge init` सफलता की +रिपोर्ट करने के बजाय exit 1 के साथ विफल होता है और कारण को stderr पर लिखता है। + +### पॉलिसी प्रोफ़ाइल + +`--profile` वह रूलसेट चुनता है जिसे `forge sync` प्रत्येक टूल की नेटिव कॉन्फ़िग में +कंपाइल करता है। केवल दो प्रोफ़ाइल समर्थित हैं: + +- **`standard`** (डिफ़ॉल्ट) — पूरा पैक: साझा मेमोरी नियम, प्रभाव विश्लेषण, और + संपूर्ण गार्डरेल हुक सेट। +- **`minimal`** — छोटे रेपो या योगदानकर्ता फ़ॉर्क के लिए एक हल्का रूलसेट। + +पुराने नाम `web-app`, `backend-service`, `library`, और `regulated` `standard` के +पदावनत उपनाम हैं। वे अभी भी काम करते हैं: `forge init` एक बार चेतावनी देता है, +`standard` संग्रहीत करता है, और पुराने नाम धारण करने वाले मौजूदा कॉन्फ़िग standard के +रूप में sync होते हैं। नए रेपो को सीधे `standard` का उपयोग करना चाहिए। कोई भी अन्य +मान अमान्य है और Forge द्वारा रेपो को छूने से पहले ही निरस्त कर देता है। + +```bash +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` कैननिकल स्रोत को हर टूल की नेटिव कॉन्फ़िग फ़ाइलों में पुनः कंपाइल करें। diff --git a/mintlify/hi/cli/overview.mdx b/mintlify/hi/cli/overview.mdx index f6981fe..de68a2f 100644 --- a/mintlify/hi/cli/overview.mdx +++ b/mintlify/hi/cli/overview.mdx @@ -1,6 +1,6 @@ --- title: "CLI अवलोकन" -description: "हर forge कमांड, Core, Memory, Substrate, Quality, और Config के अनुसार समूहित — कमांड सतह डेटा है, जिसे एक कड़ी ड्रिफ्ट चेक द्वारा डॉक्स के विरुद्ध सुलझाया जाता है।" +description: "हर forge कमांड Core, Memory, Substrate, Quality, और Config के अनुसार समूहित, साथ ही वे env vars जो प्रवर्तन और आउटपुट को नियंत्रित करते हैं।" --- `forge` कमांड सतह डेटा (`src/commands.js`) के रूप में परिभाषित है और `forge docs check` @@ -39,6 +39,17 @@ description: "हर forge कमांड, Core, Memory, Substrate, Quality, कॉन्फ़िडेंस मीटर जोड़ता है। `NO_COLOR` रंग बंद करता है, `FORCE_COLOR=1` उसे बलपूर्वक चालू करता है। - **`--json`** स्क्रिप्टिंग के लिए सब्सट्रेट और अधिकांश एनालिसिस कमांड्स पर उपलब्ध है। +## एन्वायरनमेंट वेरिएबल्स + +| वेरिएबल | प्रभाव | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `FORGE_ENFORCE=1` | सब्सट्रेट के सबसे मज़बूत सलाहकारी संकेतों को हार्ड ब्लॉक में बदल दें। | +| `FORGE_GUARD_STRICT=1` | secret redactor की `DEGRADED` चेतावनी को एक ब्लॉकिंग exit में एस्केलेट करें। डिफ़ॉल्ट रूप से एक redaction विफलता stderr पर `secret redaction DEGRADED` प्रिंट करती है और आउटपुट को पास होने देती है; strict मोड कुछ भी उत्सर्जित करने से मना कर देता है जिसे redactor पूरी तरह स्क्रब नहीं कर सका। इसे CI में या साझा मशीनों पर उपयोग करें जहाँ एक बिना-redacted पंक्ति विफल कमांड से बुरा हो। | +| `FORGE_NO_UPDATE_CHECK=1` | `forge doctor` में "commits behind upstream" सूचना को शांत करें। | +| `FORGE_NO_HINT=1` | एक-बार आने वाला init संकेत मौन करें जो आपको `forge init` चलाने के लिए प्रेरित करता है। | +| `FORGE_VERBOSE=1` | प्रति-कमांड बैनर (`Forge — …`) दिखाएँ जो डिफ़ॉल्ट रूप से छिपा होता है। | +| `FORGE_EMBED=1` | मेमोरी recall के लिए एम्बेडिंग टियर में ऑप्ट-इन करें (MinHash शून्य-निर्भरता डिफ़ॉल्ट बना रहता है)। | + हमेशा-अद्यतन सूची के लिए `forge --help` चलाएँ, या हर टूल, क्रू, और गार्ड के एक-पंक्ति कारण के साथ Start-Here इंडेक्स के लिए `forge catalog`। diff --git a/mintlify/zh-CN/cli/core.mdx b/mintlify/zh-CN/cli/core.mdx index 712d61e..7eb8515 100644 --- a/mintlify/zh-CN/cli/core.mdx +++ b/mintlify/zh-CN/cli/core.mdx @@ -1,6 +1,6 @@ --- title: "Core 命令" -description: "引导并维护一个仓库:init、sync、doctor、catalog、docs 和 update。" +description: "用 init、sync、doctor、catalog、docs 和 update 引导并维护一个 Forge 仓库 —— 还包括 profile、settings 与可逆卸载相关参数。" --- Core 组用于引导一个仓库并保持其健康。 @@ -15,6 +15,34 @@ 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 ` | 为该仓库选择策略 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,而不是报告成功。 + +### 策略 profiles + +`--profile` 选择 `forge sync` 编译进每个工具原生配置的规则集。只支持两种 profile: + +- **`standard`**(默认)—— 完整包:共享内存规则、影响分析,以及完整的护栏 hook 集。 +- **`minimal`** —— 面向小仓库或贡献者分叉的更精简规则集。 + +历史名称 `web-app`、`backend-service`、`library` 和 `regulated` 是 `standard` 的已弃用别名。它们仍然可用:`forge init` 会警告一次、存为 `standard`,而现存持有历史名称的配置也会按 standard sync。新仓库应直接使用 `standard`。任何其他值都是无效的,并会在 Forge 触碰该仓库之前中止。 + +```bash +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` 把规范源重新编译为每个工具的原生配置文件。 @@ -66,4 +94,4 @@ forge update --check # report whether a newer version is available forge update --to # pin or downgrade to a specific version (v0.19+) ``` -每条路径都失败开放 —— 离线、没有上游或 detached HEAD 会返回"unknown",从不作为错误。`FORGE_NO_UPDATE_CHECK=1` 可静默 doctor 的提示。 +每条路径都失败开放 —— 离线、没有上游或 detached HEAD 会返回 "unknown",从不作为错误。`FORGE_NO_UPDATE_CHECK=1` 可静默 doctor 的提示。 diff --git a/mintlify/zh-CN/cli/overview.mdx b/mintlify/zh-CN/cli/overview.mdx index ff17b31..294c884 100644 --- a/mintlify/zh-CN/cli/overview.mdx +++ b/mintlify/zh-CN/cli/overview.mdx @@ -1,6 +1,6 @@ --- title: "CLI 概览" -description: "每一个 forge 命令,按 Core、Memory、Substrate、Quality 和 Config 分组 —— 命令面被视为数据,并由严格的漂移检查与文档对账。" +description: "每一个 forge 命令,按 Core、Memory、Substrate、Quality 和 Config 分组,以及控制执行与输出的环境变量。" --- `forge` 命令面以数据形式定义 (`src/commands.js`),并通过 `forge docs check` 与文档对账,因此任何命令的加入或消失都逃不过文档的注意。命令被组织成五个组。 @@ -30,6 +30,17 @@ description: "每一个 forge 命令,按 Core、Memory、Substrate、Quality 和 - **管道友好输出。** 管道下是纯文本;TTY 下加上品牌调色板颜色和置信度进度条。`NO_COLOR` 关闭颜色,`FORCE_COLOR=1` 强开。 - **`--json`** 在基座和大多数分析命令上可用,便于脚本化。 +## 环境变量 + +| 变量 | 作用 | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `FORGE_ENFORCE=1` | 把基座最强的建议信号转为硬阻断。 | +| `FORGE_GUARD_STRICT=1` | 把 secret 脱敏器的 `DEGRADED` 警告升级为阻断式退出。默认情况下,脱敏失败会向 stderr 打印 `secret redaction DEGRADED` 并放行输出;严格模式则拒绝输出任何脱敏器无法完全清洗的内容。适用于 CI 或共享机器 —— 那里一行未脱敏的内容比一条失败的命令更糟。 | +| `FORGE_NO_UPDATE_CHECK=1` | 静默 `forge doctor` 中的 "commits behind upstream" 提示。 | +| `FORGE_NO_HINT=1` | 静默一次性提示你运行 `forge init` 的初始化提示。 | +| `FORGE_VERBOSE=1` | 显示默认隐藏的每命令横幅 (`Forge — …`)。 | +| `FORGE_EMBED=1` | 为记忆召回开启 embedding 层(MinHash 仍是零依赖默认)。 | + 运行 `forge --help` 获取始终最新的列表,或运行 `forge catalog` 查看每个工具、crew 和护栏并附一行原因说明的 Start-Here 索引。 diff --git a/mintlify/zh-Hans/cli/core.mdx b/mintlify/zh-Hans/cli/core.mdx index b20b380..a09d6b3 100644 --- a/mintlify/zh-Hans/cli/core.mdx +++ b/mintlify/zh-Hans/cli/core.mdx @@ -1,6 +1,6 @@ --- title: "Core 命令" -description: "引导与维护一个仓库:init、sync、doctor、catalog、docs 和 update。" +description: "使用 init、sync、doctor、catalog、docs 和 update 引导与维护一个 Forge 仓库——还包括 profile、settings 以及可逆卸载相关的参数。" --- Core 分组负责引导一个仓库并保持它健康。 @@ -16,6 +16,38 @@ forge init 生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等 (以及给 Roo Code 和 VS Code 的 MCP 服务器配置),外加 ledger 所需的 `.gitattributes` union-merge 规则。 +`forge init` 还会把 Forge 的 hooks 和 permissions 合并到**全局**的 +`~/.claude/settings.json`,因此在写入之前会先声明这次合并。该合并是幂等的、由标记保护的, +永远不会覆盖用户自己的条目。 + +### Init 参数 + +| 参数 | 作用 | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--profile ` | 为本仓库选择策略 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 +forge init --profile minimal # 更精简的规则集 +forge init --no-settings # 只写仓库内配置,跳过全局合并 +forge init --remove-settings # 撤销一次过往的全局合并 +``` + ## `forge sync` 把规范源重新编译为每个工具的原生配置文件。 diff --git a/mintlify/zh-Hans/cli/overview.mdx b/mintlify/zh-Hans/cli/overview.mdx index 8a9ad1e..6205ee0 100644 --- a/mintlify/zh-Hans/cli/overview.mdx +++ b/mintlify/zh-Hans/cli/overview.mdx @@ -1,6 +1,6 @@ --- title: "CLI 概览" -description: "每一个 forge 命令,按 Core、Memory、Substrate、Quality 和 Config 分组——命令面本身是数据,通过严格的漂移检查与文档相互对账。" +description: "每一个 forge 命令,按 Core、Memory、Substrate、Quality 和 Config 分组,并列出控制强制策略与输出的环境变量。" --- `forge` 命令面被定义为数据(`src/commands.js`),并由 `forge docs check` 与文档对账,因此一个命令无法在不被文档察觉的情况下上线或消失。命令分为五组。 @@ -35,6 +35,17 @@ description: "每一个 forge 命令,按 Core、Memory、Substrate、Quality 和 - **管道友好的输出。** 被管道时输出纯文本;在 TTY 上会加上品牌配色和置信度进度条。`NO_COLOR` 关掉颜色,`FORCE_COLOR=1` 强制打开。 - **`--json`** 在基座和大多数分析命令中可用,便于脚本使用。 +## 环境变量 + +| 变量 | 作用 | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `FORGE_ENFORCE=1` | 把基座最强的建议性信号变成硬阻断。 | +| `FORGE_GUARD_STRICT=1` | 把 secret 脱敏器的 `DEGRADED` 警告升级为阻断性退出。默认情况下,脱敏失败会向 stderr 打印 `secret redaction DEGRADED` 并放行输出;严格模式会拒绝输出任何脱敏器无法完全清洗的内容。适合在 CI 或共享机器上使用,那里一行未脱敏的内容比一次失败的命令更糟。 | +| `FORGE_NO_UPDATE_CHECK=1` | 让 `forge doctor` 中 “落后上游若干 commit” 的提示保持静默。 | +| `FORGE_NO_HINT=1` | 关闭那条一次性、提示你运行 `forge init` 的初始化提示。 | +| `FORGE_VERBOSE=1` | 显示默认被隐藏的每命令横幅(`Forge — …`)。 | +| `FORGE_EMBED=1` | 为 memory recall 启用 embedding 分层(MinHash 仍是零依赖的默认)。 | + 运行 `forge --help` 查看始终最新的命令列表,或 `forge catalog` 查看每个工具、crew 与护栏的 Start-Here 索引及一句话说明。