[docs] Rebuild the documentation as one product — guardrails and FailproofAI Cloud in one journey - #687
Open
NiveditJain wants to merge 2 commits into
Open
[docs] Rebuild the documentation as one product — guardrails and FailproofAI Cloud in one journey#687NiveditJain wants to merge 2 commits into
NiveditJain wants to merge 2 commits into
Conversation
The site had two top-level tabs, "Enforcement" and "Observability", which asked every reader to work out which half of a single product they were in before reading anything. There is now one navigation, ordered as a journey: install and guard a machine, see what happened on it, then govern the fleet from the cloud. The observability half is repositioned as FailproofAI Cloud and moves from the agenteye section to the cloud section, with a redirect for every old URL. Documents the integration surface that had no docs at all. `failproofai config --connect` existed only in --help: new pages cover connecting a machine (both capabilities, what leaves the machine, fleet provisioning, troubleshooting), managed policies (deployments, digest verification, observe-mode rollout), the fleet view, and session capture across all 12 CLIs -- replacing three per-CLI capture pages written for a separate collector that the daemon has since absorbed. Adds the pages a reader kept needing and could not find: How it works (tool call to decision to dashboard, with the failure-mode table), the failproofaid service (fail-closed, supervision, how the binary arrives, upgrades), Supported agents (per-CLI matrix of what a deny actually blocks, derived from the same source the product asserts against), Policies as a hub, one merged Concepts glossary, a files-and-paths reference, and CLI pages for config, harness, backfill, flush and uninstall. Cloud pages are value- and contract-first: internal architecture claims are out, what a user needs to operate the product stays. Per-CLI hook-schema internals move off the Configuration page and into the support matrix. Two tests hardcoded the old docs directory as a fixture path and are updated to the new location. The 14 language trees are moved and relinked; pages with no counterpart are seeded from English so every nav entry resolves, and the scheduled translation job replaces them on its next run (its cache is keyed on English source hashes, all of which changed). Adds one screenshot of the local session viewer, captured through headless Chrome against synthetic fixture data rather than a real machine's sessions. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014ZHcJRck9qdLpGEZeL51js
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014ZHcJRck9qdLpGEZeL51js
|
Important Review skippedToo many files! This PR contains 1025 files, which is 875 over the limit of 150. To get a review, reduce the PR to 150 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. Usage-priced reviews support at most 300 files. ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (24)
📒 Files selected for processing (1025)
You can disable this status message by setting the Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Hermes
No summary yet. What this changesNo component map for this revision. RoundsNo review has finished on this pull request yet. FindingsNothing raised yet.
|
Contributor
Hermes
Review complete. The navigation and redirect migration resolves correctly; I found two low-severity documentation accuracy issues affecting localized navigation and uninstall expectations. What this changesflowchart LR
n0Documentationnavigation["~ Documentation navigation"]
n1Clouddocumentation["+ Cloud documentation"]
n2Guardrailsdocumentation["~ Guardrails documentation"]
n3Localizeddocumentation["~ Localized documentation"]
n4LegacyAgentEyeroutes["− Legacy AgentEye routes"]
n5Documentationvalidationtests["~ Documentation validation tests"]
n0Documentationnavigation -- "routes readers to Cloud pages" --> n1Clouddocumentation
n0Documentationnavigation -- "routes readers to local docs" --> n2Guardrailsdocumentation
n0Documentationnavigation -- "redirects old URLs" --> n4LegacyAgentEyeroutes
n0Documentationnavigation -- "selects language-specific pages" --> n3Localizeddocumentation
n3Localizeddocumentation -- "mirrors Cloud content" --> n1Clouddocumentation
n5Documentationvalidationtests -- "validates moved doc fixtures" --> n0Documentationnavigation
Rounds
FindingsOpen
|
hermes-exosphere
approved these changes
Aug 12, 2026
hermes-exosphere
left a comment
hermes-exosphere
left a comment
Contributor
There was a problem hiding this comment.
Hermes found no blocking issues in this revision.
2 advisory findings
- Low/High Restore localized labels for the new navigation — Every non-English entry now renders the tab as "Documentation" and groups such as "Guardrails", "See what happened", and "Analyze and act" in English (for example docs/docs.json:144-218 for zh). The generator falls back to the English text for any unmapped name; its map only adds "Start here" and "CLI reference" (scripts/translate-docs/mintlify-nav.ts:86-108). Thus regenerating localized navigation will preserve this regression. (
scripts/translate-docs/mintlify-nav.ts:86) - Low/High Document that plain uninstall can retain the daemon — The new reference says
failproofai uninstallremoves the service and lists service removal as an unconditional step (docs/cli/uninstall.mdx:13-14,49-50). In the implementation, an interactive non-purge uninstall asks separately and keeps the service when declined (src/hooks/uninstall-cli.ts:305-313); the CLI help states this explicitly (bin/failproofai.mjs:994-998). (docs/cli/uninstall.mdx:13)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rebuilds the documentation as one product instead of two.
The site had two top-level tabs — "Enforcement" and "Observability" — which asked every reader to work out which half of a single product they were in before reading anything. There is now one navigation, ordered as a journey: install and guard a machine → see what happened on it → govern the fleet from the cloud.
The observability half is repositioned as FailproofAI Cloud and moves from the
agenteyesection to thecloudsection, with a redirect for every old URL (57 total).Why
The AgentEye solution is integrated and
failproofaidis live, but the docs still described two separate products — and the seam between them (failproofai config --connect) was documented only in--help. A reader could not find out how a machine joins a fleet, what a deployment is, or what leaves their machine when they connect.New pages
cloud/connectcloud/managed-policiescloud/fleetcloud/capturecloud/agent-skillshow-it-worksdaemonagent-supportpoliciesconceptsreference/filescli/{config,harness,backfill,flush,uninstall}Notable decisions
require-*-before-stopbuiltins never fire on Hermes or Goose. That is now a warning on both the policy catalogue and the support matrix rather than something you discover from a rule that quietly did nothing.docs/images/local-session-viewer.png), captured through headless Chrome in Docker against synthetic fixture data — no real project names or transcripts. A second capture was dropped because it leaked a local filesystem path.Translations
The 14 language trees are moved and relinked. Pages with no counterpart are seeded from English so every nav entry resolves and CI stays green; the scheduled translation job replaces them on its next run, since its cache is keyed on English source hashes and all of them changed.
Test changes
Two tests hardcoded the old docs directory as a fixture path (
__tests__/scripts/validate-mdx.test.ts,__tests__/scripts/translate-docs/mdx-translator.test.ts) and are updated to the new location — the fixture path is exactly the value this PR changes.Validation
bun run validate:mdx— 825 pages parse, no broken images__tests__/scripts/— 237 passed🤖 Generated with Claude Code
https://claude.ai/code/session_014ZHcJRck9qdLpGEZeL51js
Hermes review
541b256501c085f36c270d02e2a201f2fd342f2a1d8f31d926828f3bae215c58f5b35baa44acbff0gpt-5.6-terraSummary
Review complete. The navigation and redirect migration resolves correctly; I found two low-severity documentation accuracy issues affecting localized navigation and uninstall expectations.
Changes
Validation
Passedjq navigation/redirect target existence check— All 810 navigation entries and 57 redirect targets resolve to current documentation files; no duplicate or self-referential redirect sources were found. (0s)Skippeddocker run ... bun run validate:mdx— The source snapshot has no installed dependencies. A disposable-container clean install did not complete dependency resolution, so the MDX compiler check could not run; no explicit validation command was configured. (44s)Findings
No blocking findings.
2 advisory findings
scripts/translate-docs/mintlify-nav.ts:86)failproofai uninstallremoves the service and lists service removal as an unconditional step (docs/cli/uninstall.mdx:13-14,49-50). In the implementation, an interactive non-purge uninstall asks separately and keeps the service when declined (src/hooks/uninstall-cli.ts:305-313); the CLI help states this explicitly (bin/failproofai.mjs:994-998). (docs/cli/uninstall.mdx:13)Open questions
None.
Policy overrides
None.