FailproofAI · chhhee10 · Sep 8, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 8, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,18 @@
 - The 1.0.2 documentation overhaul is reverted: `docs/` and `README.md` go back byte-for-byte to the commit #756 merged onto, along with the 14 generated locales and 14 translated READMEs #759 regenerated from those English sources. The release half of #756 stays — `package.json` and the Cargo workspace are untouched, since they have moved on to 1.0.4-beta.0 and the release tag the CLI builds its daemon download URL from is that npm version. Under `## 1.0.2` the heading and its release narrative stay, because 1.0.2 did ship; the `### Docs` entries underneath described the overhaul and go with it. Leaving the locales in place was the alternative considered and rejected: the nightly translate job is content-hash cached, so pages whose pre-overhaul English hashes it had already seen would have been skipped rather than repaired, stranding every non-English reader on a translation of text that no longer exists (#773)
 - The landing page no longer opens with the harness paragraph claiming that "the same events, the same policies, and the same session history apply to every one" of the twelve. Removed from `docs/index.mdx` and all 14 locales (#773)
 
+- The commands the reverted docs teach are checked against the shipped CLI again, and three of them did not run at all: `failproofai pack add core` is refused (`"core" is no longer a pack name` — ours is a pack like anyone else's now), `failproofai pack add --bundled` is an unknown flag, and `pack build` retired into `publish`. `packs.mdx`, `publish-a-pack.mdx`, `failure-behavior.mdx` and `reference/failproof-cli.mdx` are corrected; `policy`, `pack` and `p` remain working aliases for `policies` and are documented as such rather than silently relied on (#788)
+- `failproofai config --connect <url> --token <key>` is no longer taught as the way to set a machine up. `--connect` short-circuits to enrolment and **returns** — no daemon, no hooks — so anyone who followed the quickstart got a machine that showed up in Cloud and then collected and enforced nothing. Fresh machines now get plain `failproofai config`, with the key arriving through `FAILPROOFAI_CLOUD_TOKEN` rather than argv, where `ps`, shell history and CI logs can all read it. Corrected in `start/quickstart.mdx`, `start/setup.mdx`, `reference/failproof-cli.mdx`, `reference/harnesses.mdx`, `reference/custom-agents.mdx` and `reference/overview.mdx` (#788)
+- Nothing claims that installing hooks enables the policy catalog any more. `policies --install` with no names wires hooks and touches no policy, and setup says so itself when it finishes ("Nothing is enforcing yet"), so `README.md` and `start/quickstart.mdx` now carry the `failproofai policies add FailproofAI/policies` step that actually puts guardrails on a machine — 38 policies, of which the pack's manifest switches on 10. The always-on `block-failproofai-commands` guard is documented separately, as the one thing enforcing before that command runs (#788)
+- The README's harness paragraph no longer promises "same events, same policies" across all twelve. `src/hooks/enforcement-capability.ts` is the authority and disagrees: blocking a tool call before it runs is verified on all twelve, but turn-end gates on eight — OpenCode, Pi, Hermes and Goose have none — so a Stop policy deployed on the strength of that sentence enforced nothing. It now states what is shared (one policy API, one session history), what is not, and links the per-harness matrix. `docs/index.mdx` lost the same sentence in #773; the README kept it (#788)
+- `--machine-label` is documented in the order it actually works. On `config` it is *always* a rename — the branch that reads it fires whenever `--connect` and `--disconnect` are absent, so `failproofai config --token <key> --machine-label <name>` never reaches the wizard and answers "this machine is not connected … so it has no name to change". Setup comes first, the label after (#788)
+- `sanitize-api-keys` is out of the README's "What it stops" table. It matches `PostToolUse`, which `ENFORCEMENT_CAPABILITY` classes observe-only, so the tool has already run and its output has already reached the model: it reports a secret rather than keeping one out of the context (#669). The nine policies left in that table are all `PreToolUse` and do gate the call, on every harness (#788)
+- 102 published pages across seven locales opened with two consecutive `---` lines, so Mintlify closed the frontmatter block before any key was in it and rendered `title:`, `description:` and `icon:` as body text on a page with no title — visible on `docs.befailproof.ai` for as long as it stood. The stray delimiter is stripped, and `findTranslationError` gained the check that could not have caught it: every existing test asks `YAML.parse`, which reads a leading `---` as a document-start marker and returns a clean `{title, …}`, so the defect was invisible to the validator that exists to prevent exactly this. A second, Mintlify-shaped view of the block is now compared against it (#788)
+- The builtin pages no longer disagree with the catalog about how many policies there are, or which of them are on. `builtin.mdx` claimed **40**; `POLICY_CATALOG` and `BUILTIN_POLICIES` both hold **39**, and the catalog page documents 39 names matching source exactly. Both numbers a reader meets are now stated together and once: 39 exist, **38** are selectable, and the 39th is `block-failproofai-commands` — always on, excluded from the pack because a pack may not declare `alwaysOn`. `--beta` is documented as adding nothing, because no policy is currently marked beta (#788)
+- The catalog's "Recommended baseline" listed **14** policies as the guided setup's selection. Setup selects nothing, the list is the pack manifest's own 10 defaults, and three of the fourteen — `block-rm-rf`, `block-force-push` and `block-secrets-write` — are **not** among them. Those are the guards a reader is most likely to assume are on, so the corrected list is followed by a warning naming all three and the command to enable each (#788)
+- The five `sanitize-*` rows in the catalog said they redact secrets "before the model sees them" while the same row named `PostToolUse` as the trigger. They match an observation-only event: the tool has already run and its output has already reached the model, so they report a secret rather than withhold one, and they are not a data-loss control (#669). Reworded, with a note pointing at the `PreToolUse` guards that do stop the read (#788)
+- `docs/start/integrations.mdx` is in the navigation. The hub page for the five framework guides was on disk and linked from `reference/overview.mdx` and `reference/custom-agents.mdx`, but listed in no sidebar, in English and all 14 locales. Nav and disk now agree exactly: 1020 entries, 1020 files, nothing orphaned and nothing dangling (#788)
+
 ### Dependencies
 
 - `fp-cloud-cli`: typer 0.27.1 → 0.27.2, click 8.4.2 → 8.5.0, posthog 7.42.0 → 7.44.2 (#771)
@@ -601,7 +613,7 @@ disappearing quietly.
 
 - Drop the Status link from the docs sidebar. It was a `navigation.global.anchors` entry, which Mintlify pins above the page tree on every page in every tab — permanent real estate for a link that answers a question almost no reader of a docs page is asking. Support stays, since that one is reached from anywhere in the docs by someone who is already stuck. (#718)
 
-- Drop a duplicated entry and a repeated `### Fixes` heading from this release's own section. The canary-images entry was committed twice — once carrying an unfilled `(#PR)` placeholder and once as `(#705)` — and the section then opened a second `### Fixes` block a few entries after the first. Both were invisible while the changelog was only ever read on GitHub; the release announcement renders straight from these sections, so a duplicated headline and a heading appearing twice were about to show up in a public channel. (#721)
+- Drop a duplicated entry and a repeated `### Fixes` heading from this release's own section. The canary-images entry was committed twice — once carrying an unfilled `(#788)` placeholder and once as `(#705)` — and the section then opened a second `### Fixes` block a few entries after the first. Both were invisible while the changelog was only ever read on GitHub; the release announcement renders straight from these sections, so a duplicated headline and a heading appearing twice were about to show up in a public channel. (#721)
 
 ## 1.0.1-beta.0 — 2026-08-14
 

diff --git a/README.md b/README.md
@@ -31,8 +31,11 @@ tool calls before they execute. 39 built-in policies. Zero latency. Runs locally
 ## Supported harnesses
 
 Twelve harnesses in two classes — ten coding CLIs, and two chat and assistant
-gateways (Hermes, OpenClaw). Same events, same policies, same session history,
-whichever one your agent runs in.
+gateways (Hermes, OpenClaw). One policy API and one session history across all
+of them. What a policy can *block* is per-harness: stopping a tool call before
+it runs is verified on all twelve, turn-end gates on eight. The
+[per-harness matrix](https://docs.befailproof.ai/reference/harnesses#enforcement-capability)
+lists the events each one honours.
 
 Agents that run in none of them report through the [Python SDK](https://docs.befailproof.ai/reference/custom-agents),
 which gives you tracing, sessions and audits. Enforcement there needs a hook in
@@ -136,19 +139,29 @@ your own runtime — [talk to us](mailto:support@befailproof.ai) and we'll map i
 
 ```sh
 npm install -g failproofai
-failproofai policies --install   # or just run `failproofai` and accept the first-run prompt
-failproofai
+failproofai config                             # wire up your agents and the daemon
+failproofai policies add FailproofAI/policies  # choose what to enforce
+failproofai                                    # dashboard on localhost:8020
 ```
 
-39 built-in policies activate immediately. Dashboard at `localhost:8020`. Disable the first-run prompt with `FAILPROOFAI_NO_FIRST_RUN=1`.
+Setup wires the hooks and picks **no** policies — that second command is what
+puts guardrails on the machine, and any pack is typed the same way
+(`failproofai policies add <owner>/<repo>`; `policies show <owner>/<repo>` reads
+one first). Run `failproofai config` with no terminal — CI, a container, an
+agent driving it — and it applies rather than asking. On a machine that has
+never been set up, any other command runs the same wizard first; disable that
+with `FAILPROOFAI_NO_FIRST_RUN=1`.
+
+Until a pack arrives, the only thing enforcing is `block-failproofai-commands`,
+which is always on and cannot be switched off or paused: an agent that can pause
+enforcement can switch off every other policy.
 
 ---
 
 ## What it stops
 
 | Policy | What it blocks |
 |---|---|
-| `sanitize-api-keys` | API keys leaking into the agent's context |
 | `block-env-files` | Reads of `.env` and other secret files |
 | `warn-repeated-tool-calls` | The agent looping on the same call |
 | `block-sudo` | Privilege escalation |
@@ -157,8 +170,11 @@ failproofai
 | `block-rm-rf` | Recursive file deletion |
 | `block-force-push` / `block-push-master` | `git push --force`, direct pushes to `main` |
 
-The first five apply to any agent that can call a tool. The last three are the
-developer favourites — coding CLIs are the harness class we cover deepest.
+Every one of these gates the call *before* it runs, so they hold on all twelve
+harnesses. The first four apply to any agent that can call a tool; the last
+three are the developer favourites — coding CLIs are the harness class we cover
+deepest. The `sanitize-*` family is separate: it runs after a tool returns, so
+it reports a secret in tool output rather than keeping it out of the context.
 
 → [All 39 built-in policies](https://docs.befailproof.ai/policies/builtin)
 

diff --git a/__tests__/scripts/translate-docs/validate-translation.test.ts b/__tests__/scripts/translate-docs/validate-translation.test.ts
@@ -23,6 +23,31 @@ describe("findTranslationError", () => {
     expect(error).toMatch(/does not parse/);
   });
 
+  it("flags a stray second opening delimiter", async () => {
+    // The exact shape that shipped to 102 published pages across seven locales.
+    // Every check that asks YAML calls this clean — YAML reads the leading
+    // `---` as a document-start marker and returns `{title, description}` — but
+    // Mintlify closes the block on line 2, so the keys render as body text and
+    // the page has no title at all. Only the second, Mintlify-shaped view sees
+    // it, which is the whole reason that view exists.
+    const rendered = `---\n---\ntitle: "Fähigkeit"\ndescription: "Eine Seite"\n---\n\n# Körper\n`;
+    const error = await findTranslationError(rendered, SOURCE);
+    expect(error).not.toBeNull();
+    expect(error).toContain("empty");
+    // Says what to do, not just what is wrong — the message is read by a model
+    // that has to produce a corrected page on the retry.
+    expect(error).toContain("exactly one opening `---`");
+  });
+
+  it("flags a stray second opening delimiter on a frontmatter-less source", async () => {
+    // Nothing about the defect depends on the source having frontmatter: the
+    // page is equally broken either way, so the check runs for every shape.
+    const rendered = `---\n---\ntitle: "Titel"\n---\n\nEtwas Prosa.\n`;
+    const error = await findTranslationError(rendered, README_SOURCE);
+    expect(error).not.toBeNull();
+    expect(error).toContain("empty");
+  });
+
   it("flags a frontmatter block the model dropped entirely", async () => {
     // A missing block is still valid YAML (mintlify tolerates it), so only the
     // key-parity check against the source catches it.

diff --git a/docs/ar/admin/keys-and-permissions.mdx b/docs/ar/admin/keys-and-permissions.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "المفاتيح والأذونات"
 description: "إنشاء مفاتيح API ذات نطاق محدد للآلات والأتمتة والمشغلين."
 icon: "key-round"

diff --git a/docs/ar/admin/overview.mdx b/docs/ar/admin/overview.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "الإدارة"
 description: "تشغيل الوصول والاستخدام والمنظمات والأمان دون دمجها في سير عمل الموثوقية."
 icon: "settings-2"

diff --git a/docs/ar/admin/usage.mdx b/docs/ar/admin/usage.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "الاستخدام"
 description: "فحص استهلاك المنظمة والنافذة الفعالة للفواتير."
 icon: "chart-no-axes-combined"

diff --git a/docs/ar/audits/agent-contracts.mdx b/docs/ar/audits/agent-contracts.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "سياق الوكيل"
 description: "أخبر المراجعات بما يجب أن يفعله كل وكيل، وما يجب أن ينتجه، وما يجب أن لا يفعله أبداً."
 icon: "bot"

diff --git a/docs/ar/audits/alerts.mdx b/docs/ar/audits/alerts.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "التنبيهات"
 description: "كتشف تكرار الحوادث وإعادة توجيهها إلى المستجيبين المناسبين."
 icon: "bell-ring"

diff --git a/docs/ar/audits/cadence.mdx b/docs/ar/audits/cadence.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "تكرار المراجعة"
 description: "حدد موعد تشغيل المراجعات المتكررة وكمية البيانات التي تراجعها."
 icon: "calendar-clock"

diff --git a/docs/ar/audits/findings-and-issues.mdx b/docs/ar/audits/findings-and-issues.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "النتائج والمشاكل"
 description: "تحويل أدلة التدقيق إلى عمل إعادة معالجة مملوك وقابل للتتبع."
 icon: "clipboard-check"

diff --git a/docs/ar/audits/recipes.mdx b/docs/ar/audits/recipes.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "وصفات التدقيق"
 description: "أهداف البداية للتحقيقات الشائعة لفشل الوكيل."
 icon: "book-open-check"

diff --git a/docs/ar/audits/run.mdx b/docs/ar/audits/run.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "تشغيل ومراجعة التدقيق"
 description: "قم بتشغيل التدقيق والتحقق من نطاقه وفحص النتائج الناتجة."
 icon: "play"

diff --git a/docs/ar/index.mdx b/docs/ar/index.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "اجعل وكيلك failproof"
 description: "قابلية المراقبة والإنفاذ لكل محرك يعمل به وكلاؤك — برامج سطر الأوامر للترميز، بوابات الدردشة، المساعدات المستضافة ذاتياً، والوكلاء المزودين بآليات المراقبة الخاصة بك."
 icon: "shield-check"

diff --git a/docs/ar/policies/custom.mdx b/docs/ar/policies/custom.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "سياسات مخصصة"
 description: "اكتب سياسة لحالة فشل فريدة من نوعها في سير عمل وكيلك."
 icon: "shield-plus"

diff --git a/docs/ar/policies/deploy.mdx b/docs/ar/policies/deploy.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "نشر السياسات"
 description: "طرح نسخة سياسة تمت مراجعتها على الأجهزة المخطط لها."
 icon: "cloud-upload"

diff --git a/docs/ar/policies/editor.mdx b/docs/ar/policies/editor.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "محرر السياسات"
 description: "إنشاء ومراجعة السياسات ذات الإصدارات من نمط فشل مؤكد."
 icon: "file-pen-line"

diff --git a/docs/ar/policies/failure-behavior.mdx b/docs/ar/policies/failure-behavior.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "سلوك الفشل"
 description: "فهم ما يحدث عند عدم توفر تقييم السياسة أو مُحقِّق محلي."
 icon: "shield-alert"

diff --git a/docs/ar/policies/fleet.mdx b/docs/ar/policies/fleet.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "نشر السياسات على الأجهزة"
 description: "تحديد الأجهزة المسجلة والمحدثة والتي تطبق إصدارات السياسات المقصودة."
 icon: "network"

diff --git a/docs/ar/policies/local-configuration.mdx b/docs/ar/policies/local-configuration.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "التكوين المحلي"
 description: "التحكم في نطاق السياسة والمعاملات والملفات المخصصة وإعدادات Failproof AI على مستوى الجهاز."
 icon: "file-cog"

diff --git a/docs/ar/policies/overview.mdx b/docs/ar/policies/overview.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "السياسات"
 description: "راقب أو وجّه أو احجب إجراءات الوكيل قبل أن تتكرر حالة فشل معروفة."
 icon: "shield-check"

diff --git a/docs/ar/policies/publish-a-pack.mdx b/docs/ar/policies/publish-a-pack.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "نشر حزمة"
 description: "شحن سياساتك الخاصة كإصدار GitHub يمكن لأي شخص تثبيته."
 icon: "upload"

diff --git a/docs/ar/policies/rollback.mdx b/docs/ar/policies/rollback.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "التراجع عن النشر"
 description: "استعادة نشر سياسة معروف عند حدوث اضطراب في عمل الوكيل الصحيح."
 icon: "rotate-ccw"

diff --git a/docs/ar/reference/cloud-cli.mdx b/docs/ar/reference/cloud-cli.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "Failproof Cloud CLI"
 description: "مرجع شامل للاستعلام عن وإدارة Failproof AI Cloud باستخدام fp."
 icon: "cloud-cog"

diff --git a/docs/ar/reference/evaluator-sdk.mdx b/docs/ar/reference/evaluator-sdk.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "Evaluator SDK"
 description: "أنشئ خدمة تقيّم جلسات Failproof AI بشكل متزامن أو غير متزامن."
 icon: "gauge"

diff --git a/docs/ar/reference/failproof-cli.mdx b/docs/ar/reference/failproof-cli.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "واجهة أوامر Failproof AI"
 description: "ثبّت الخطافات، أدِر السياسات المحلية، اتصل بالسحابة، وشغّل مراقب الخادم المحلي."
 icon: "terminal"

diff --git a/docs/ar/reference/policy-sdk.mdx b/docs/ar/reference/policy-sdk.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "السياسات المخصصة"
 description: "قم بتأليف واختبار ونشر سياسات JavaScript أو TypeScript لحالات الفشل الخاصة بوكلائك."
 icon: "shield-plus"

diff --git a/docs/ar/sessions/assistant.mdx b/docs/ar/sessions/assistant.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "مساعد Failproof"
 description: "حلل وشغل Failproof AI باستخدام اللغة الطبيعية، من الأسئلة والاستفسارات إلى لوحات المعلومات والتدقيق."
 icon: "message-square-text"

diff --git a/docs/ar/sessions/dashboards.mdx b/docs/ar/sessions/dashboards.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "لوحات المعلومات"
 description: "تتبع إشارات الموثوقية التي تهم الوكيل أو سير العمل."
 icon: "layout-dashboard"

diff --git a/docs/ar/sessions/errors.mdx b/docs/ar/sessions/errors.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "الأخطاء"
 description: "جمّع الأخطاء المتكررة وافتح الجلسات المرتبطة بها."
 icon: "circle-alert"

diff --git a/docs/ar/sessions/evaluations.mdx b/docs/ar/sessions/evaluations.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "التقييمات المباشرة"
 description: "قيّم الجلسات المباشرة والمكتملة من حيث الجودة والامتثال والتكلفة والكمون."
 icon: "gauge"

diff --git a/docs/ar/sessions/live-events.mdx b/docs/ar/sessions/live-events.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "الأحداث المباشرة"
 description: "شاهد نشاط الوكيل يصل أثناء تشغيل جلسة عمل."
 icon: "radio"

diff --git a/docs/ar/sessions/models.mdx b/docs/ar/sessions/models.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "النماذج"
 description: "قارن زمن الاستجابة والرموز واستخدام السياق وتوزيع حركة المرور بين النماذج."
 icon: "cpu"

diff --git a/docs/ar/sessions/overview.mdx b/docs/ar/sessions/overview.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "الجلسات"
 description: "ابدأ بسجل كامل لتشغيل وكيل واحد."
 icon: "workflow"

diff --git a/docs/ar/sessions/policy-decisions.mdx b/docs/ar/sessions/policy-decisions.mdx
@@ -1,5 +1,4 @@
 ---
----
 title: "قرارات السياسة"
 description: "اطّلع على السياسات المقيّمة والمحظورة والموجّهة والمسموح بها."
 icon: "shield-check"