From 9e7778bd7fc90c2276c36c559c9a743b15a0f563 Mon Sep 17 00:00:00 2001 From: chhhee10 Date: Tue, 8 Sep 2026 18:47:56 +0530 Subject: [PATCH 1/5] Fix the commands and claims the docs revert left behind MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #773 restored docs/ and README.md byte-for-byte to the pre-#756 commit, which was the right call for positioning and the wrong one for accuracy: that text describes a CLI two minor versions old. Three commands in it do not run at all, one sets a machine up wrong, and two claims the code contradicts. Verified against the shipped 1.0.4-beta.0 binary, not against memory: failproofai pack add core refused — "core" is no longer a pack name failproofai pack add --bundled unknown flag failproofai pack build retired into `publish` The worst one still exits 0. `failproofai config --connect --token ` was taught as first-machine setup in six pages, but `--connect` short-circuits to enrolment and RETURNS (bin/failproofai.mjs:2181) — the wizard never runs, so no daemon and no hooks. Anyone who followed the quickstart got a machine that appeared 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. Both of hermes-exosphere's blocking findings on #773: - "39 built-in policies activate immediately" (README:143) is false. `--install` with no names wires hooks and touches no policy (manager.ts:614), 1 of 39 is alwaysOn, and setup says so itself when it finishes: "Nothing is enforcing yet." The README and quickstart now carry the `policies add FailproofAI/policies` step that actually guards a machine, and document `block-failproofai-commands` separately as the one thing enforcing before it runs. - "Same events, same policies" across twelve harnesses (README:34) is what enforcement-capability.ts exists to prevent. Pre-tool blocking is verified on all twelve; turn-end gates on eight — OpenCode, Pi, Hermes and Goose have none, so a Stop policy deployed on that sentence enforced nothing. #773 removed the claim from docs/index.mdx and left the README. The advisory finding was worse than advisory. 102 pages across seven locales opened with two consecutive `---`, so Mintlify closed the frontmatter before any key was in it: docs.befailproof.ai/ar/policies/overview was rendering raw `title:` / `description:` / `icon:` as body text, on a page with no title. Stripped — and findTranslationError gained the check that could not have caught it, because every check there asks YAML.parse, which reads a leading `---` as a document-start marker and returns a clean {title, …}. A second Mintlify-shaped view of the block is now compared against it, with tests that fail without it. Also found while checking: `--machine-label` on `config` is always a rename (the branch fires whenever --connect and --disconnect are absent), so `config --token --machine-label ` never reaches the wizard — the docs now put the label after setup, not during. `sanitize-api-keys` is out of the README's "What it stops" table: it matches PostToolUse, which ENFORCEMENT_CAPABILITY classes observe-only, so it reports a secret rather than keeping one out of the context (#669, still open). And docs/start/integrations was linked from two pages but listed in no sidebar, in English and all 14 locales; nav and disk now agree exactly at 1020 each. English sources only — the nightly translate job regenerates the locales from them, as it did in #774. The 102 frontmatter fixes are direct because their English sources are unchanged and the job would not revisit them. Verified: validate:mdx 1034 pages clean, tsc --noEmit clean, lint 0 errors (5 pre-existing warnings), translate-docs suite 154 passed. --- CHANGELOG.md | 9 ++ README.md | 32 +++-- .../validate-translation.test.ts | 25 ++++ docs/ar/admin/keys-and-permissions.mdx | 1 - docs/ar/admin/overview.mdx | 1 - docs/ar/admin/usage.mdx | 1 - docs/ar/audits/agent-contracts.mdx | 1 - docs/ar/audits/alerts.mdx | 1 - docs/ar/audits/cadence.mdx | 1 - docs/ar/audits/findings-and-issues.mdx | 1 - docs/ar/audits/recipes.mdx | 1 - docs/ar/audits/run.mdx | 1 - docs/ar/index.mdx | 1 - docs/ar/policies/custom.mdx | 1 - docs/ar/policies/deploy.mdx | 1 - docs/ar/policies/editor.mdx | 1 - docs/ar/policies/failure-behavior.mdx | 1 - docs/ar/policies/fleet.mdx | 1 - docs/ar/policies/local-configuration.mdx | 1 - docs/ar/policies/overview.mdx | 1 - docs/ar/policies/publish-a-pack.mdx | 1 - docs/ar/policies/rollback.mdx | 1 - docs/ar/reference/cloud-cli.mdx | 1 - docs/ar/reference/evaluator-sdk.mdx | 1 - docs/ar/reference/failproof-cli.mdx | 1 - docs/ar/reference/policy-sdk.mdx | 1 - docs/ar/sessions/assistant.mdx | 1 - docs/ar/sessions/dashboards.mdx | 1 - docs/ar/sessions/errors.mdx | 1 - docs/ar/sessions/evaluations.mdx | 1 - docs/ar/sessions/live-events.mdx | 1 - docs/ar/sessions/models.mdx | 1 - docs/ar/sessions/overview.mdx | 1 - docs/ar/sessions/policy-decisions.mdx | 1 - docs/ar/sessions/read-a-trace.mdx | 1 - docs/ar/start/first-policy.mdx | 1 - docs/ar/start/integrations.mdx | 1 - docs/ar/start/integrations/crewai.mdx | 1 - docs/ar/start/integrations/langchain.mdx | 1 - docs/ar/start/quickstart.mdx | 1 - docs/ar/start/quickstarts/crewai.mdx | 1 - docs/ar/start/quickstarts/custom-agents.mdx | 1 - docs/ar/start/quickstarts/langchain.mdx | 1 - docs/docs.json | 15 +++ docs/he/admin/overview.mdx | 1 - docs/he/audits/agent-contracts.mdx | 1 - docs/he/audits/local-audit.mdx | 1 - docs/he/audits/overview.mdx | 1 - docs/he/audits/recipes.mdx | 1 - docs/he/index.mdx | 1 - docs/he/policies/custom.mdx | 1 - docs/he/reference/self-hosting.mdx | 1 - docs/he/sessions/evaluations.mdx | 1 - docs/he/sessions/live-events.mdx | 1 - docs/he/sessions/models.mdx | 1 - docs/he/start/integrations.mdx | 1 - docs/he/start/integrations/crewai.mdx | 1 - docs/he/start/integrations/llamaindex.mdx | 1 - docs/he/start/integrations/pydantic-ai.mdx | 1 - docs/hi/admin/keys-and-permissions.mdx | 1 - docs/hi/policies/custom.mdx | 1 - docs/hi/policies/failure-behavior.mdx | 1 - docs/hi/reference/local-dashboard.mdx | 1 - docs/hi/sessions/evaluations.mdx | 1 - docs/hi/start/integrations.mdx | 1 - docs/hi/start/integrations/crewai.mdx | 1 - docs/it/admin/overview.mdx | 1 - docs/it/audits/agent-contracts.mdx | 1 - docs/it/policies/local-configuration.mdx | 1 - docs/it/reference/evaluator-sdk.mdx | 1 - docs/it/reference/harnesses.mdx | 1 - docs/it/reference/local-dashboard.mdx | 1 - docs/it/sessions/assistant.mdx | 1 - docs/it/sessions/queries.mdx | 1 - docs/it/start/quickstarts/langchain.mdx | 1 - docs/policies/failure-behavior.mdx | 6 +- docs/policies/packs.mdx | 45 ++++--- docs/policies/publish-a-pack.mdx | 117 ++++++++++++------ docs/reference/custom-agents.mdx | 4 +- docs/reference/failproof-cli.mdx | 51 +++++--- docs/reference/harnesses.mdx | 10 +- docs/reference/overview.mdx | 4 +- docs/ru/audits/recipes.mdx | 1 - docs/ru/audits/setup.mdx | 1 - docs/ru/policies/publish-a-pack.mdx | 1 - docs/ru/sessions/assistant.mdx | 1 - docs/ru/start/integrations/crewai.mdx | 1 - docs/start/quickstart.mdx | 25 +++- docs/start/setup.mdx | 18 ++- docs/tr/admin/keys-and-permissions.mdx | 1 - docs/tr/admin/usage.mdx | 1 - docs/tr/admin/users-and-organizations.mdx | 1 - docs/tr/audits/alerts.mdx | 1 - docs/tr/audits/overview.mdx | 1 - docs/tr/audits/recipes.mdx | 1 - docs/tr/policies/builtin-catalog.mdx | 1 - docs/tr/reference/cloud-cli.mdx | 1 - docs/tr/reference/evaluator-sdk.mdx | 1 - docs/tr/reference/harnesses.mdx | 1 - docs/tr/reference/policy-sdk.mdx | 1 - docs/tr/reference/troubleshooting.mdx | 1 - docs/tr/sessions/overview.mdx | 1 - docs/tr/sessions/policy-decisions.mdx | 1 - docs/tr/start/concepts.mdx | 1 - docs/tr/start/quickstarts/langchain.mdx | 1 - docs/vi/admin/settings-and-security.mdx | 1 - docs/vi/audits/agent-contracts.mdx | 1 - docs/vi/audits/local-audit.mdx | 1 - docs/vi/audits/run.mdx | 1 - docs/vi/audits/setup.mdx | 1 - docs/vi/index.mdx | 1 - docs/vi/policies/failure-behavior.mdx | 1 - docs/vi/sessions/evaluations.mdx | 1 - docs/vi/start/integrations.mdx | 1 - docs/vi/start/setup.mdx | 1 - .../translate-docs/validate-translation.ts | 44 +++++++ 116 files changed, 301 insertions(+), 206 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 64b4f6dd5..cd2dc7cb4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,15 @@ - 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 (#PR) +- `failproofai config --connect --token ` 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` (#PR) +- 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 (#PR) +- 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 (#PR) +- `--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 --machine-label ` never reaches the wizard and answers "this machine is not connected … so it has no name to change". Setup comes first, the label after (#PR) +- `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 (#PR) +- 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 (#PR) +- `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 (#PR) + ### 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) diff --git a/README.md b/README.md index 636d2666b..9b396f776 100644 --- 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,11 +139,22 @@ 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 /`; `policies show /` 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. --- @@ -148,7 +162,6 @@ failproofai | 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 index 97d4eb43e..05f600b74 100644 --- 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 index 0f8682ef5..fc3ef8cb9 100644 --- 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 index 8827906ad..23483ed1d 100644 --- 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 index 532df2e43..066940331 100644 --- 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 index 442b6c2bb..abd6d8a32 100644 --- 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 index a7a8b5af1..bb9d34362 100644 --- 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 index 35661228f..32cf486b6 100644 --- 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 index 8655cd01e..ff12081d9 100644 --- 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 index d93b47879..402c90080 100644 --- 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 index 7b857ebaa..6e221a7d1 100644 --- 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 index 92b389a32..dea610256 100644 --- 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 index 5cd4348c8..6827b9df2 100644 --- 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 index b2aa395d4..55b293fb9 100644 --- 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 index ed6ed1238..9668f9c04 100644 --- 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 index ba16d9ece..e666f018a 100644 --- 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 index e2e5c65d5..4fcf2f76f 100644 --- 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 index 690de26c5..f8144b958 100644 --- 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 index 5e2a3ec67..9be3a2c13 100644 --- 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 index 602fdb5a2..048637e78 100644 --- 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 index 621137578..acecf62b1 100644 --- 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 index 41ebf2238..42b2069c5 100644 --- 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 index 6f3eb4f27..2084d1107 100644 --- 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 index 0344448d9..1339a14c2 100644 --- 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 index eb0e43a4b..1a433f1a8 100644 --- 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 index 6fd63c8fb..bc00d786f 100644 --- 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 index 318610784..a1fd12604 100644 --- 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 index 8277065b5..55f9df2cb 100644 --- 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 index ad4b8f0b1..8d5168a1a 100644 --- 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 index 7c678d3ac..a5476ae67 100644 --- 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 index b47c3ccec..862d72e63 100644 --- 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 index 5726912ee..9933bb518 100644 --- 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 index 6fe89515e..c972d4a2d 100644 --- a/docs/ar/sessions/policy-decisions.mdx +++ b/docs/ar/sessions/policy-decisions.mdx @@ -1,5 +1,4 @@ --- ---- title: "قرارات السياسة" description: "اطّلع على السياسات المقيّمة والمحظورة والموجّهة والمسموح بها." icon: "shield-check" diff --git a/docs/ar/sessions/read-a-trace.mdx b/docs/ar/sessions/read-a-trace.mdx index 212dddf39..a3600aa9c 100644 --- a/docs/ar/sessions/read-a-trace.mdx +++ b/docs/ar/sessions/read-a-trace.mdx @@ -1,5 +1,4 @@ --- ---- title: "قراءة التتبع" description: "ابحث عن الحدث الذي غيّر مسار جلسة الوكيل." icon: "route" diff --git a/docs/ar/start/first-policy.mdx b/docs/ar/start/first-policy.mdx index ccc76b888..6647e7f1f 100644 --- a/docs/ar/start/first-policy.mdx +++ b/docs/ar/start/first-policy.mdx @@ -1,5 +1,4 @@ --- ---- title: "منع فشلك الأول باستخدام سياسة" description: "قم بتأليف نسخة من السياسة، وانشرها في وضع المراقبة، ثم طبقها." icon: "shield-check" diff --git a/docs/ar/start/integrations.mdx b/docs/ar/start/integrations.mdx index 047a0ff6f..a56459630 100644 --- a/docs/ar/start/integrations.mdx +++ b/docs/ar/start/integrations.mdx @@ -1,5 +1,4 @@ --- ---- title: "جهز وكيلك" sidebarTitle: "الأطر العمل" description: "اربط أي إطار عمل وكيل مدعوم إلى Failproof AI برمز واحد." diff --git a/docs/ar/start/integrations/crewai.mdx b/docs/ar/start/integrations/crewai.mdx index 16861f7bf..e580e5d34 100644 --- a/docs/ar/start/integrations/crewai.mdx +++ b/docs/ar/start/integrations/crewai.mdx @@ -1,5 +1,4 @@ --- ---- title: "CrewAI" sidebarTitle: "CrewAI" description: "تجهيز الفرق والتدفقات والوكلاء حسب الدور والأدوات والذاكرة وردود الفعل البشرية." diff --git a/docs/ar/start/integrations/langchain.mdx b/docs/ar/start/integrations/langchain.mdx index c6f9eee46..a35b43efa 100644 --- a/docs/ar/start/integrations/langchain.mdx +++ b/docs/ar/start/integrations/langchain.mdx @@ -1,5 +1,4 @@ --- ---- title: "LangChain و LangGraph" sidebarTitle: "LangChain و LangGraph" description: "قم بتتبع الرسوم البيانية والعقد والأدوات والمسترجعات واستدعاءات النموذج برمز واحد." diff --git a/docs/ar/start/quickstart.mdx b/docs/ar/start/quickstart.mdx index b59e7768f..1daebeea6 100644 --- a/docs/ar/start/quickstart.mdx +++ b/docs/ar/start/quickstart.mdx @@ -1,5 +1,4 @@ --- ---- title: "البدء السريع" description: "التقط جلسة وكيل، ابحث عن عطل، وابدأ في منعه." icon: "zap" diff --git a/docs/ar/start/quickstarts/crewai.mdx b/docs/ar/start/quickstarts/crewai.mdx index d948814b2..9ee22d1db 100644 --- a/docs/ar/start/quickstarts/crewai.mdx +++ b/docs/ar/start/quickstarts/crewai.mdx @@ -1,5 +1,4 @@ --- ---- title: "CrewAI" description: "قم بالتثبيت والمراقبة وشاهد أول تتبع لك." icon: "/images/frameworks/crewai.svg" diff --git a/docs/ar/start/quickstarts/custom-agents.mdx b/docs/ar/start/quickstarts/custom-agents.mdx index e5b6d2347..a25d12073 100644 --- a/docs/ar/start/quickstarts/custom-agents.mdx +++ b/docs/ar/start/quickstarts/custom-agents.mdx @@ -1,5 +1,4 @@ --- ---- title: "وكلاء مخصصون" description: "غلّف وكيلك في ثلاث كتل `with` وسيبدأ التسجيل." icon: "code" diff --git a/docs/ar/start/quickstarts/langchain.mdx b/docs/ar/start/quickstarts/langchain.mdx index b16ccee4b..53c3f78f1 100644 --- a/docs/ar/start/quickstarts/langchain.mdx +++ b/docs/ar/start/quickstarts/langchain.mdx @@ -1,5 +1,4 @@ --- ---- title: "LangChain و LangGraph" description: "التثبيت والأداة والحصول على أول تتبع لديك." icon: "/images/frameworks/langchain.svg" diff --git a/docs/docs.json b/docs/docs.json index cda19dd2f..e8f6b669d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -121,6 +121,7 @@ { "group": "Plug in your agent", "pages": [ + "start/integrations", "start/integrations/custom-agents", "start/integrations/langchain", "start/integrations/crewai", @@ -283,6 +284,7 @@ { "group": "Plug in your agent", "pages": [ + "zh/start/integrations", "zh/start/integrations/custom-agents", "zh/start/integrations/langchain", "zh/start/integrations/crewai", @@ -439,6 +441,7 @@ { "group": "Plug in your agent", "pages": [ + "ja/start/integrations", "ja/start/integrations/custom-agents", "ja/start/integrations/langchain", "ja/start/integrations/crewai", @@ -595,6 +598,7 @@ { "group": "Plug in your agent", "pages": [ + "ko/start/integrations", "ko/start/integrations/custom-agents", "ko/start/integrations/langchain", "ko/start/integrations/crewai", @@ -751,6 +755,7 @@ { "group": "Plug in your agent", "pages": [ + "es/start/integrations", "es/start/integrations/custom-agents", "es/start/integrations/langchain", "es/start/integrations/crewai", @@ -907,6 +912,7 @@ { "group": "Plug in your agent", "pages": [ + "pt-br/start/integrations", "pt-br/start/integrations/custom-agents", "pt-br/start/integrations/langchain", "pt-br/start/integrations/crewai", @@ -1063,6 +1069,7 @@ { "group": "Plug in your agent", "pages": [ + "de/start/integrations", "de/start/integrations/custom-agents", "de/start/integrations/langchain", "de/start/integrations/crewai", @@ -1219,6 +1226,7 @@ { "group": "Plug in your agent", "pages": [ + "fr/start/integrations", "fr/start/integrations/custom-agents", "fr/start/integrations/langchain", "fr/start/integrations/crewai", @@ -1375,6 +1383,7 @@ { "group": "Plug in your agent", "pages": [ + "ru/start/integrations", "ru/start/integrations/custom-agents", "ru/start/integrations/langchain", "ru/start/integrations/crewai", @@ -1531,6 +1540,7 @@ { "group": "Plug in your agent", "pages": [ + "hi/start/integrations", "hi/start/integrations/custom-agents", "hi/start/integrations/langchain", "hi/start/integrations/crewai", @@ -1687,6 +1697,7 @@ { "group": "Plug in your agent", "pages": [ + "tr/start/integrations", "tr/start/integrations/custom-agents", "tr/start/integrations/langchain", "tr/start/integrations/crewai", @@ -1843,6 +1854,7 @@ { "group": "Plug in your agent", "pages": [ + "vi/start/integrations", "vi/start/integrations/custom-agents", "vi/start/integrations/langchain", "vi/start/integrations/crewai", @@ -1999,6 +2011,7 @@ { "group": "Plug in your agent", "pages": [ + "it/start/integrations", "it/start/integrations/custom-agents", "it/start/integrations/langchain", "it/start/integrations/crewai", @@ -2155,6 +2168,7 @@ { "group": "Plug in your agent", "pages": [ + "ar/start/integrations", "ar/start/integrations/custom-agents", "ar/start/integrations/langchain", "ar/start/integrations/crewai", @@ -2311,6 +2325,7 @@ { "group": "Plug in your agent", "pages": [ + "he/start/integrations", "he/start/integrations/custom-agents", "he/start/integrations/langchain", "he/start/integrations/crewai", diff --git a/docs/he/admin/overview.mdx b/docs/he/admin/overview.mdx index e549af854..ffe88835f 100644 --- a/docs/he/admin/overview.mdx +++ b/docs/he/admin/overview.mdx @@ -1,5 +1,4 @@ --- ---- title: "ניהול" description: "נהל גישה, שימוש, ארגונים וביטחון ללא עירוב שלהם בזרימת העבודה של אמינות." icon: "settings-2" diff --git a/docs/he/audits/agent-contracts.mdx b/docs/he/audits/agent-contracts.mdx index bb2e66a8c..671c42b06 100644 --- a/docs/he/audits/agent-contracts.mdx +++ b/docs/he/audits/agent-contracts.mdx @@ -1,5 +1,4 @@ --- ---- title: "הקשר סוכן" description: "ספר לביקורות מה כל סוכן חייב לעשות, להפיק, ולעולם לא לעשות." icon: "bot" diff --git a/docs/he/audits/local-audit.mdx b/docs/he/audits/local-audit.mdx index 2e09ecbb4..50eda92f2 100644 --- a/docs/he/audits/local-audit.mdx +++ b/docs/he/audits/local-audit.mdx @@ -1,5 +1,4 @@ --- ---- title: "审核本地代理历史记录" description: "离线扫描受支持的代理 CLI 历史记录，并在本地审查风险或浪费的行为。" icon: "laptop-minimal-check" diff --git a/docs/he/audits/overview.mdx b/docs/he/audits/overview.mdx index 8dc687f4d..c73b7eb66 100644 --- a/docs/he/audits/overview.mdx +++ b/docs/he/audits/overview.mdx @@ -1,5 +1,4 @@ --- ---- title: "ביקורות" description: "בדוק אוכלוסיית פגיעויות מוגדרת לכשלים שעקבות בלבד לא יגידו עליהם." icon: "scan-search" diff --git a/docs/he/audits/recipes.mdx b/docs/he/audits/recipes.mdx index 2dd3dc4a3..5466ac6cc 100644 --- a/docs/he/audits/recipes.mdx +++ b/docs/he/audits/recipes.mdx @@ -1,5 +1,4 @@ --- ---- title: "מתכונים ביקורת" description: "יעדים התחלתיים לחקירות נפוצות של כשלים בסוכנים." icon: "book-open-check" diff --git a/docs/he/index.mdx b/docs/he/index.mdx index ede5a62cb..dbcf5ee98 100644 --- a/docs/he/index.mdx +++ b/docs/he/index.mdx @@ -1,5 +1,4 @@ --- ---- title: "הפוך את הסוכן שלך לבטוח מטעויות" description: "נראות והטלת אכיפה על כל ההרתמה שהסוכנים שלך מריצים - CLIs קידוד, שערי צ'אט, עוזרים עצמאיים והסוכנים המותאמים שלך." icon: "shield-check" diff --git a/docs/he/policies/custom.mdx b/docs/he/policies/custom.mdx index 7735b35c4..fa36bd27c 100644 --- a/docs/he/policies/custom.mdx +++ b/docs/he/policies/custom.mdx @@ -1,5 +1,4 @@ --- ---- title: "מדיניויות מותאמות" description: "כתוב מדיניות עבור מצב כשל ייחודי לזרימת העבודה של הסוכן שלך." icon: "shield-plus" diff --git a/docs/he/reference/self-hosting.mdx b/docs/he/reference/self-hosting.mdx index 4f0b72ed5..1df6da179 100644 --- a/docs/he/reference/self-hosting.mdx +++ b/docs/he/reference/self-hosting.mdx @@ -1,5 +1,4 @@ --- ---- title: "Self-host Failproof AI Cloud" description: "פרוס את מישור הבקרה של Failproof AI על קלסטר Kubernetes המנוהל על ידי הלקוח." icon: "cloud-cog" diff --git a/docs/he/sessions/evaluations.mdx b/docs/he/sessions/evaluations.mdx index 328d60cb1..2b37f70d3 100644 --- a/docs/he/sessions/evaluations.mdx +++ b/docs/he/sessions/evaluations.mdx @@ -1,5 +1,4 @@ --- ---- title: "הערכות מקוונות" description: "דירוג הפעלות חיות ושהסתיימו לאיכות, ציות, עלות ותופעת השהיה." icon: "gauge" diff --git a/docs/he/sessions/live-events.mdx b/docs/he/sessions/live-events.mdx index 5e24741da..59b9c5ea1 100644 --- a/docs/he/sessions/live-events.mdx +++ b/docs/he/sessions/live-events.mdx @@ -1,5 +1,4 @@ --- ---- title: "אירועים בזמן אמת" description: "צפו בפעילות הסוכן בזמן ביצוע הסשן." icon: "radio" diff --git a/docs/he/sessions/models.mdx b/docs/he/sessions/models.mdx index 72f10ff2d..94666771c 100644 --- a/docs/he/sessions/models.mdx +++ b/docs/he/sessions/models.mdx @@ -1,5 +1,4 @@ --- ---- title: "Models" description: "השווה בין latency של מודלים, tokens, שימוש בקונטקסט, והפצת תעבורה." icon: "cpu" diff --git a/docs/he/start/integrations.mdx b/docs/he/start/integrations.mdx index f88a2c9fe..3c67d164c 100644 --- a/docs/he/start/integrations.mdx +++ b/docs/he/start/integrations.mdx @@ -1,5 +1,4 @@ --- ---- title: "הוספת כלים לסוכן שלך" sidebarTitle: "Frameworks" description: "חבר כל framework סוכן נתמך ל-Failproof AI בקריאה אחת." diff --git a/docs/he/start/integrations/crewai.mdx b/docs/he/start/integrations/crewai.mdx index c58033a42..b7d5b367d 100644 --- a/docs/he/start/integrations/crewai.mdx +++ b/docs/he/start/integrations/crewai.mdx @@ -1,5 +1,4 @@ --- ---- title: "CrewAI" sidebarTitle: "CrewAI" description: "ניהול צוות, זרימות, סוכנים לפי תפקיד, כלים, זיכרון ומשוב אנושי." diff --git a/docs/he/start/integrations/llamaindex.mdx b/docs/he/start/integrations/llamaindex.mdx index 267cc8c80..e36fb1d6b 100644 --- a/docs/he/start/integrations/llamaindex.mdx +++ b/docs/he/start/integrations/llamaindex.mdx @@ -1,5 +1,4 @@ --- ---- title: "LlamaIndex" sidebarTitle: "LlamaIndex" description: "Instrument workflows, steps, function agents, and retrievers." diff --git a/docs/he/start/integrations/pydantic-ai.mdx b/docs/he/start/integrations/pydantic-ai.mdx index 685b36d59..ca0aced10 100644 --- a/docs/he/start/integrations/pydantic-ai.mdx +++ b/docs/he/start/integrations/pydantic-ai.mdx @@ -1,5 +1,4 @@ --- ---- title: "Pydantic AI" sidebarTitle: "Pydantic AI" description: "הגן על אג'נטים מוקלדים, כלים, קריאות מודל וניסיונות חוזרים." diff --git a/docs/hi/admin/keys-and-permissions.mdx b/docs/hi/admin/keys-and-permissions.mdx index 405a74a4b..ba9fd66d5 100644 --- a/docs/hi/admin/keys-and-permissions.mdx +++ b/docs/hi/admin/keys-and-permissions.mdx @@ -1,5 +1,4 @@ --- ---- title: "कुंजियाँ और अनुमतियाँ" description: "मशीनों, स्वचालन और ऑपरेटरों के लिए स्कोप की गई API कुंजियाँ बनाएँ।" icon: "key-round" diff --git a/docs/hi/policies/custom.mdx b/docs/hi/policies/custom.mdx index 7c04250fe..05edc823e 100644 --- a/docs/hi/policies/custom.mdx +++ b/docs/hi/policies/custom.mdx @@ -1,5 +1,4 @@ --- ---- title: "कस्टम नीतियां" description: "अपने agent वर्कफ़्लो के लिए अद्वितीय विफलता मोड के लिए एक नीति लिखें।" icon: "shield-plus" diff --git a/docs/hi/policies/failure-behavior.mdx b/docs/hi/policies/failure-behavior.mdx index 1c635b52e..42bccfe67 100644 --- a/docs/hi/policies/failure-behavior.mdx +++ b/docs/hi/policies/failure-behavior.mdx @@ -1,5 +1,4 @@ --- ---- title: "विफलता व्यवहार" description: "समझें कि जब नीति मूल्यांकन या स्थानीय daemon अनुपलब्ध हो तो क्या होता है।" icon: "shield-alert" diff --git a/docs/hi/reference/local-dashboard.mdx b/docs/hi/reference/local-dashboard.mdx index c6d49c557..bb30c11f6 100644 --- a/docs/hi/reference/local-dashboard.mdx +++ b/docs/hi/reference/local-dashboard.mdx @@ -1,5 +1,4 @@ --- ---- title: "लोकल डैशबोर्ड" description: "लोकल प्रोजेक्ट, सेशन, पॉलिसी एक्टिविटी, कॉन्फ़िगरेशन, ऑडिट और शेड्यूल्ड स्कैन की समीक्षा करें।" icon: "monitor-cog" diff --git a/docs/hi/sessions/evaluations.mdx b/docs/hi/sessions/evaluations.mdx index 5f5e4fae5..4eb1d3d31 100644 --- a/docs/hi/sessions/evaluations.mdx +++ b/docs/hi/sessions/evaluations.mdx @@ -1,5 +1,4 @@ --- ---- title: "ऑनलाइन मूल्यांकन" description: "गुणवत्ता, अनुपालन, लागत और विलंबता के लिए लाइव और पूर्ण सत्रों को स्कोर करें।" icon: "gauge" diff --git a/docs/hi/start/integrations.mdx b/docs/hi/start/integrations.mdx index 7f4e3eebc..336abed0e 100644 --- a/docs/hi/start/integrations.mdx +++ b/docs/hi/start/integrations.mdx @@ -1,5 +1,4 @@ --- ---- title: "अपने एजेंट को इंस्ट्रूमेंट करें" sidebarTitle: "Frameworks" description: "किसी भी समर्थित एजेंट फ्रेमवर्क को Failproof AI से एक कॉल के साथ कनेक्ट करें।" diff --git a/docs/hi/start/integrations/crewai.mdx b/docs/hi/start/integrations/crewai.mdx index 0ed13312e..d09708955 100644 --- a/docs/hi/start/integrations/crewai.mdx +++ b/docs/hi/start/integrations/crewai.mdx @@ -1,5 +1,4 @@ --- ---- title: "CrewAI" sidebarTitle: "CrewAI" description: "Crews, flows, agents को भूमिका, tools, memory और human feedback द्वारा instrument करें।" diff --git a/docs/it/admin/overview.mdx b/docs/it/admin/overview.mdx index 3bbdb458d..ee1356207 100644 --- a/docs/it/admin/overview.mdx +++ b/docs/it/admin/overview.mdx @@ -1,5 +1,4 @@ --- ---- title: "Amministrazione" description: "Gestisci accesso, utilizzo, organizzazioni e sicurezza senza mischiarli nel flusso di lavoro di affidabilità." icon: "settings-2" diff --git a/docs/it/audits/agent-contracts.mdx b/docs/it/audits/agent-contracts.mdx index 05743e556..161e0ff22 100644 --- a/docs/it/audits/agent-contracts.mdx +++ b/docs/it/audits/agent-contracts.mdx @@ -1,5 +1,4 @@ --- ---- title: "Contesto dell'agente" description: "Indica ai controlli cosa deve fare, produrre e non fare mai ogni agente." icon: "bot" diff --git a/docs/it/policies/local-configuration.mdx b/docs/it/policies/local-configuration.mdx index 549621077..a758d9606 100644 --- a/docs/it/policies/local-configuration.mdx +++ b/docs/it/policies/local-configuration.mdx @@ -1,5 +1,4 @@ --- ---- title: "Configurazione locale" description: "Controlla l'ambito delle policy, i parametri, i file personalizzati e le impostazioni di Failproof AI a livello di macchina." icon: "file-cog" diff --git a/docs/it/reference/evaluator-sdk.mdx b/docs/it/reference/evaluator-sdk.mdx index 693304db9..0fc260696 100644 --- a/docs/it/reference/evaluator-sdk.mdx +++ b/docs/it/reference/evaluator-sdk.mdx @@ -1,5 +1,4 @@ --- ---- title: "Evaluator SDK" description: "Costruisci un servizio che valuta le sessioni di Failproof AI in modo sincrono o asincrono." icon: "gauge" diff --git a/docs/it/reference/harnesses.mdx b/docs/it/reference/harnesses.mdx index 701f74256..5839de80c 100644 --- a/docs/it/reference/harnesses.mdx +++ b/docs/it/reference/harnesses.mdx @@ -1,5 +1,4 @@ --- ---- title: "Harness per agent" description: "Cattura sessioni e applica policy su tutti i 12 harness per agent supportati." icon: "plug-zap" diff --git a/docs/it/reference/local-dashboard.mdx b/docs/it/reference/local-dashboard.mdx index e2a200ef4..d00b81828 100644 --- a/docs/it/reference/local-dashboard.mdx +++ b/docs/it/reference/local-dashboard.mdx @@ -1,5 +1,4 @@ --- ---- title: "Dashboard locale" description: "Rivedi progetti locali, sessioni, attività delle policy, configurazione, audit e scansioni pianificate." icon: "monitor-cog" diff --git a/docs/it/sessions/assistant.mdx b/docs/it/sessions/assistant.mdx index ac6815ebd..ad66c6b21 100644 --- a/docs/it/sessions/assistant.mdx +++ b/docs/it/sessions/assistant.mdx @@ -1,5 +1,4 @@ --- ---- title: "Failproof Assistant" description: "Analizza e gestisci Failproof AI in linguaggio naturale, da domande e query a dashboard e audit." icon: "message-square-text" diff --git a/docs/it/sessions/queries.mdx b/docs/it/sessions/queries.mdx index a474e1f37..9d760555d 100644 --- a/docs/it/sessions/queries.mdx +++ b/docs/it/sessions/queries.mdx @@ -1,5 +1,4 @@ --- ---- title: "Query" description: "Esplora i dati di sessione, evento e valutazione con SQL riutilizzabile." icon: "database" diff --git a/docs/it/start/quickstarts/langchain.mdx b/docs/it/start/quickstarts/langchain.mdx index 473332274..97db6c747 100644 --- a/docs/it/start/quickstarts/langchain.mdx +++ b/docs/it/start/quickstarts/langchain.mdx @@ -1,5 +1,4 @@ --- ---- title: "LangChain e LangGraph" description: "Installa, strumenta e visualizza la tua prima traccia." icon: "/images/frameworks/langchain.svg" diff --git a/docs/policies/failure-behavior.mdx b/docs/policies/failure-behavior.mdx index 15865cd3c..176be13a2 100644 --- a/docs/policies/failure-behavior.mdx +++ b/docs/policies/failure-behavior.mdx @@ -61,7 +61,9 @@ It does not fire for: ### What to do ```bash -failproofai pack list +failproofai policies ``` -It names any installed pack that will not load, says why, and exits non-zero. Then either reinstall it (`failproofai pack add `) or remove it (`failproofai pack remove `) — removing it withdraws the expectation, and the deny stops with it. +The listing names any installed pack that will not load and says why, alongside everything else enforcing here. Then either reinstall it (`failproofai policies add `) or remove it (`failproofai policies remove `) — removing it withdraws the expectation, and the deny stops with it. + +The deny itself is attributed to `pack/failproofai-pack-unavailable`, which outranks the policies that did load, so a blocked tool call names the missing pack rather than whichever surviving guard happened to fire first. diff --git a/docs/policies/packs.mdx b/docs/policies/packs.mdx index 8f1db2d19..870439776 100644 --- a/docs/policies/packs.mdx +++ b/docs/policies/packs.mdx @@ -9,33 +9,37 @@ A pack is a set of policies published as a GitHub release. One command installs ## Install the Failproof AI policies ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -That installs the set we publish, from the copy inside the package — so it needs no network and cannot fail behind a proxy. Take part of it: +That installs the set we publish, fetched and pinned from its own GitHub release — ours is a pack like anyone else's, typed the same way, with no short name only we can use. It carries 38 policies and switches on the 10 its manifest marks as safe to enable unattended; the rest are listed for you to choose. Take part of it instead: ```bash -failproofai pack add core --policy block-rm-rf # one, or a comma-separated few -failproofai pack add core --category dangerous-commands # a whole category -failproofai pack add core --all # everything in it +failproofai policies add FailproofAI/policies --policy block-rm-rf # one, or a comma-separated few +failproofai policies add FailproofAI/policies --category dangerous-commands # a whole category +failproofai policies add FailproofAI/policies --all # everything in it ``` -`failproofai pack list` names every category the pack offers. +`failproofai policies show FailproofAI/policies` names every category the pack offers. + + + This is the one step of setup that needs the network. `failproofai config` wires the hooks and deliberately chooses **no** policies, so a machine that has only been set up is not yet enforcing one — it tells you so when it finishes. + ## See what a pack contains, before installing it ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` Lists every policy the pack carries, grouped by category, marking which ones its author switches on by default and which are opt-in. It reads **only the manifest** — the entry artifact is never downloaded and never imported, so looking at a stranger's pack cannot run a stranger's code. The manifest is still checked against the release's own `SHA256SUMS`, so what you are reading is what would install. -`failproofai pack list` with no source lists the packs already installed here. +`failproofai policies` with no arguments lists what is already installed here — packs included, alongside builtin, convention and custom policies. ## Install somebody else's pack ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` Any of these work — paste whichever you have: @@ -54,9 +58,9 @@ Naming no tag installs the newest release **and pins it**, then tells you which By default you get the pack's **own** defaults — the policies its author marked safe to switch on unattended — not everything it contains. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add acme/support-agent --category billing,git +failproofai policies add acme/support-agent --policy block-refunds +failproofai policies add acme/support-agent --all ``` `--category` and `--policy` combine as a union (`--only` is accepted as a synonym for `--policy`). Re-adding at a newer version keeps whatever you chose rather than switching the rest back on. @@ -64,11 +68,11 @@ failproofai pack add acme/support-agent --all ## Manage what is on ```bash -failproofai policies # every source in one list, packs included -failproofai pack list # packs only, grouped by category +failproofai policies # every source in one list, packs included +failproofai policies show acme/support-agent # what a pack out there carries failproofai policies --uninstall block-refunds # turn one pack policy off failproofai policies --install block-refunds # and back on -failproofai pack remove acme/support-agent +failproofai policies remove acme/support-agent # uninstall the pack ``` A bare name means the **builtin** when one exists by that name. Name a pack's copy explicitly when you need to: @@ -83,13 +87,16 @@ If a pack ships a policy whose name is also an **enabled builtin**, the builtin ## Where the Failproof AI policies come from -`core` reads the copy vendored in the npm package. The same set is published as a GitHub release, which is what you install if you want a specific version: +The same place anyone else's do — a GitHub release, fetched and pinned like any other pack. The npm package carries no copy of them and there is no short name reserved for ours, so the set we publish is installed and versioned exactly the way yours would be: ```bash -failproofai pack add core # from this package, no network -failproofai pack add FailproofAI/policies # the same set, from its GitHub release +failproofai policies add FailproofAI/policies # newest release, pinned +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # a specific one +failproofai policies show FailproofAI/policies --releases # everything it has published ``` +The one policy that does ship compiled into the package is `block-failproofai-commands`, the always-on guard: a pack may not declare `alwaysOn`, because a downloaded file no local command can switch off is the thing that guard exists to prevent. + ## What integrity does and does not buy `SHA256SUMS` ships in the same release as the artifact, so it is **not** a signature and proves nothing about who published it. What it does prove is that the bytes are the ones that release published — and because the digest is recorded when you add the pack and re-verified before every import, a pack cannot change under your machine afterwards. A repository that retags or replaces an asset stops loading instead of quietly running something else. @@ -98,7 +105,7 @@ At install time the pack is also **imported once** and checked against its own m ## When a pack will not load -A pack this machine was told to enforce and cannot run **denies** the events its missing policies covered, rather than allowing them silently. See [Failure behavior](/policies/failure-behavior). `failproofai pack list` names any pack in that state and exits non-zero. +A pack this machine was told to enforce and cannot run **denies** the events its missing policies covered, rather than allowing them silently — as `pack/failproofai-pack-unavailable`, which outranks the policies that did load so the deny is attributed to the missing pack rather than to whichever guard happened to fire first. The exception is `UserPromptSubmit`, which instructs instead: denying there would lock you out of the agent you need in order to fix it. See [Failure behavior](/policies/failure-behavior). ## Offline and mirrors diff --git a/docs/policies/publish-a-pack.mdx b/docs/policies/publish-a-pack.mdx index 54a977e10..4f5e8b026 100644 --- a/docs/policies/publish-a-pack.mdx +++ b/docs/policies/publish-a-pack.mdx @@ -4,11 +4,19 @@ description: "Ship your own policies as a GitHub release that anyone can install icon: "upload" --- -A pack is three files attached to a GitHub release. `failproofai pack build` writes all three from a policy file you already have. +A pack is three files attached to a GitHub release. `failproofai publish` writes all three from the policy files in front of it, creates the release, and uploads them. ## 1. Write the policies -One file, using the same API as any custom policy. Two extra fields matter for a pack: +Start from something that already works rather than a template with blanks: + +```bash +failproofai publish --init +``` + +That asks what the pack is called, writes `.mjs`, and stops — no network, no git, nothing published. The file it writes is one policy that already blocks `git push --force`. It refuses to overwrite a file that exists. + +Policies use the same API as any custom policy. Two extra fields matter for a pack: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,105 @@ customPolicies.add({ }); ``` -`defaultEnabled` defaults to **false** when you omit it. A plain `failproofai pack add` switches on only what you marked — installing a stranger's every policy unattended is not a decision the installer should make for its user. +`defaultEnabled` defaults to **false** when you omit it. A plain `failproofai policies add` switches on only what you marked — installing a stranger's every policy unattended is not a decision the installer should make for its user. + +Write as many files as you like; one per category reads well. Every file in the directory that registers policies is bundled into the single artifact a pack has to be. -The entry must be **one self-contained file**. Only the entry is digest-pinned, so a pack that imports local files could not honestly claim the digest covers what runs. Bundle first (`esbuild`, `bun build`, `rollup`) and build the pack from the bundle — `pack build` refuses a local import rather than shipping a promise it cannot keep. +Bundling needs **bun**. Without it, keep to one self-contained file. Either way the published entry must not import local files at install time: only the entry is digest-pinned, so a pack that reached for siblings could not honestly claim the digest covers what runs — and `publish` refuses one rather than shipping a promise it cannot keep. -## 2. Build the release assets +## 2. Try it here first + +Before anyone else can see it, enforce the file on this machine: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs ``` -It writes three files, and validates every policy with the **loader's own rules** first — so a pack that could never install fails here, where you can fix it: +Any path, any filename. Ask your agent to do the thing you blocked and watch it get refused. Nothing is published and nobody else is affected. + +## 3. Publish it + +```bash +failproofai publish +``` + +It asks **where** only when nothing tells it — no git remote to read — and works the rest out. In order, stopping before it touches GitHub if anything is wrong: + +1. Finds the policy files here by **content** (files that import `failproofai` and call `customPolicies.add`), not by filename. Not recursive: publishing a fixture is worse than being asked. +2. Reads the repo from `git remote get-url origin`, in the **file's** directory rather than yours, and decides the version. +3. Finds your credential: `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth login`. It needs release-write and nothing else, and is never printed. +4. Creates the repository if it does not exist. +5. Builds the three assets, validating with the **loader's own rules** — the code that decides what may install on a stranger's machine. A pack that could never install fails here, where you can fix it. +6. Creates or reuses the release and uploads, replacing assets of the same name. | File | What it is | | --- | --- | | `failproofai-pack.json` | The manifest: id, version, effect, and one entry per policy | -| `failproofai-pack.mjs` | Your entry, verbatim | +| `failproofai-pack.mjs` | Your bundled entry | | `SHA256SUMS` | ` ` for the other two | +The asset names are fixed — they are what a consumer's CLI constructs its URLs from, with no API call and no discovery. + Refused at build time: an id that is not `publisher/name`, a policy name containing `/`, a policy declaring `alwaysOn`, a missing `description`, `category` or `match`, an entry that registers nothing, and an entry that imports local files. -## 3. Attach them to a release +Use `--dry-run` to build the assets and publish nothing; it needs no credential. -Tag the release with the same version you built, and attach all three files as release assets: +## How the version is decided -```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS -``` +The **commit you are publishing from** — its short sha, twelve characters: `a1b2c3d4e5f6`. Nothing to pick and nothing to count, and it names exactly where the bytes came from. Publish the same source twice and you get the same version, because there is nothing to increment. -Anyone can now install it: +Twelve characters rather than git's seven: seven collides in a repository with enough objects, and a version that stops being unique means two artifacts claiming one name. The full sha is recorded beside it. -```bash -failproofai pack add acme/support-agent -``` +It is read from the tree in front of you, never from the repository's releases, so a fresh clone and an air-gapped machine compute the same answer and neither has to ask GitHub what happened before. -The asset names are fixed — they are what a consumer's CLI constructs its URLs from, with no API call and no discovery. +It **refuses rather than guessing** in two cases, because the version claims to name a commit and must not be minted where that is false: -## Shipping a new version +| Case | Why | +| --- | --- | +| No git checkout | There is no commit to name | +| Uncommitted changes | Those bytes are not in that commit | + +`--version` overrides both, and a tag on `HEAD` wins over the sha — someone who tagged `v1.2.0` has said what this release is. -Build with the new `--version`, tag a new release, attach the three assets again. Consumers run the same `pack add` and keep whatever subset they had chosen; a policy they turned off stays off across the upgrade. +A sha does not order. `failproofai policies show / --releases` is where you see which came first, newest at the top. -Changing a policy's **name** is a breaking change: a machine that had turned it off is turning off a name that no longer exists, and the new name arrives at whatever `defaultEnabled` says. + + The release also records the commit you published from, in the manifest and in the release notes. That is **provenance, not verification** — the artifact digest is still the only thing that decides whether the bytes are the ones that were published. It answers the question a digest cannot: which source produced them. + -## What your users are trusting +## The repository must be public -`SHA256SUMS` lives in the same release as the artifact, so it proves the bytes are the ones you published — not who you are. Whoever can write to the repository can write both files. Your users' protection is that the digest is pinned when they install, so what you shipped cannot change under them afterwards. +Installs are anonymous HTTPS with no credential to offer, so a private repository publishes to nobody. A repo `publish` creates is public for that reason; an existing private one is **refused**, before anything is built, created or uploaded. -Publish from a repository whose write access you control, and treat a pack release like publishing a package. +`--allow-private` publishes to one anyway, for somebody who will hand the three assets over another way — it still says plainly that no `policies add` can reach them. -## Observe before you enforce +Only the release matters. Installs read `releases/download//` and never touch your git tree; pushing the source is for humans. -A manifest may declare `"effect": "observe"`. Those policies run and their verdicts are **recorded and discarded** — nothing is blocked. It is the way to measure a new rule against real traffic before it can interrupt anyone's work. +## Install it -```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +```bash +failproofai policies add acme/support-agent # newest release, pinned +failproofai policies add acme/support-agent@a1b2c3d4e5f6 # that exact one +failproofai policies show acme/support-agent --releases # everything published ``` + +## Options + +| Flag | Use | +| --- | --- | +| `--init [file]` | Write a starter policy and stop | +| `--repo /` | Where to release it, created if missing | +| `--version ` | Name the version, instead of the commit it was built from | +| `--id ` | The pack's id. Defaults to `--repo` | +| `--tag ` | Release tag. Defaults to the version; a `v` prefix is fine | +| `--notes ` | Release notes | +| `--out ` | Where to write the assets. Default `dist-pack` | +| `--effect ` | `enforce` or `observe`. `observe` records and blocks nothing. Default `enforce` | +| `--dry-run` | Build the assets, publish nothing. No credential needed | +| `--allow-private` | Publish to an already-private repo anyway. Nobody can install it | + +## Shipping a new version + +Commit the change and run `failproofai publish` again — the new commit is the new version. Consumers run the same `failproofai policies add` and keep whatever subset they had chosen; a policy they turned off stays off across the upgrade. diff --git a/docs/reference/custom-agents.mdx b/docs/reference/custom-agents.mdx index 938a3b5b9..0568f7976 100644 --- a/docs/reference/custom-agents.mdx +++ b/docs/reference/custom-agents.mdx @@ -38,9 +38,7 @@ The package is installed as `failproofai-sdk` and imported in Python as `failpro ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + FAILPROOFAI_CLOUD_TOKEN= failproofai config failproofai config --status ``` diff --git a/docs/reference/failproof-cli.mdx b/docs/reference/failproof-cli.mdx index 49242ed3d..db3328f68 100644 --- a/docs/reference/failproof-cli.mdx +++ b/docs/reference/failproof-cli.mdx @@ -6,37 +6,46 @@ icon: "terminal" Install the local CLI with `npm install -g failproofai`. Run it with no arguments to open the local policy dashboard. -The package requires Node.js 20.9 or newer. Bun 1.3 or newer is supported for development and source installs. `failproofai configure` and `failproofai setup` are aliases for `failproofai config`; `failproofai p` is an alias for `failproofai policies`. +The package requires Node.js 20.9 or newer. Bun 1.3 or newer is supported for development and source installs. `failproofai configure` and `failproofai setup` are aliases for `failproofai config`. `failproofai policy`, `failproofai pack` and `failproofai p` are all spellings of `failproofai policies` — packs and single policies were three commands for one idea and are now one. The older spellings still work, with two exceptions: `pack list ` is now `policies show `, and `pack build` is now `publish`. ## Set up a machine ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +export FAILPROOFAI_CLOUD_TOKEN="" +failproofai config # hooks, daemon, and Cloud in one pass +failproofai policies add FailproofAI/policies # choose what enforces failproofai config --status ``` +`failproofai config` is the whole of setup: it installs the `failproofaid` service (root once, via `sudo -n` — never an interactive password prompt), wires hooks into every agent CLI it finds, and connects to Cloud when a key is available. With no terminal — CI, a container, an agent driving it — it applies rather than asking, and exits 1 if anything it was asked to do did not happen. + +It chooses **no** policies. That is the second command's job, and without it a freshly configured machine enforces nothing but the always-on guard. + +Prefer the environment variable over `--token`: a command-line argument is readable from `ps` by every user on the box, and lands in shell history and CI logs. + + + `--connect ` enrols a machine that is **already set up**. It returns as soon as enrolment succeeds — it does not install the daemon and does not wire any hooks. Use plain `failproofai config` (or `failproofai config --token `) on a machine that has not been set up yet, or it will read as connected while collecting and enforcing nothing. + + Run `failproofai` without arguments to open the local policy dashboard. | Command | Outcome | | --- | --- | -| `failproofai config` | Run interactive machine setup | -| `failproofai config --connect --token ` | Connect Cloud ingestion and policy delivery | +| `failproofai config` | Set the machine up: agents, daemon, and Cloud when a key is present | +| `failproofai config --token ` | Set up and connect in one pass, asking nothing | +| `failproofai config --connect ` | Enrol a machine that is **already** set up — no daemon, no hooks | | `failproofai config --status` | Show connection, daemon, delivery, and pause state | | `failproofai policies` | List builtin, custom, convention, pack, and Cloud-managed policies | -| `failproofai policies --install` | Install hooks and enable policies | -| `failproofai policy add ` | Enable one policy — a builtin, or `:` from an installed pack | -| `failproofai policy remove ` | Disable one policy, same naming | +| `failproofai policies --install` | Wire hooks into your agent CLIs. Enables no policy on its own | +| `failproofai policies add ` | Enable one policy — a builtin, or `:` from an installed pack | +| `failproofai policies remove ` | Disable one policy, same naming | | `failproofai policies --uninstall` | Disable policies or remove harness hooks | -| `failproofai pack list` | List installed policy packs and every policy each one carries | -| `failproofai pack add ` | Install a policy pack from a GitHub release; no tag takes the newest and pins it | -| `failproofai pack add --bundled` | Install the builtin policies as a pack, from this package, with no network | -| `failproofai pack build ` | Build the three release assets for a pack of your own | -| `failproofai pack remove ` | Deactivate an installed pack | +| `failproofai policies show /` | What a pack carries, read from its manifest, before you take it | +| `failproofai policies show / --releases` | Every version it has published, and which one is here | +| `failproofai policies add ` | Install a policy pack from a GitHub release; no tag takes the newest and pins it | +| `failproofai publish` | Ship your own policies as a pack; `--init` writes one to start from | +| `failproofai policies remove ` | Uninstall a pack | | `failproofai audit` | Scan local agent history and open the local audit view | | `failproofai audit --schedule [days] --email
` | Schedule recurring local scans and email their findings | | `failproofai audit --status` | Show the report address, interval, and next scheduled scan | @@ -56,9 +65,11 @@ Run `failproofai` without arguments to open the local policy dashboard. | Flag | Use | | --- | --- | -| `--connect --token ` | Connect non-interactively | +| `--token ` | Set up and connect non-interactively; also read from `FAILPROOFAI_CLOUD_TOKEN` | +| `--url ` | Connect somewhere other than `app.befailproof.ai`; also read from `FAILPROOFAI_CLOUD_URL` | +| `--connect ` | Enrol only, on a machine already set up. Skips the daemon and every hook | | `--machine-id ` | Set the stable machine ID | -| `--machine-label ` | Set or change the dashboard label | +| `--machine-label ` | Rename a machine that is **already connected**. On its own it never runs setup, so give it after `failproofai config`, not during | | `--no-transcripts` | Send decisions without transcript content | | `--disconnect` | Stop Cloud policy pulls and event delivery | | `--status` | Show current machine state | @@ -73,7 +84,7 @@ Local pauses suspend builtin, custom, convention, and pack policies for one sess | Flag | Use | | --- | --- | -| `--install`, `-i` | Enable policies and install harness hooks | +| `--install`, `-i` | Install harness hooks. Names after it enable those policies; with none, no policy changes | | `--uninstall`, `-u` | Disable policies or remove hooks | | `--cli ` | Target one or more supported harnesses | | `--scope user\|project\|local\|all` | Choose the configuration scope; `all` is for uninstall | @@ -116,6 +127,8 @@ Use configuration files for persistent machine behavior. Environment variables a | Variable | Use | | --- | --- | +| `FAILPROOFAI_CLOUD_TOKEN` | The Cloud key, instead of `--token`. Prefer this: an argument is readable from `ps` and lands in shell history and CI logs | +| `FAILPROOFAI_CLOUD_URL` | The Cloud URL, instead of `--url`. The same variable the daemon reads | | `FAILPROOFAI_HOME` | Relocate the complete `~/.failproofai` layout | | `FAILPROOFAI_LOG_LEVEL` | Set local logging verbosity | | `FAILPROOFAI_HOOK_LOG_FILE` | Write hook diagnostics to a selected file | diff --git a/docs/reference/harnesses.mdx b/docs/reference/harnesses.mdx index ceafd3c9c..3876abb2e 100644 --- a/docs/reference/harnesses.mdx +++ b/docs/reference/harnesses.mdx @@ -65,15 +65,15 @@ Capabilities are version-sensitive. Re-test after upgrading an agent CLI, especi ![The Policy page used to verify policy decisions from a newly connected harness.](/images/dashboard/policy-observe.png) - Install hooks for every detected harness: + Set the machine up — this wires hooks for every detected harness, installs the daemon, and connects to Cloud: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + FAILPROOFAI_CLOUD_TOKEN= failproofai config + failproofai policies add FailproofAI/policies ``` + Setup enables no policy on its own, which is what the second command is for. + Or target named harnesses and a configuration scope: ```bash diff --git a/docs/reference/overview.mdx b/docs/reference/overview.mdx index a39656a7e..f3437a5d1 100644 --- a/docs/reference/overview.mdx +++ b/docs/reference/overview.mdx @@ -65,9 +65,7 @@ The generated [HTTP API reference](/reference/http-api) covers the public `/v1` --add events:add \ --add policies:pull - failproofai config \ - --connect https://app.befailproof.ai \ - --token + FAILPROOFAI_CLOUD_TOKEN= failproofai config failproofai flush --wait fp sessions --since 1h --env production diff --git a/docs/ru/audits/recipes.mdx b/docs/ru/audits/recipes.mdx index 5bfc2f4e9..cd4f0f0ad 100644 --- a/docs/ru/audits/recipes.mdx +++ b/docs/ru/audits/recipes.mdx @@ -1,5 +1,4 @@ --- ---- title: "Рецепты аудитов" description: "Начальные цели для типичных расследований сбоев агентов." icon: "book-open-check" diff --git a/docs/ru/audits/setup.mdx b/docs/ru/audits/setup.mdx index 499cc9937..623c926a5 100644 --- a/docs/ru/audits/setup.mdx +++ b/docs/ru/audits/setup.mdx @@ -1,5 +1,4 @@ --- ---- title: "Настройка аудита" description: "Определите цель аудита, популяцию сессий и контекст доказательств." icon: "sliders-horizontal" diff --git a/docs/ru/policies/publish-a-pack.mdx b/docs/ru/policies/publish-a-pack.mdx index 92fffcbdd..5298b4508 100644 --- a/docs/ru/policies/publish-a-pack.mdx +++ b/docs/ru/policies/publish-a-pack.mdx @@ -1,5 +1,4 @@ --- ---- title: "Опубликовать пак" description: "Распространяйте собственные политики как релиз на GitHub, который сможет установить любой." icon: "upload" diff --git a/docs/ru/sessions/assistant.mdx b/docs/ru/sessions/assistant.mdx index 54fe9e1bb..8831ed5b1 100644 --- a/docs/ru/sessions/assistant.mdx +++ b/docs/ru/sessions/assistant.mdx @@ -1,5 +1,4 @@ --- ---- title: "Failproof Assistant" description: "Анализируйте и управляйте Failproof AI на естественном языке: от вопросов и запросов до панелей управления и аудитов." icon: "message-square-text" diff --git a/docs/ru/start/integrations/crewai.mdx b/docs/ru/start/integrations/crewai.mdx index 67004ea67..378cdce16 100644 --- a/docs/ru/start/integrations/crewai.mdx +++ b/docs/ru/start/integrations/crewai.mdx @@ -1,5 +1,4 @@ --- ---- title: "CrewAI" sidebarTitle: "CrewAI" description: "Оркестрируйте команды, потоки, агентов по ролям, инструменты, память и обратную связь от пользователей." diff --git a/docs/start/quickstart.mdx b/docs/start/quickstart.mdx index 31f47f690..cde4bda55 100644 --- a/docs/start/quickstart.mdx +++ b/docs/start/quickstart.mdx @@ -42,11 +42,17 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` + That one command is the whole of setup: it installs the local daemon (root once), wires hooks into every agent CLI it finds, and connects this machine to Cloud. Passing the key through the environment rather than `--token` keeps it out of `ps`, shell history and CI logs. + Session transcripts are sent by default. Add `--no-transcripts` to report hook activity and policy decisions without transcript content. + + Do not reach for `failproofai config --connect ` here. That flag enrols a machine that is **already** set up and returns straight after — no daemon, no hooks — so the machine would appear in Cloud while collecting and enforcing nothing. + + If this machine already has agent history, preview and import the last seven days, then wait for delivery to finish. Skip this step on a new machine. ```bash @@ -57,10 +63,8 @@ export FAILPROOFAI_KEY="" Open **Sessions** in Failproof AI and select an imported session. - - This attaches Failproof AI to your harness and installs the 39 built-in policies. Use them to see local policy decisions and try enforcement before Failproof AI audits your sessions and writes policies for your agents. - - Let the installer detect your harness, or name one explicitly. Every one of the 12 is a valid `--cli` value — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + The previous step already wired every agent CLI it detected. Re-run it for one harness explicitly when you need to, or to add a harness installed afterwards. Every one of the 12 is a valid `--cli` value — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # a coding CLI @@ -69,6 +73,17 @@ export FAILPROOFAI_KEY="" Blocking a tool call before it runs is verified on all 12. Turn-end gates are verified on 8 — see [enforcement capability](/reference/harnesses#enforcement-capability) for the per-harness matrix. + + Wiring hooks enables no policy. Setup deliberately picks none — that decision is yours — so take a pack: + + ```bash + failproofai policies add FailproofAI/policies + ``` + + Ours is a pack like anyone else's: fetched from its GitHub release, checksum-verified, and pinned to the exact tag it resolved. It carries 38 policies and switches on the 10 its manifest marks as safe to enable unattended. Read one before taking it with `failproofai policies show /`, and see [policy packs](/policies/packs) for taking only part of one. + + Until this runs, the only thing enforcing is `block-failproofai-commands` — the always-on guard that stops an agent switching Failproof AI off. `failproofai policies` lists what is on. + Follow [Run your first failure check](/start/first-audit). Use a concrete goal such as “find sessions where the agent retried a failing tool without changing its approach.” diff --git a/docs/start/setup.mdx b/docs/start/setup.mdx index b88165d66..b6a124cf8 100644 --- a/docs/start/setup.mdx +++ b/docs/start/setup.mdx @@ -6,7 +6,7 @@ icon: "waypoints" - Install hooks and policies on a machine. Use this when you need immediate guardrails without sending session data to Cloud. + Set a machine up and take a policy pack. Use this when you need immediate guardrails without sending session data to Cloud. Add centralized sessions, audits, online evaluations, dashboards, alerts, and fleet policy deployment. @@ -49,15 +49,23 @@ icon: "waypoints" ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + export FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" + failproofai config - failproofai policies --install --cli claude --scope user + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` + `failproofai config` does the whole setup — daemon, hooks for every agent CLI it finds, and the Cloud connection — then chooses no policies, which is what the second command is for. + + The label comes **after** connecting, not during: `failproofai config --machine-label ` renames a machine that is already connected, and on one that is not it does nothing but say so. + Add `--no-transcripts` when transcript content must remain local. + + + On a machine that is **already** set up, `failproofai config --connect ` enrols it and nothing else. Do not use that form for a first install: it returns before the daemon or any hook is in place, leaving a machine that shows up in Cloud but collects and enforces nothing. + diff --git a/docs/tr/admin/keys-and-permissions.mdx b/docs/tr/admin/keys-and-permissions.mdx index 1250cd0b1..08d6f7da6 100644 --- a/docs/tr/admin/keys-and-permissions.mdx +++ b/docs/tr/admin/keys-and-permissions.mdx @@ -1,5 +1,4 @@ --- ---- title: "Anahtarlar ve izinler" description: "Makineler, otomasyon ve operatörler için kapsamlı API anahtarları oluşturun." icon: "key-round" diff --git a/docs/tr/admin/usage.mdx b/docs/tr/admin/usage.mdx index be7adcaa7..76a728155 100644 --- a/docs/tr/admin/usage.mdx +++ b/docs/tr/admin/usage.mdx @@ -1,5 +1,4 @@ --- ---- title: "Kullanım" description: "Kuruluş tüketimini ve etkin faturalama dönemini inceleyin." icon: "chart-no-axes-combined" diff --git a/docs/tr/admin/users-and-organizations.mdx b/docs/tr/admin/users-and-organizations.mdx index de032c3c2..f082e362f 100644 --- a/docs/tr/admin/users-and-organizations.mdx +++ b/docs/tr/admin/users-and-organizations.mdx @@ -1,5 +1,4 @@ --- ---- title: "Kullanıcılar ve kuruluşlar" description: "Üyelik kontrolü ve her kuruluşun verilerini ve işlemlerini kapsamlı tutun." icon: "users" diff --git a/docs/tr/audits/alerts.mdx b/docs/tr/audits/alerts.mdx index ea9bc133d..bc735942a 100644 --- a/docs/tr/audits/alerts.mdx +++ b/docs/tr/audits/alerts.mdx @@ -1,5 +1,4 @@ --- ---- title: "Uyarılar" description: "Tekrarlayan sorunları algılayın ve olayı uygun müdahalelere yönlendirin." icon: "bell-ring" diff --git a/docs/tr/audits/overview.mdx b/docs/tr/audits/overview.mdx index 34eaa75dd..5b696362e 100644 --- a/docs/tr/audits/overview.mdx +++ b/docs/tr/audits/overview.mdx @@ -1,5 +1,4 @@ --- ---- title: "Denetimler" description: "Tanı izleri tek başına ortaya çıkarmayacak başarısızlıkları bulmak için belirlenmiş bir oturum popülasyonunu gözden geçirin." icon: "scan-search" diff --git a/docs/tr/audits/recipes.mdx b/docs/tr/audits/recipes.mdx index 9252fa273..7e7293bc0 100644 --- a/docs/tr/audits/recipes.mdx +++ b/docs/tr/audits/recipes.mdx @@ -1,5 +1,4 @@ --- ---- title: "Denetim reçeteleri" description: "Yaygın aracı arıza soruşturmaları için başlangıç hedefleri." icon: "book-open-check" diff --git a/docs/tr/policies/builtin-catalog.mdx b/docs/tr/policies/builtin-catalog.mdx index dbf1755e1..ba6159f5e 100644 --- a/docs/tr/policies/builtin-catalog.mdx +++ b/docs/tr/policies/builtin-catalog.mdx @@ -1,5 +1,4 @@ --- ---- title: "Dahili politika kataloğu" description: "Her bir Failproof AI dahili politikasını, tetikleyicisini, önerilen durumunu ve yapılandırılabilir parametrelerini gözden geçirin." icon: "list-checks" diff --git a/docs/tr/reference/cloud-cli.mdx b/docs/tr/reference/cloud-cli.mdx index d68139bce..fa491b25b 100644 --- a/docs/tr/reference/cloud-cli.mdx +++ b/docs/tr/reference/cloud-cli.mdx @@ -1,5 +1,4 @@ --- ---- title: "Failproof Cloud CLI" description: "Failproof AI Cloud'u fp ile sorgulamak ve yönetmek için kapsamlı referans." icon: "cloud-cog" diff --git a/docs/tr/reference/evaluator-sdk.mdx b/docs/tr/reference/evaluator-sdk.mdx index d1567ed6b..ff1efbee2 100644 --- a/docs/tr/reference/evaluator-sdk.mdx +++ b/docs/tr/reference/evaluator-sdk.mdx @@ -1,5 +1,4 @@ --- ---- title: "Evaluator SDK" description: "Failproof AI oturumlarını senkron veya asenkron olarak puanlayan bir hizmet oluşturun." icon: "gauge" diff --git a/docs/tr/reference/harnesses.mdx b/docs/tr/reference/harnesses.mdx index 28694dd3b..440450f50 100644 --- a/docs/tr/reference/harnesses.mdx +++ b/docs/tr/reference/harnesses.mdx @@ -1,5 +1,4 @@ --- ---- title: "Agent araçları" description: "12 desteklenen agent aracında oturumları yakalayın ve politikaları uygulatın." icon: "plug-zap" diff --git a/docs/tr/reference/policy-sdk.mdx b/docs/tr/reference/policy-sdk.mdx index b297dc823..ef8e6fbf5 100644 --- a/docs/tr/reference/policy-sdk.mdx +++ b/docs/tr/reference/policy-sdk.mdx @@ -1,5 +1,4 @@ --- ---- title: "Özel politikalar" description: "Aracılarınıza özgü hatalar için JavaScript veya TypeScript politikaları yazın, test edin ve dağıtın." icon: "shield-plus" diff --git a/docs/tr/reference/troubleshooting.mdx b/docs/tr/reference/troubleshooting.mdx index 45a27e39a..b16640cdd 100644 --- a/docs/tr/reference/troubleshooting.mdx +++ b/docs/tr/reference/troubleshooting.mdx @@ -1,5 +1,4 @@ --- ---- title: "Sorun Giderme" description: "Eksik oturumları, eksik politikaları, başarısız teslimatı ve engellenen aracı işlemlerini tanılayın." icon: "wrench" diff --git a/docs/tr/sessions/overview.mdx b/docs/tr/sessions/overview.mdx index 29db18368..71d77f27b 100644 --- a/docs/tr/sessions/overview.mdx +++ b/docs/tr/sessions/overview.mdx @@ -1,5 +1,4 @@ --- ---- title: "Oturumlar" description: "Bir aracı çalışmasının tam kaydıyla başlayın." icon: "workflow" diff --git a/docs/tr/sessions/policy-decisions.mdx b/docs/tr/sessions/policy-decisions.mdx index e815d420e..d77fd8f4a 100644 --- a/docs/tr/sessions/policy-decisions.mdx +++ b/docs/tr/sessions/policy-decisions.mdx @@ -1,5 +1,4 @@ --- ---- title: "İlke kararları" description: "Hangi ilkelerin değerlendirildiğini, engellediğini, yönlendirdiğini veya izin verdiğini görün." icon: "shield-check" diff --git a/docs/tr/start/concepts.mdx b/docs/tr/start/concepts.mdx index 2a34a09d6..34f238916 100644 --- a/docs/tr/start/concepts.mdx +++ b/docs/tr/start/concepts.mdx @@ -1,5 +1,4 @@ --- ---- title: "Temel kavramlar" description: "Failproof AI genelinde kullanılan kavramların küçük bir seti." icon: "boxes" diff --git a/docs/tr/start/quickstarts/langchain.mdx b/docs/tr/start/quickstarts/langchain.mdx index 43a51a2a2..07e30b83a 100644 --- a/docs/tr/start/quickstarts/langchain.mdx +++ b/docs/tr/start/quickstarts/langchain.mdx @@ -1,5 +1,4 @@ --- ---- title: "LangChain ve LangGraph" description: "Kurun, enstrüman edin ve ilk izinizi görün." icon: "/images/frameworks/langchain.svg" diff --git a/docs/vi/admin/settings-and-security.mdx b/docs/vi/admin/settings-and-security.mdx index 5993dc912..ee694e80a 100644 --- a/docs/vi/admin/settings-and-security.mdx +++ b/docs/vi/admin/settings-and-security.mdx @@ -1,5 +1,4 @@ --- ---- title: "Cài đặt và bảo mật" description: "Định cấu hình các giá trị hoạt động cụ thể và đưa ra những lựa chọn có chủ đích về dữ liệu của agent." icon: "lock-keyhole" diff --git a/docs/vi/audits/agent-contracts.mdx b/docs/vi/audits/agent-contracts.mdx index 299a5ec56..4f7344995 100644 --- a/docs/vi/audits/agent-contracts.mdx +++ b/docs/vi/audits/agent-contracts.mdx @@ -1,5 +1,4 @@ --- ---- title: "Ngữ cảnh agent" description: "Cho các audit biết mỗi agent phải làm gì, tạo ra cái gì, và không được phép làm gì." icon: "bot" diff --git a/docs/vi/audits/local-audit.mdx b/docs/vi/audits/local-audit.mdx index a8db5db00..2021a704a 100644 --- a/docs/vi/audits/local-audit.mdx +++ b/docs/vi/audits/local-audit.mdx @@ -1,5 +1,4 @@ --- ---- title: "Kiểm toán lịch sử agent cục bộ" description: "Quét lịch sử CLI agent được hỗ trợ ngoại tuyến và xem xét hành vi rủi ro hoặc lãng phí cục bộ." icon: "laptop-minimal-check" diff --git a/docs/vi/audits/run.mdx b/docs/vi/audits/run.mdx index fd774facc..d893a96ea 100644 --- a/docs/vi/audits/run.mdx +++ b/docs/vi/audits/run.mdx @@ -1,5 +1,4 @@ --- ---- title: "Chạy và xem xét một audit" description: "Chạy một audit, xác minh phạm vi bao phủ của nó, và kiểm tra các phát hiện kết quả." icon: "play" diff --git a/docs/vi/audits/setup.mdx b/docs/vi/audits/setup.mdx index 11557ee9e..c61be6e3d 100644 --- a/docs/vi/audits/setup.mdx +++ b/docs/vi/audits/setup.mdx @@ -1,5 +1,4 @@ --- ---- title: "Thiết lập một audit" description: "Xác định mục tiêu audit, dân số phiên, và ngữ cảnh bằng chứng." icon: "sliders-horizontal" diff --git a/docs/vi/index.mdx b/docs/vi/index.mdx index 045fcc0b6..46cf81ccc 100644 --- a/docs/vi/index.mdx +++ b/docs/vi/index.mdx @@ -1,5 +1,4 @@ --- ---- title: "Làm cho agent của bạn không thể thất bại" description: "Khả năng quan sát và thực thi cho mọi công cụ mà agent chạy — CLI mã hóa, cổng trò chuyện, trợ lý tự lưu trữ và agent được đo lường của riêng bạn." icon: "shield-check" diff --git a/docs/vi/policies/failure-behavior.mdx b/docs/vi/policies/failure-behavior.mdx index 8c75d7c90..3a64aa423 100644 --- a/docs/vi/policies/failure-behavior.mdx +++ b/docs/vi/policies/failure-behavior.mdx @@ -1,5 +1,4 @@ --- ---- title: "Hành vi khi gặp sự cố" description: "Hiểu điều gì xảy ra khi đánh giá chính sách hoặc daemon cục bộ không khả dụng." icon: "shield-alert" diff --git a/docs/vi/sessions/evaluations.mdx b/docs/vi/sessions/evaluations.mdx index 731123b9b..821a1cd15 100644 --- a/docs/vi/sessions/evaluations.mdx +++ b/docs/vi/sessions/evaluations.mdx @@ -1,5 +1,4 @@ --- ---- title: "Đánh giá trực tuyến" description: "Chấm điểm các phiên làm việc trực tiếp và đã hoàn thành để đánh giá chất lượng, tuân thủ, chi phí và độ trễ." icon: "gauge" diff --git a/docs/vi/start/integrations.mdx b/docs/vi/start/integrations.mdx index 134d131a9..bdc9ce35c 100644 --- a/docs/vi/start/integrations.mdx +++ b/docs/vi/start/integrations.mdx @@ -1,5 +1,4 @@ --- ---- title: "Thiết bị cho agent của bạn" sidebarTitle: "Frameworks" description: "Kết nối bất kỳ framework agent được hỗ trợ nào với Failproof AI chỉ bằng một lệnh gọi." diff --git a/docs/vi/start/setup.mdx b/docs/vi/start/setup.mdx index 4223bb0e6..76290fdf3 100644 --- a/docs/vi/start/setup.mdx +++ b/docs/vi/start/setup.mdx @@ -1,5 +1,4 @@ --- ---- title: "Chọn cách thiết lập của bạn" description: "Chọn thực thi cục bộ, Failproof AI Cloud, hoặc triển khai doanh nghiệp." icon: "waypoints" diff --git a/scripts/translate-docs/validate-translation.ts b/scripts/translate-docs/validate-translation.ts index 632343028..181133715 100644 --- a/scripts/translate-docs/validate-translation.ts +++ b/scripts/translate-docs/validate-translation.ts @@ -11,6 +11,11 @@ * - Frontmatter YAML (class A): the model re-emits an inner `"` unescaped into * a double-quoted `title:`/`description:` value, breaking the YAML. This is * the class that failed run 29575781632; `findFrontmatterError` catches it. + * - Empty block (class A2): the model emits a second opening `---`, so the + * block Mintlify reads closes before any key is inside it and the whole + * frontmatter renders as body text. YAML calls a leading `---` a + * document-start marker and parses it clean, so class A is blind to this; + * `mintlifyFrontmatterBlock` is the second view that is not. * - Key parity (class B): the model drops the frontmatter block entirely, or * renames a key. A dropped block is still *valid YAML* (mintlify tolerates * it, deriving the title from the slug), so only comparing against the @@ -52,6 +57,30 @@ function frontmatterKeys(page: string): string[] | null { } } +/** + * The frontmatter block as MINTLIFY reads it: opened by a leading `---` line, + * closed by the FIRST line after it that is exactly `---`. `null` when the page + * does not open with a delimiter at all. + * + * Deliberately NOT reusing `FRONTMATTER_RE`. That matcher exists to feed + * `YAML.parse`, and YAML reads a bare `---` as a document-START marker rather + * than as a terminator — so a page beginning `---\n---\ntitle: …` parses there + * as a perfectly clean `{title: …}` while Mintlify closes the block on line 2 + * and renders every key as body text. The reader gets a literal `title: "…"` at + * the top of the page and no title on it. + * + * That is not hypothetical: 102 published pages across seven locales shipped + * exactly that way, invisible to every other check in this file, because both + * of them asked YAML. The two views have to be compared, never shared. + */ +function mintlifyFrontmatterBlock(page: string): string | null { + const lines = page.split(/\r?\n/); + if (lines[0]?.trim() !== "---") return null; + const close = lines.findIndex((line, i) => i > 0 && line.trim() === "---"); + if (close < 0) return null; + return lines.slice(1, close).join("\n"); +} + /** * A ±2-line window around `line` (1-based), the failing line prefixed `> ` and * its neighbours ` `. Empty string when `line` is undefined. @@ -93,6 +122,21 @@ export async function findTranslationError( ); } + // Class A2: a block that is EMPTY as Mintlify delimits it. A stray opening + // delimiter (`---\n---\ntitle: …`) is the shape that does this, and it is + // invisible to everything above — see `mintlifyFrontmatterBlock`. Checked for + // every source shape, like the YAML above: the model adding this to a + // frontmatter-less page breaks that page just as thoroughly. + const mintlifyBlock = mintlifyFrontmatterBlock(rendered); + if (mintlifyBlock !== null && mintlifyBlock.trim() === "") { + return ( + "The YAML frontmatter block is empty. The page opens with `---` and the " + + "very next line is `---` again, which closes the block before any key is " + + "in it — every `title:`/`description:`/`icon:` line below then renders as " + + "body text and the page has no title. Emit exactly one opening `---`." + ); + } + const sourceKeys = frontmatterKeys(source); if (sourceKeys) { // The source has frontmatter, so the translation must carry the same keys. From fe8ec199631679e759241c14ba5ebc5d64e788f0 Mon Sep 17 00:00:00 2001 From: chhhee10 Date: Tue, 8 Sep 2026 19:03:40 +0530 Subject: [PATCH 2/5] Match the docs' own voice and restore what the rewrite dropped MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Checked against the live site, which is the post-#773 baseline this branch edits. Three problems, all mine. The publish-a-pack rewrite silently dropped two sections. It was a whole-file replace written after reading only the first 75 of 91 lines, so `What your users are trusting` and `Observe before you enforce` went with it, along with the note that renaming a policy is a breaking change. The observe section matters most: observe-before-enforce is the rollout story the landing page's Session → Audit → Finding → Issue → Policy narrative ends on, and dropping it removed a positioning concept rather than a stale command. Restored, with `"effect": "observe"` now pointing at the `--effect observe` flag that sets it. Three sentences had drifted into the CLI's own register — inward-looking rationale about why WE built it this way ("ours is a pack like anyone else's", "no short name only we can use", twice more), where the surrounding pages state what a thing does for the reader. The baseline uses that self-referential framing twice in 68 pages; this branch had introduced it three times in two. Rewritten to the page's register, and the same for the clipped help-text phrasings that read as pasted output rather than prose ("Not recursive: publishing a fixture is worse than being asked", "A sha does not order"). The quickstart lost a positioning sentence along with the false claim it sat beside — "try enforcement before Failproof AI audits your sessions and writes policies for your agents" is the same observe → audit → policy loop, and only the "installs the 39 built-in policies" half was wrong. Restored. Also trimmed the version-scheme section, which had grown implementation trivia (why twelve sha characters rather than git's seven) that no publisher needs. Design checks against the true HEAD~1 baseline rather than a no-op stash: callouts 39 Warning / 14 Note across 68 English pages, several pages already carrying two or three Warnings, so +3/+2 here is in keeping; headings stay sentence case; no untouched page now contradicts an edited one — every surviving `policies --install ` names policies, which does enable them. validate:mdx 1034 pages clean. --- docs/policies/packs.mdx | 6 +++--- docs/policies/publish-a-pack.mdx | 32 +++++++++++++++++++++++--------- docs/start/quickstart.mdx | 4 +++- 3 files changed, 29 insertions(+), 13 deletions(-) diff --git a/docs/policies/packs.mdx b/docs/policies/packs.mdx index 870439776..c3418df84 100644 --- a/docs/policies/packs.mdx +++ b/docs/policies/packs.mdx @@ -12,7 +12,7 @@ A pack is a set of policies published as a GitHub release. One command installs failproofai policies add FailproofAI/policies ``` -That installs the set we publish, fetched and pinned from its own GitHub release — ours is a pack like anyone else's, typed the same way, with no short name only we can use. It carries 38 policies and switches on the 10 its manifest marks as safe to enable unattended; the rest are listed for you to choose. Take part of it instead: +That fetches the Failproof AI set from its GitHub release and pins it, the same way any other pack is installed. It carries 38 policies and switches on the 10 its manifest marks as safe to enable unattended; the rest are listed for you to choose. Take part of it instead: ```bash failproofai policies add FailproofAI/policies --policy block-rm-rf # one, or a comma-separated few @@ -87,7 +87,7 @@ If a pack ships a policy whose name is also an **enabled builtin**, the builtin ## Where the Failproof AI policies come from -The same place anyone else's do — a GitHub release, fetched and pinned like any other pack. The npm package carries no copy of them and there is no short name reserved for ours, so the set we publish is installed and versioned exactly the way yours would be: +A GitHub release, fetched and pinned like any other pack. The npm package carries no copy of them, so naming a specific version works exactly as it does for anybody's pack: ```bash failproofai policies add FailproofAI/policies # newest release, pinned @@ -95,7 +95,7 @@ failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # a specific one failproofai policies show FailproofAI/policies --releases # everything it has published ``` -The one policy that does ship compiled into the package is `block-failproofai-commands`, the always-on guard: a pack may not declare `alwaysOn`, because a downloaded file no local command can switch off is the thing that guard exists to prevent. +One policy does ship compiled into the package: `block-failproofai-commands`, the always-on guard. A pack may not declare `alwaysOn`, precisely because a downloaded file that no local command can switch off is what that guard exists to prevent. ## What integrity does and does not buy diff --git a/docs/policies/publish-a-pack.mdx b/docs/policies/publish-a-pack.mdx index 4f5e8b026..b8fe61264 100644 --- a/docs/policies/publish-a-pack.mdx +++ b/docs/policies/publish-a-pack.mdx @@ -58,13 +58,13 @@ Any path, any filename. Ask your agent to do the thing you blocked and watch it failproofai publish ``` -It asks **where** only when nothing tells it — no git remote to read — and works the rest out. In order, stopping before it touches GitHub if anything is wrong: +It works out where to publish, what to bundle and what version to call it, and only asks when nothing in the repository tells it. In order, stopping before it touches GitHub if anything is wrong: -1. Finds the policy files here by **content** (files that import `failproofai` and call `customPolicies.add`), not by filename. Not recursive: publishing a fixture is worse than being asked. +1. Finds the policy files here by **content** — those that import `failproofai` and call `customPolicies.add` — rather than by filename, so it finds `guards.mjs` and ignores an unrelated `policies.mjs`. It does not descend into subdirectories, so a test fixture is never swept up by accident. 2. Reads the repo from `git remote get-url origin`, in the **file's** directory rather than yours, and decides the version. 3. Finds your credential: `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth login`. It needs release-write and nothing else, and is never printed. 4. Creates the repository if it does not exist. -5. Builds the three assets, validating with the **loader's own rules** — the code that decides what may install on a stranger's machine. A pack that could never install fails here, where you can fix it. +5. Builds the three assets, validating them with the **loader's own rules** — the same code that decides what may install on a stranger's machine — so a pack that could never install fails here, where you can still fix it. 6. Creates or reuses the release and uploads, replacing assets of the same name. | File | What it is | @@ -81,13 +81,11 @@ Use `--dry-run` to build the assets and publish nothing; it needs no credential. ## How the version is decided -The **commit you are publishing from** — its short sha, twelve characters: `a1b2c3d4e5f6`. Nothing to pick and nothing to count, and it names exactly where the bytes came from. Publish the same source twice and you get the same version, because there is nothing to increment. +The version is the **commit you are publishing from** — its short sha, twelve characters: `a1b2c3d4e5f6`. There is nothing to pick and nothing to increment, and the version names exactly where the bytes came from, so publishing the same source twice gives the same version. -Twelve characters rather than git's seven: seven collides in a repository with enough objects, and a version that stops being unique means two artifacts claiming one name. The full sha is recorded beside it. +It is read from the tree in front of you, never from the repository's releases, so a fresh clone and an air-gapped machine compute the same answer without asking GitHub what happened before. -It is read from the tree in front of you, never from the repository's releases, so a fresh clone and an air-gapped machine compute the same answer and neither has to ask GitHub what happened before. - -It **refuses rather than guessing** in two cases, because the version claims to name a commit and must not be minted where that is false: +Because the version claims to name a commit, it **refuses rather than guessing** where that would be false: | Case | Why | | --- | --- | @@ -96,7 +94,7 @@ It **refuses rather than guessing** in two cases, because the version claims to `--version` overrides both, and a tag on `HEAD` wins over the sha — someone who tagged `v1.2.0` has said what this release is. -A sha does not order. `failproofai policies show / --releases` is where you see which came first, newest at the top. +A sha carries no ordering of its own, so use `failproofai policies show / --releases` to see which release came first — newest at the top. The release also records the commit you published from, in the manifest and in the release notes. That is **provenance, not verification** — the artifact digest is still the only thing that decides whether the bytes are the ones that were published. It answers the question a digest cannot: which source produced them. @@ -136,3 +134,19 @@ failproofai policies show acme/support-agent --releases # everything published ## Shipping a new version Commit the change and run `failproofai publish` again — the new commit is the new version. Consumers run the same `failproofai policies add` and keep whatever subset they had chosen; a policy they turned off stays off across the upgrade. + +Changing a policy's **name** is a breaking change: a machine that had turned it off is turning off a name that no longer exists, and the new name arrives at whatever `defaultEnabled` says. + +## What your users are trusting + +`SHA256SUMS` lives in the same release as the artifact, so it proves the bytes are the ones you published — not who you are. Whoever can write to the repository can write both files. Your users' protection is that the digest is pinned when they install, so what you shipped cannot change under them afterwards. + +Publish from a repository whose write access you control, and treat a pack release like publishing a package. + +## Observe before you enforce + +A manifest may declare `"effect": "observe"` — `failproofai publish --effect observe` is what sets it. Those policies run and their verdicts are **recorded and discarded** — nothing is blocked. It is the way to measure a new rule against real traffic before it can interrupt anyone's work. + +```json +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } +``` diff --git a/docs/start/quickstart.mdx b/docs/start/quickstart.mdx index cde4bda55..6620f6be5 100644 --- a/docs/start/quickstart.mdx +++ b/docs/start/quickstart.mdx @@ -80,7 +80,9 @@ export FAILPROOFAI_KEY="" failproofai policies add FailproofAI/policies ``` - Ours is a pack like anyone else's: fetched from its GitHub release, checksum-verified, and pinned to the exact tag it resolved. It carries 38 policies and switches on the 10 its manifest marks as safe to enable unattended. Read one before taking it with `failproofai policies show /`, and see [policy packs](/policies/packs) for taking only part of one. + The pack is fetched from its GitHub release, checksum-verified, and pinned to the exact tag it resolved. It carries 38 policies and switches on the 10 its manifest marks as safe to enable unattended. Use them to see local policy decisions and try enforcement before Failproof AI audits your sessions and writes policies for your agents. + + Read any pack before taking it with `failproofai policies show /`, and see [policy packs](/policies/packs) for taking only part of one. Until this runs, the only thing enforcing is `block-failproofai-commands` — the always-on guard that stops an agent switching Failproof AI off. `failproofai policies` lists what is on. From f9beef30245eaa716c832202b6953ee3e0c50a09 Mon Sep 17 00:00:00 2001 From: chhhee10 Date: Tue, 8 Sep 2026 19:22:03 +0530 Subject: [PATCH 3/5] Reconcile the builtin pages with the catalog they describe MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `builtin.mdx` taught `policy add` with no mention that policies arrive in a pack at all, which read oddly beside every other page now saying setup selects nothing. Fixing that surfaced three harder errors on it and the catalog page it links to. THE COUNT. It claimed 40. `POLICY_CATALOG` and `BUILTIN_POLICIES` both hold 39, and the catalog page documents 39 names that diff clean against source — so 40 came from nowhere. 38 is also right, for a different question: a pack may not declare `alwaysOn`, so `block-failproofai-commands` cannot travel that lane and the pack carries 38. Both numbers were already in the docs, unexplained and a page apart. They are now stated together, once, on the page about builtins: 39 exist, 38 are selectable, the 39th is the always-on guard. Also recorded that `--beta` currently adds nothing, since no policy carries the flag. THE BASELINE, which is the one that mattered. The catalog listed fourteen policies as "the guided setup's recommended selection". Setup has no selection — it enables none — and of those fourteen, `block-rm-rf`, `block-force-push` and `block-secrets-write` are NOT `defaultEnabled`. Anyone reading that page believed their two most-wanted guards were on when a bare pack install leaves them off. The list is now the manifest's real 10, attributed to the pack rather than to setup, and the three absentees are called out by name with the command to enable each. THE SANITIZERS, again. Five rows promised redaction "before the model sees them" while the same row named `PostToolUse` as the trigger — the contradiction sitting in one line. Same finding as #669 and the same fix already applied to the README: they report a secret that has already reached the model. Reworded, with a note pointing at the `PreToolUse` guards that stop the read instead. Counts verified by importing the real modules, not by grepping: 39 catalog, 39 runtime, 1 alwaysOn, 0 beta, 11 defaultEnabled of which 10 are not the guard — which is where pack-store's "10 of 38" comes from. validate:mdx 1034 pages clean; both pages render. --- CHANGELOG.md | 3 +++ docs/policies/builtin-catalog.mdx | 41 +++++++++++++++++++------------ docs/policies/builtin.mdx | 24 +++++++++++++----- 3 files changed, 46 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cd2dc7cb4..e6d638ec5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,9 @@ - `--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 --machine-label ` never reaches the wizard and answers "this machine is not connected … so it has no name to change". Setup comes first, the label after (#PR) - `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 (#PR) - 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 (#PR) +- 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 (#PR) +- 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 (#PR) +- 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 (#PR) - `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 (#PR) ### Dependencies diff --git a/docs/policies/builtin-catalog.mdx b/docs/policies/builtin-catalog.mdx index 75029a507..78f3cd6ba 100644 --- a/docs/policies/builtin-catalog.mdx +++ b/docs/policies/builtin-catalog.mdx @@ -8,39 +8,48 @@ The installed package is the source of truth for policy availability. Run `failp ## Recommended baseline -The guided setup's recommended selection currently enables secret sanitizers, environment protections, self-protection, catastrophic-command guards, and protected-branch safety: +Setting up a machine enables **no** policy. The baseline below is the Failproof AI pack's own default selection — the 10 its manifest marks as safe to switch on unattended, applied when you run `failproofai policies add FailproofAI/policies` with no flags: ```text sanitize-jwt sanitize-api-keys -sanitize-connection-strings sanitize-private-key-content +sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars -block-env-files block-secrets-write -block-failproofai-commands block-sudo -block-curl-pipe-sh block-rm-rf -block-push-master block-force-push +block-env-files block-sudo +block-curl-pipe-sh block-push-master ``` -`block-failproofai-commands` is **always on**. It is listed above for -completeness, but it registers on every evaluation whether or not it appears in -your enabled set, and it cannot be disabled or paused — a guard against the -agent switching off enforcement that the agent can switch off is not a guard. +`block-failproofai-commands` enforces alongside them without being one of them. It is **always on**: it registers on every evaluation whether or not it appears in your enabled set, and it cannot be disabled or paused — a guard against the agent switching off enforcement that the agent can switch off is not a guard. -Recommended is deliberately narrower than **Everything**. Infrastructure and workflow policies can interrupt valid work and should be enabled for the repositories and machines that need them. + + `block-rm-rf`, `block-force-push` and `block-secrets-write` are **not** in the baseline. They are among the most-wanted guards and it is reasonable to assume otherwise, so enable them deliberately: + + ```bash + failproofai policies add block-rm-rf + failproofai policies add block-force-push + failproofai policies add block-secrets-write + ``` + + +The baseline is deliberately narrower than **Everything**. Destructive-command, infrastructure and workflow policies can interrupt valid work, so they are opt-in per repository and machine — `--all` takes the lot. ## Secrets and environment | Policy | Trigger | Outcome | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | Redact JWTs from tool output before the model sees them. | -| `sanitize-api-keys` | `PostToolUse` | Redact common OpenAI, Anthropic, GitHub, AWS, Stripe, and Google keys. | -| `sanitize-connection-strings` | `PostToolUse` | Redact database connection strings containing credentials. | -| `sanitize-private-key-content` | `PostToolUse` | Redact PEM private-key bodies. | -| `sanitize-bearer-tokens` | `PostToolUse` | Redact authorization bearer tokens. | +| `sanitize-jwt` | `PostToolUse` | Report JWTs found in tool output. | +| `sanitize-api-keys` | `PostToolUse` | Report common OpenAI, Anthropic, GitHub, AWS, Stripe, and Google keys. | +| `sanitize-connection-strings` | `PostToolUse` | Report database connection strings containing credentials. | +| `sanitize-private-key-content` | `PostToolUse` | Report PEM private-key bodies. | +| `sanitize-bearer-tokens` | `PostToolUse` | Report authorization bearer tokens. | | `protect-env-vars` | `PreToolUse` on shell tools | Block commands that dump environment variables. | | `block-env-files` | `PreToolUse` | Block reads and writes of `.env` files. | | `block-read-outside-cwd` | `PreToolUse` on read, glob, grep, or shell tools | Keep reads inside the session working directory. | | `block-secrets-write` | `PreToolUse` on write tools | Block writes to common secret-key and credential filenames. | + + The five `sanitize-*` policies run on `PostToolUse`, which is **observation only**: the tool has already run and its output has already reached the model. They tell you a secret appeared in tool output — they do not keep it out of the context, and they are not a data-loss control. Use `block-env-files`, `protect-env-vars` and `block-secrets-write`, which gate on `PreToolUse`, to stop the read happening at all. + + ## Dangerous commands and infrastructure | Policy | Trigger | Outcome | diff --git a/docs/policies/builtin.mdx b/docs/policies/builtin.mdx index 1dd24e61b..7b92d0c12 100644 --- a/docs/policies/builtin.mdx +++ b/docs/policies/builtin.mdx @@ -6,6 +6,16 @@ icon: "library" Builtin policies cover secret handling, environment files, destructive shell commands, protected branches, cloud and infrastructure tools, package publishing, repeated calls, and end-of-task workflow checks. +There are **39** of them, and **38** are yours to choose from. The odd one out 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, so that guard ships compiled into the package rather than arriving in a pack. + +They reach a machine as a **pack**. Setting up wires the hooks and selects nothing, so take one before any of the 38 enforce: + +```bash +failproofai policies add FailproofAI/policies +``` + +That switches on the 10 the pack's manifest marks as safe to enable unattended and lists the rest for you to pick from. See [policy packs](/policies/packs) for taking only part of one. + ## Enable and verify a builtin policy @@ -19,15 +29,15 @@ Builtin policies cover secret handling, environment files, destructive shell com ```bash failproofai policies - failproofai policy add block-rm-rf --cli claude --scope project + failproofai policies add block-rm-rf --cli claude --scope project failproofai config --status ``` - Remove it with `failproofai policy remove block-rm-rf --cli claude --scope project`. + Remove it with `failproofai policies remove block-rm-rf --cli claude --scope project`. -List the policies available in your installed version: +List every policy on this machine and whether it is on: ```bash failproofai policies @@ -36,9 +46,11 @@ failproofai policies Enable one policy for a project: ```bash -failproofai policy add block-rm-rf --scope project +failproofai policies add block-rm-rf --scope project ``` +A name with no slash is a policy; anything with one is a pack source, so there is nothing to disambiguate. + Enable several policies for selected harnesses: ```bash @@ -46,10 +58,10 @@ failproofai policies --install block-sudo block-force-push \ --cli claude codex --scope project ``` -Some policies accept parameters or are marked beta. Review the description, match scope, and default behavior before rollout. A policy that protects one workflow may block valid operations in another. +Some policies accept parameters. Review the description, match scope, and default behavior before rollout — a policy that protects one workflow may block valid operations in another. `--beta` includes policies marked beta; none currently are. - Review all 40 current policies, their triggers, recommended baseline, and parameters. + Review all 39 policies, their triggers, recommended baseline, and parameters. From b31ceb3817c52e071d34ff3a10f3db0a4b91688b Mon Sep 17 00:00:00 2001 From: chhhee10 Date: Tue, 8 Sep 2026 20:05:35 +0530 Subject: [PATCH 4/5] Point the changelog entries at #788 --- CHANGELOG.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e6d638ec5..b2305673f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,17 +12,17 @@ - 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 (#PR) -- `failproofai config --connect --token ` 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` (#PR) -- 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 (#PR) -- 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 (#PR) -- `--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 --machine-label ` never reaches the wizard and answers "this machine is not connected … so it has no name to change". Setup comes first, the label after (#PR) -- `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 (#PR) -- 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 (#PR) -- 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 (#PR) -- 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 (#PR) -- 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 (#PR) -- `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 (#PR) +- 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 --token ` 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 --machine-label ` 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 @@ -613,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 From d3e1b9bd6a00237c5bd8929be931ab2fef56234e Mon Sep 17 00:00:00 2001 From: chhhee10 Date: Tue, 8 Sep 2026 20:29:42 +0530 Subject: [PATCH 5/5] Bring the edited pages back to the site's formatting conventions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Measured against df1d0565 rather than eyeballed, and one page was well outside what the rest of the site does. publish-a-pack had grown from 91 lines and 6 H2s to 152 and 10 — the only page on the branch more than a few lines from its baseline. The command it documents did change completely (`pack build` plus a hand-written `gh release create` became one `publish`), but that did not justify four new top-level sections. Two were reference material the site keeps elsewhere: `## Install it` restated packs.mdx and is now one sentence linking there, and `## Options` was a ten-row flag table where this page's own convention is flags shown inline in the example being explained. `## The repository must be public` folded into `What your users are trusting`, which is the same subject. Now 7 H2s and 125 lines. Two smaller drifts, both from copying one page's habits onto others: - Aligned trailing `#` comments in bash blocks are a packs.mdx idiom — 8 of the 96 bash lines in the English docs, all on that one page. They had spread to the setup block in failproof-cli.mdx, where the baseline has none. Removed; the explanation was already in the prose underneath. - Two callout bodies sat at 0 indentation where 67 of 69 top-level callouts in the baseline use 2. Both were pre-existing rather than introduced here, but they are in files this branch already touches, so they are normalised now. Also fixed an example that taught the wrong thing: `--id acme/support-agent` passed alongside `--repo acme/support-agent`, which is exactly its default, so the flag looked required. Dropped from the example and described in the prose. validate:mdx 1034 pages clean; pages render. --- docs/policies/packs.mdx | 2 +- docs/policies/publish-a-pack.mdx | 62 +++++++++----------------------- docs/reference/failproof-cli.mdx | 4 +-- 3 files changed, 20 insertions(+), 48 deletions(-) diff --git a/docs/policies/packs.mdx b/docs/policies/packs.mdx index c3418df84..68581b039 100644 --- a/docs/policies/packs.mdx +++ b/docs/policies/packs.mdx @@ -82,7 +82,7 @@ failproofai policies --uninstall acme/support-agent:block-refunds ``` -If a pack ships a policy whose name is also an **enabled builtin**, the builtin runs and the pack's copy is skipped — the same guard would otherwise be evaluated twice. Turn the builtin off to use the pack's copy instead. + If a pack ships a policy whose name is also an **enabled builtin**, the builtin runs and the pack's copy is skipped — the same guard would otherwise be evaluated twice. Turn the builtin off to use the pack's copy instead. ## Where the Failproof AI policies come from diff --git a/docs/policies/publish-a-pack.mdx b/docs/policies/publish-a-pack.mdx index b8fe61264..b636d95f8 100644 --- a/docs/policies/publish-a-pack.mdx +++ b/docs/policies/publish-a-pack.mdx @@ -39,7 +39,7 @@ customPolicies.add({ Write as many files as you like; one per category reads well. Every file in the directory that registers policies is bundled into the single artifact a pack has to be. -Bundling needs **bun**. Without it, keep to one self-contained file. Either way the published entry must not import local files at install time: only the entry is digest-pinned, so a pack that reached for siblings could not honestly claim the digest covers what runs — and `publish` refuses one rather than shipping a promise it cannot keep. + Bundling needs **bun**. Without it, keep to one self-contained file. Either way the published entry must not import local files at install time: only the entry is digest-pinned, so a pack that reached for siblings could not honestly claim the digest covers what runs — and `publish` refuses one rather than shipping a promise it cannot keep. ## 2. Try it here first @@ -77,7 +77,19 @@ The asset names are fixed — they are what a consumer's CLI constructs its URLs Refused at build time: an id that is not `publisher/name`, a policy name containing `/`, a policy declaring `alwaysOn`, a missing `description`, `category` or `match`, an entry that registers nothing, and an entry that imports local files. -Use `--dry-run` to build the assets and publish nothing; it needs no credential. +Override anything it decided: + +```bash +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run +``` + +`--id` sets the pack id when it should differ from the repo, `--tag` and `--notes` name the release, `--out` chooses where the assets are written (default `dist-pack`), and `--dry-run` builds them without publishing and needs no credential. + +Anyone can now install it with `failproofai policies add acme/support-agent`. See [policy packs](/policies/packs) for pinning a version and taking only part of one. ## How the version is decided @@ -85,52 +97,10 @@ The version is the **commit you are publishing from** — its short sha, twelve It is read from the tree in front of you, never from the repository's releases, so a fresh clone and an air-gapped machine compute the same answer without asking GitHub what happened before. -Because the version claims to name a commit, it **refuses rather than guessing** where that would be false: - -| Case | Why | -| --- | --- | -| No git checkout | There is no commit to name | -| Uncommitted changes | Those bytes are not in that commit | - -`--version` overrides both, and a tag on `HEAD` wins over the sha — someone who tagged `v1.2.0` has said what this release is. +Because the version claims to name a commit, it **refuses rather than guessing** where that would be false: outside a git checkout there is no commit to name, and with uncommitted changes those bytes are not in the commit it would name. `--version` overrides both, and a tag on `HEAD` wins over the sha — someone who tagged `v1.2.0` has said what this release is. A sha carries no ordering of its own, so use `failproofai policies show / --releases` to see which release came first — newest at the top. - - The release also records the commit you published from, in the manifest and in the release notes. That is **provenance, not verification** — the artifact digest is still the only thing that decides whether the bytes are the ones that were published. It answers the question a digest cannot: which source produced them. - - -## The repository must be public - -Installs are anonymous HTTPS with no credential to offer, so a private repository publishes to nobody. A repo `publish` creates is public for that reason; an existing private one is **refused**, before anything is built, created or uploaded. - -`--allow-private` publishes to one anyway, for somebody who will hand the three assets over another way — it still says plainly that no `policies add` can reach them. - -Only the release matters. Installs read `releases/download//` and never touch your git tree; pushing the source is for humans. - -## Install it - -```bash -failproofai policies add acme/support-agent # newest release, pinned -failproofai policies add acme/support-agent@a1b2c3d4e5f6 # that exact one -failproofai policies show acme/support-agent --releases # everything published -``` - -## Options - -| Flag | Use | -| --- | --- | -| `--init [file]` | Write a starter policy and stop | -| `--repo /` | Where to release it, created if missing | -| `--version ` | Name the version, instead of the commit it was built from | -| `--id ` | The pack's id. Defaults to `--repo` | -| `--tag ` | Release tag. Defaults to the version; a `v` prefix is fine | -| `--notes ` | Release notes | -| `--out ` | Where to write the assets. Default `dist-pack` | -| `--effect ` | `enforce` or `observe`. `observe` records and blocks nothing. Default `enforce` | -| `--dry-run` | Build the assets, publish nothing. No credential needed | -| `--allow-private` | Publish to an already-private repo anyway. Nobody can install it | - ## Shipping a new version Commit the change and run `failproofai publish` again — the new commit is the new version. Consumers run the same `failproofai policies add` and keep whatever subset they had chosen; a policy they turned off stays off across the upgrade. @@ -143,6 +113,8 @@ Changing a policy's **name** is a breaking change: a machine that had turned it Publish from a repository whose write access you control, and treat a pack release like publishing a package. +The repository must also be **public**. Installs are anonymous HTTPS with no credential to offer, so an existing private repo is refused before anything is built or uploaded, and one `publish` creates is public for the same reason. `--allow-private` overrides that for somebody handing the three assets over another way, and says plainly that no `policies add` can reach them. Only the release matters: installs read `releases/download//` and never touch your git tree. + ## Observe before you enforce A manifest may declare `"effect": "observe"` — `failproofai publish --effect observe` is what sets it. Those policies run and their verdicts are **recorded and discarded** — nothing is blocked. It is the way to measure a new rule against real traffic before it can interrupt anyone's work. diff --git a/docs/reference/failproof-cli.mdx b/docs/reference/failproof-cli.mdx index db3328f68..bcead78d0 100644 --- a/docs/reference/failproof-cli.mdx +++ b/docs/reference/failproof-cli.mdx @@ -13,8 +13,8 @@ The package requires Node.js 20.9 or newer. Bun 1.3 or newer is supported for de ```bash npm install -g failproofai export FAILPROOFAI_CLOUD_TOKEN="" -failproofai config # hooks, daemon, and Cloud in one pass -failproofai policies add FailproofAI/policies # choose what enforces +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ```