Back to Details

failproofai

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

FailproofAI

FailproofAI

Observability and enforcement for every harness your agents run in — coding CLIs, chat gateways, self-hosted assistants, and your own instrumented agents.
Session  →  Audit  →  Finding  →  Issue  →  Policy
what happened   is it a pattern   what broke   who owns it   stop it recurring
This is the single umbrella for the whole product. It orients, explains every vertical, sets a machine up, moves data, operates the fleet, and carries enough reference material to work alone. When focused sibling skills are installed, route to them for a smaller context.
Source pointers are grep anchors inside the 
failproofai
package — 
node_modules/failproofai/
in an installed project, the repo root in a checkout. They survive refactors; line numbers do not.
为 Agent 运行于其上的每个 harness 提供可观测性与强制执行能力——编程 CLI、聊天网关、自托管助手，以及你自己完成插桩的 Agent。
Session  →  Audit  →  Finding  →  Issue  →  Policy
发生了什么   是否构成模式   出了什么问题   谁负责   阻止再次发生
这是面向整个产品的唯一总入口。它负责提供整体视角、解释每个垂直领域、配置机器、迁移数据、运维 fleet，并包含足够的参考资料，可独立完成工作。安装了聚焦特定场景的 sibling skill 时，应将任务路由过去，以缩小上下文。
源码定位点是 
failproofai
包内可通过 grep 查找的锚点——在已安装项目中位于 
node_modules/failproofai/
，在代码检出（checkout）中位于仓库根目录。它们能够承受重构；行号不能。

The one thing that will confuse you

最容易令人困惑的一点

FailproofAI is one product with two halves, and each half has its own binary. Almost every early mistake is a category error between them.
LocalFailproofAI Cloud
Binary
failproofai
fp
— current. 
agenteye
is the legacy binary, still installable
Install
npm i -g failproofai
(Node ≥20.9)
uv tool install fp-cloud-cli
/ pipx
Doeshooks, policies, enforcement, capture, machine enrollmentquery sessions, audits, issues, alerts, keys, orgs; publish, deploy and roll back policy
Needs an accountno — works fully offlineyes
Config
~/.failproofai/
~/.failproofai/fpcli/cli-auth.json
, mode 0600
Never write 
uv tool install fp-cli
. 
fp_cli
is the Python module; the distribution is 
fp-cloud-cli
. The module name installs nothing.
Separate packages and separate auth — but not separate config trees any more. The cloud CLI's session file moved inside the local home, so 
~/.failproofai/
existing tells you nothing about whether you are signed in to the cloud, and being signed in tells you nothing about whether the local half is set up. Check each with its own command. (
~/.fp/cli.json
and 
$FP_HOME/cli.json
are read once for adoption and never written.)
A machine can run the local half forever without ever connecting to the cloud, and that is a legitimate end state — do not treat "not connected" as a broken install.
FailproofAI 是一个包含两半的产品，而每一半都有自己的 binary。 早期几乎所有错误，都是把两者混为一谈所导致的类别错误。
本地FailproofAI Cloud
Binary
failproofai
fp
——当前版本。
agenteye
是旧版 binary，但仍可安装
安装
npm i -g failproofai
（Node ≥20.9）
uv tool install fp-cloud-cli
/ pipx
功能hook、Policy、强制执行、采集、机器注册查询 session、审计、issue、告警、key、org；发布、部署及回滚 Policy
是否需要账号否——可完全离线运行是
配置
~/.failproofai/
~/.failproofai/fpcli/cli-auth.json
，权限 0600
绝不要执行 
uv tool install fp-cli
。 
fp_cli
是 Python module；发行包名称是 
fp-cloud-cli
。module 名称不会安装任何东西。
二者使用不同的包和不同的认证方式，但现在已不再使用彼此独立的配置目录树。Cloud CLI 的 session 文件已移至本地 home 内部，因此，
~/.failproofai/
存在并不能说明是否已登录 Cloud，而已登录 Cloud 也不能说明本地部分是否配置完成。必须分别使用各自的命令进行检查。（
~/.fp/cli.json
和 
$FP_HOME/cli.json
仅在迁移时读取一次，之后不会再被写入。）
机器可以永远只运行本地部分，而从不连接 Cloud；这是一种合法且受支持的最终状态——不要将“未连接”视为安装损坏。

The cloud half was called AgentEye

Cloud 部分过去名为 AgentEye

It is now FailproofAI Cloud. Use that name; never introduce "AgentEye" yourself. But recognise it, because the old name is still load-bearing in places a rename cannot cheaply reach, and an agent that meets one of these needs to know it is the same product:
Still says AgentEyeWhat it is
X-AgentEye-Org
, 
X-AgentEye-Client
, 
X-AgentEye-Signature
, cookie 
ae_session
, OpenAPI title "AgentEye API"		the wire and the session. 
fp
still sends every one of these
AGENTEYE_HOME
, 
~/.agenteye/events
the local daemon's legacy SDK spool, which it still watches
AGENTEYE_KEY
(collector ingest), 
AGENTEYE_API_KEY
(dashboard admin)		ingest credentials. 
FP_API_KEY
was named deliberately not to collide — never tell anyone to reuse either
ghcr.io/agenteye-enterprise
, k8s namespace 
agenteye
, ClickHouse 
agenteye.events
self-hosted infrastructure
dist 
agenteye-evaluator
, module 
agenteye_evaluator
, UA 
agenteye-server/<version>
the RETIRED v1 evaluator package. Scoring is Evaluator v2 now: author a hosted evaluation in the dashboard, or run a worker on the SDK (
failproofai_sdk.evaluator
/ 
@failproofai/sdk/evaluator
)
incidents:read
/
:write
/
:ack
, 
alerts:ack
, the 
INCIDENT_ID
positional on 
issues show
retired grants and arguments the server still parses
The env prefix follows the binary. 
fp
reads 
FP_HOME
, 
FP_JSON
, 
FP_TOKEN
, 
FP_API_KEY
, 
FP_ORG
, 
FP_DASHBOARD_URL
, 
FP_INSECURE
(plus 
FAILPROOFAI_HOME
) and zero 
AGENTEYE_*
variables. Legacy 
agenteye
reads 
AGENTEYE_HOME
, 
AGENTEYE_CLI_TOKEN
, 
AGENTEYE_CLI_JSON
. Note the dropped infix: it is 
FP_TOKEN
and 
FP_JSON
, not 
FP_CLI_TOKEN
/
FP_CLI_JSON
— a mechanical 
AGENTEYE_
→ 
FP_
rewrite produces names nothing reads. 
AGENTEYE_ENVIRONMENT
is read by neither CLI. And 
AGENTEYE_TOKEN
in the SDK install doc is an invented name for a GitHub PAT, defined by no artifact — it must not become 
FP_TOKEN
.
What never modernises is the other half of that rule: headers, the cookie, registry paths, namespaces and the daemon's own 
AGENTEYE_HOME
spool. Rename an env var when the binary changed; never rename a literal something on the wire still reads.
Two binaries can be on PATH, and 
fp
wins. Resolve it once, at the start:
bash
command -v fp agenteye        # fp first — prefer it whenever both resolve
Legacy 
agenteye
(0.1.13) has no 
policies
, 
fleet
, 
guardrails
or 
usage
at all, so a missing command there means "wrong binary", not "not shipped".
"Audit" is also two unrelated things — see Audits: pick the right one. Getting that fork wrong wastes the most time of anything in this product.
它现在名为 FailproofAI Cloud。请使用该名称，不要自行引入“AgentEye”。但仍需识别旧名称，因为在无法低成本完成重命名的位置，旧名称仍然发挥关键作用。如果 Agent 遇到以下内容，需要知道它们指向同一个产品：
仍显示 AgentEye 的内容含义
X-AgentEye-Org
、
X-AgentEye-Client
、
X-AgentEye-Signature
、cookie 
ae_session
、OpenAPI 标题“AgentEye API”		网络传输层与会话。
fp
仍会发送其中每一项
AGENTEYE_HOME
、
~/.agenteye/events
本地 daemon 的旧版 SDK spool，daemon 仍会监视它
AGENTEYE_KEY
（collector ingest）、
AGENTEYE_API_KEY
（dashboard admin）		ingest 凭据。
FP_API_KEY
被有意命名以避免冲突——绝不能让任何人复用上述任一凭据
ghcr.io/agenteye-enterprise
、k8s namespace 
agenteye
、ClickHouse 
agenteye.events
自托管基础设施
dist 
agenteye-evaluator
、module 
agenteye_evaluator
、UA 
agenteye-server/<version>
已淘汰的 v1 evaluator 包。评分现已使用 Evaluator v2：在 dashboard 中编写托管评估，或在 SDK 上运行 worker（
failproofai_sdk.evaluator
/ 
@failproofai/sdk/evaluator
）
incidents:read
/
:write
/
:ack
、
alerts:ack
、
issues show
上的 
INCIDENT_ID
位置参数		已淘汰的授权和参数，但服务端仍会解析
环境变量前缀取决于 binary。 
fp
读取 
FP_HOME
、
FP_JSON
、
FP_TOKEN
、
FP_API_KEY
、
FP_ORG
、
FP_DASHBOARD_URL
、
FP_INSECURE
（以及 
FAILPROOFAI_HOME
），并且完全不读取任何 
AGENTEYE_*
变量。旧版 
agenteye
读取 
AGENTEYE_HOME
、
AGENTEYE_CLI_TOKEN
、
AGENTEYE_CLI_JSON
。注意中间部分已被删除：现在是 
FP_TOKEN
和 
FP_JSON
，而不是 
FP_CLI_TOKEN
/
FP_CLI_JSON
——机械地将 
AGENTEYE_
替换为 
FP_
会生成无人读取的名称。两个 CLI 都不读取 
AGENTEYE_ENVIRONMENT
。SDK 安装文档中的 
AGENTEYE_TOKEN
是为 GitHub PAT 杜撰的名称，没有任何 artifact 对它作出定义——绝不能将其改为 
FP_TOKEN
。
但规则的另一半永远不会改变：headers、cookie、registry paths、namespaces，以及 daemon 自己的 
AGENTEYE_HOME
spool。binary 改变时可以重命名环境变量；但绝不要重命名网络传输层仍会读取的字面量。
两个 binary 可能同时位于 PATH 上，而 
fp
优先。 开始时只解析一次：
bash
command -v fp agenteye        # fp first — prefer it whenever both resolve
旧版 
agenteye
（0.1.13）完全没有 
policies
、
fleet
、
guardrails
或 
usage
，因此命令缺失表示“binary 用错了”，而不是“该功能未提供”。
“Audit”也指两件互不相关的事——参见审计：选择正确的审计方式。选错分支是本产品中最浪费时间的问题。

Route first

先进行路由

Read this before doing any work. Two of the specialists — 
fp-cloud-cli
and 
failproofai-sdk
— are mirrors, synced from a private repo and marked do-not-hand-edit; duplicating or patching them here is a maintenance bug. 
failproofai-eval-brainstorm
is a mirror too, and answers the question the retired 
agenteye-evaluator
skill used to: what is worth measuring. It stops at the proposal — the dashboard's eval authoring page composes, backtests and deploys the evaluation itself, so nothing here scaffolds an evaluator service any more.
The request isGo to
Stop a behaviour — "agents keep force-pushing", turn audit findings into enforcement, make a CLAUDE.md real, write/enable a policy
failproofai-policy-author
Publish tested policies as a GitHub pack others can install
failproofai-policy-publish
Publish a Cloud policy version, deploy it to fleet machines, observe, enforce, or roll back
fp-cloud-cli
Query FailproofAI Cloud — browse sessions, events, errors, evals; triage issues/alerts; manage keys, users, roles, settings
fp-cloud-cli
 (the cloud CLI skill)
Decide what to score — which dimensions are worth tracking, grounded in real sessions
failproofai-eval-brainstorm
Instrument an agent that is not one of the 12 supported CLIs — Python or TypeScript/JavaScript, on a framework (LangChain/LangGraph, CrewAI, LlamaIndex, Pydantic AI, Vercel AI SDK, Mastra) or hand-built
failproofai-sdk
Run your own evaluator worker (the eval pod) — LLM judges or checks on your own infra, in Python or TypeScript
failproofai-sdk
Every surface at once — product architecture, commands, terminology, setup, and skill selectionstay here
Anything local-machine: install, connect, daemon, backfill, flush, capture paths, upgrade, uninstallstay here
Keys and org concepts, self-hosting, "what is X"stay here
Two routes run the other way:
  • Policy work on an unset-up machine. A policy cannot be enforced without an installed CLI and (for cloud policy) a daemon. Do Set up a machine first, then hand off. The one exception is 
    fp policies test
    , which needs nothing but 
    node
    on PATH.
  • "My SDK events never appear in the dashboard." Split by evidence, not symptom. Verify the delivery half here (
    config --status
    , then 
    flush --wait
    ) before sending them to 
    failproofai-sdk
    — the bug is usually delivery, not instrumentation.
If a specialist skill is not installed, do the job here — 
references/
carries a compact version of each. Say which specialist would have done it better and how to install it:
bash
npx skills add FailproofAI/skills --skill failproofai-policy-author
执行任何工作前请先阅读本节。两个 specialist——
fp-cloud-cli
和 
failproofai-sdk
——是 mirror，内容从私有仓库同步并标记为禁止手动编辑；在此复制或修补它们属于维护缺陷。
failproofai-eval-brainstorm
同样是 mirror，它回答已淘汰的 
agenteye-evaluator
skill 曾经处理的问题：什么值得衡量。它只负责提出方案；dashboard 的 eval 编写页面会自行组合、回测和部署评估，因此这里不再为 evaluator service 生成脚手架。
请求类型去哪里
阻止某种行为——“Agent 持续 force-push”、将审计发现转化为强制执行、让 CLAUDE.md 真正生效、编写或启用 Policy
failproofai-policy-author
将经过测试的 Policy 发布为可供他人安装的 GitHub pack
failproofai-policy-publish
发布 Cloud Policy 版本、将其部署到 fleet 机器、观察、执行或回滚
fp-cloud-cli
查询 FailproofAI Cloud——浏览 session、event、error、eval；对 issue/告警进行分类处理；管理 key、用户、角色和设置
fp-cloud-cli
（Cloud CLI skill）
决定需要评分的内容——哪些维度值得跟踪，并以真实 session 为依据
failproofai-eval-brainstorm
为不属于 12 个受支持 CLI 的 Agent 插桩——使用 Python 或 TypeScript/JavaScript，基于框架（LangChain/LangGraph、CrewAI、LlamaIndex、Pydantic AI、Vercel AI SDK、Mastra）或自行构建
failproofai-sdk
运行自己的 evaluator worker（eval pod）——在自己的基础设施上使用 Python 或 TypeScript 执行 LLM judge 或检查
failproofai-sdk
同时覆盖所有入口——产品架构、命令、术语、安装和 skill 选择留在本 skill
任何本机操作——安装、连接、daemon、回填、刷新、采集路径、升级、卸载留在本 skill
key 和 org 的概念、自托管、“X 是什么”留在本 skill
另有两类路由方向相反：
  • 在尚未配置的机器上进行 Policy 工作。 没有安装 CLI，就无法执行 Policy；对于 Cloud Policy，还需要 daemon。请先执行从零配置机器，然后再移交给对应 skill。唯一的例外是 
    fp policies test
    ，它只要求 PATH 中存在 
    node
    。
  • “我的 SDK event 从未出现在 dashboard 中。” 应根据证据而非症状拆分问题。先在这里验证交付部分（
    config --status
    ，然后 
    flush --wait
    ），再转交 
    failproofai-sdk
    ——问题通常出在交付，而不是插桩。
如果未安装某个 specialist skill，则在这里完成工作——
references/
包含每个 specialist 的精简版本。请说明哪个 specialist 本来会处理得更好，以及如何安装：
bash
npx skills add FailproofAI/skills --skill failproofai-policy-author

Establish state before you act

行动前先确认状态

Never advise from assumption. Five commands, in this order, cost seconds:
bash
command -v failproofai fp agenteye           # which halves exist at all
failproofai config --status                  # cloud rows, daemon, layout/version, pause state
failproofai policies                         # what is enabled, and in which scope
fp --json whoami                             # cloud session — read .logged_in, not the exit code
command -v claude codex copilot cursor-agent opencode pi hermes openclaw droid devin agy goose
fp whoami
exits 0 whether or not you are signed in; signed out it prints 
{"logged_in": false, "auth_mode": "none"}
. Branch on the field. Any instruction to treat a non-zero exit as "not signed in" is wrong and will misreport a healthy machine.
config --status
is the single most informative command in the product. It prints the pause state first, then the connection rows, then the version triad. Read all three:
Row saysMeans
Ingest REJECTED (401/403) — N batches parked
the key stopped being accepted after connecting. Nothing is arriving. Reconnect
policy connected, ingest absentan 
events:add
-only or 
policies:pull
-only key. Half the machine works
daemon 
stopped
/ version differs from CLI		enforcement is failing closed — see Troubleshoot
pausedenforcement suspended, max 8h, one session only
config --status
overrides its own "connected" line with the delivery-health verdict, so trust the rejection row over the connection row when they disagree.
绝不要基于假设提供建议。按以下顺序执行五个命令只需几秒：
bash
command -v failproofai fp agenteye           # which halves exist at all
failproofai config --status                  # cloud rows, daemon, layout/version, pause state
failproofai policies                         # what is enabled, and in which scope
fp --json whoami                             # cloud session — read .logged_in, not the exit code
command -v claude codex copilot cursor-agent opencode pi hermes openclaw droid devin agy goose
无论是否已登录，
fp whoami
都会以 0 退出；未登录时输出 
{"logged_in": false, "auth_mode": "none"}
。应根据字段分支处理。任何要求将非零退出码视为“未登录”的指令都是错误的，会错误报告一台健康的机器。
config --status
是本产品中信息量最大的单一命令。它首先输出暂停状态，然后是连接行，最后是版本三元组。三部分都要阅读：
输出行含义
Ingest REJECTED (401/403) — N batches parked
key 在连接后不再被接受。数据没有到达。重新连接
Policy 已连接，但 ingest 缺失key 仅包含 
events:add
或仅包含 
policies:pull
。机器只有一半功能可用
daemon 为 
stopped
，或版本与 CLI 不同		强制执行正在fail closed——参见故障排查
paused强制执行已暂停，最长 8 小时，且仅限一个 session
当 
config --status
自己的“connected”行与交付健康状况结论冲突时，应信任 rejection 行，而不是 connection 行。

Set up a machine from zero

从零配置机器

State the fork before running anything, because it decides whether you need sudo:
  • Local only — hooks and policies on this machine, nothing leaves it, no account. Never run 
    --connect
    . This is a complete, supported setup.
  • Cloud connected — adds centrally-managed policy, session capture and the fleet view. Requires the daemon, which requires sudo.
bash
npm install -g failproofai        # Node >= 20.9
failproofai config                # the interactive wizard
Only the interactive 
failproofai config
wizard installs the daemon. 
config --connect
deliberately avoids sudo and merely warns. Without a daemon there is no policy pull, no transcript capture and no delivery — so a 
--connect
-only machine looks configured and ships nothing. This is the single most common broken setup.
The wizard is six steps, and the two that matter most are the ones people forget: daemon (step 0, takes sudo, runs before any hook config is touched so a failure leaves the machine untouched) and scope. It needs a TTY — see Running these as an agent.
references/setup.md
has the full wizard walkthrough, the non-interactive path, and what each step writes.
运行任何操作前先明确选择哪个分支，因为它决定是否需要 sudo：
  • 仅本地——hook 和 Policy 仅位于本机，数据不会离开本机，也不需要账号。绝不要运行 
    --connect
    。这是完整且受支持的配置方式。
  • 连接 Cloud——增加集中管理的 Policy、session 采集和 fleet 视图。需要 daemon，而 daemon 需要 sudo。
bash
npm install -g failproofai        # Node >= 20.9
failproofai config                # the interactive wizard
只有交互式 
failproofai config
wizard 会安装 daemon。 
config --connect
有意避免使用 sudo，只会发出警告。没有 daemon，就不会拉取 Policy、采集 transcript 或交付数据；因此，仅执行 
--connect
的机器看起来已经配置完成，却不会发送任何数据。这是最常见的错误配置。
wizard 共有六个步骤，其中最容易遗漏的是 daemon（步骤 0，需要 sudo，并且会在修改任何 hook 配置之前运行，因此失败时机器不会受到影响）和 scope。它需要 TTY——参见以 Agent 身份运行这些工具。
references/setup.md
包含完整的 wizard 操作说明、非交互式路径，以及每个步骤会写入的内容。

Verify it, do not assume it

进行验证，不要想当然

bash
failproofai config --status       # daemon running? both credentials present?
failproofai policies              # hooks installed for the CLIs you expect?
Then make one real tool call in the target agent CLI and confirm a decision appears in the local dashboard's Policies → Activity log (
failproofai
, port 8020). An install that has never evaluated a single event is not a verified install.
bash
failproofai config --status       # daemon running? both credentials present?
failproofai policies              # hooks installed for the CLIs you expect?
然后在目标 Agent CLI 中发起一次真实工具调用，并确认本地 dashboard（
failproofai
，端口 8020）的 Policies → Activity log 中出现相应 decision。从未评估过任何 event 的安装不算验证成功。

Connect to the cloud and prove both halves

连接 Cloud 并验证两部分

One URL and one token configure two independent capabilities:
CapabilityPermissionVerified againstWritten to
Pull managed policy
policies:pull
GET <base>/enforcement/v1/desired-state
credentials.json
Push events/transcripts
events:add
empty 
POST <base>/v1/events
collector block + ingest credential
bash
failproofai config --connect https://app.befailproof.ai --token "<one-time-secret>"
Each half is probed before anything is written, and only what verified is written. So a partial success is normal and is reported per-half.
Four traps here, all of which have bitten people:
  • The exit code tracks only the policy half. An 
    events:add
    -only key writes a working ingest credential and still exits 1. Never 
    &&
    -chain on this command — read the output.
  • Transcripts are sent by default. 
    --no-transcripts
    limits to hook decisions. It is matched by exact string, and the 
    config
    branch validates no unknown flags — so 
    --no-transcript
    , 
    --notranscripts
    , any typo, is silently ignored and full transcripts (prompts, file contents) ship. Confirm with 
    config --status
    , not with the exit code.
  • The machine id does not default to the hostname, despite what 
    config --help
    says. It is an explicit 
    --machine-id
    , else the one already on disk, else a random UUID. The hostname is only the mutable label. Passing 
    --machine-id "$(hostname)"
    on several machines silently merges them into one.
  • Use a scoped key, not an admin key. 
    events:add
    + 
    policies:pull
    is the whole requirement. The secret is shown exactly once.
一个 URL 和一个 token 会配置两项彼此独立的能力：
能力权限验证方式写入位置
拉取托管 Policy
policies:pull
GET <base>/enforcement/v1/desired-state
credentials.json
推送 event/transcript
events:add
空的 
POST <base>/v1/events
collector 配置块 + ingest 凭据
bash
failproofai config --connect https://app.befailproof.ai --token "<one-time-secret>"
写入任何内容之前，会分别探测两部分，并且只写入验证通过的部分。因此，部分成功属于正常情况，系统会按部分分别报告。
这里有四个陷阱，曾让许多人栽跟头：
  • 退出码只跟踪 Policy 部分。 仅含 
    events:add
    的 key 会写入可用的 ingest 凭据，同时仍以 1 退出。绝不要用 
    &&
    串联此命令——应读取输出。
  • 默认发送 transcript。 
    --no-transcripts
    会将范围限制为 hook decision。该选项通过精确字符串匹配，而 
    config
    分支不验证任何未知 flag——因此，
    --no-transcript
    、
    --notranscripts
    或任何拼写错误都会被静默忽略，并继续发送完整 transcript（prompt、文件内容）。请通过 
    config --status
    确认，而不是依赖退出码。
  • machine id 默认不会使用 hostname，尽管 
    config --help
    如此说明。它的取值依次为：显式指定的 
    --machine-id
    、磁盘上已有的值、随机 UUID。hostname 只是可变的标签。在多台机器上传入 
    --machine-id "$(hostname)\"
    会将它们静默合并为同一台机器。
  • 使用 scoped key，而不是 admin key。 
    events:add
    + 
    policies:pull
    已覆盖全部需求。secret 只显示一次。

Bring in existing history

导入现有历史数据

This is the "transfer" surface. Four commands, each for a different situation:
SituationCommand
Connected later than the work happened; dashboard cleared; machine re-enrolled
failproofai backfill --since 30d
Spooled batches not shipped yet; want them now
failproofai flush --wait
Sessions live somewhere the collector does not watch (second profile, team share, container home)
failproofai harness add-path <harness> <label>=<path>
Upgraded npm but the daemon/layout is behind
failproofai update
bash
failproofai backfill --since 7d --dry-run    # always preview first
failproofai backfill --since 7d
这是“传输”操作入口。四个命令分别适用于不同情况：
情况命令
连接时间晚于工作发生时间；dashboard 已清空；机器重新注册
failproofai backfill --since 30d
spool 中仍有批次未发送，希望立即发送
failproofai flush --wait
session 位于 collector 未监视的位置（第二个 profile、团队共享目录、容器 home）
failproofai harness add-path <harness> <label>=<path>
已升级 npm，但 daemon 或布局仍为旧版
failproofai update
bash
failproofai backfill --since 7d --dry-run    # always preview first
failproofai backfill --since 7d

wait for the daemon's next tick before flushing — see below

wait for the daemon's next tick before flushing — see below

failproofai flush --wait

**`backfill` then `flush --wait` back to back is a race that reports success while nothing
shipped.** `backfill` only writes a *request file* that the daemon drains on its next tick;
`flush` exits 0 with "Nothing spooled" the instant the spool is empty. Run `backfill`, wait
for the collector to actually re-read (watch `config --status`), then `flush`.

The collector will not re-read a file it already holds a cursor for — that is exactly what
`backfill` exists to override. `--since` takes `30d`, `6m`, or `YYYY-MM-DD`; default 30 days.

`references/transfer.md` covers re-enrolling into a different org, keeping vs resetting the
machine id, and moving capture paths.
failproofai flush --wait

**连续执行 `backfill` 和 `flush --wait` 会产生竞态：命令报告成功，但实际上没有发送任何数据。** `backfill` 只写入一个*请求文件*，daemon 会在下一个 tick 中处理它；而 spool 一旦为空，`flush` 就会立即以 0 退出并显示“Nothing spooled”。应先运行 `backfill`，等待 collector 实际重新读取文件（观察 `config --status`），然后再执行 `flush`。

collector 不会重新读取已持有 cursor 的文件——这正是 `backfill` 所要覆盖的场景。`--since` 接受 `30d`、`6m` 或 `YYYY-MM-DD`；默认值为 30 天。

`references/transfer.md` 介绍重新注册到其他 org、保留或重置 machine id，以及迁移采集路径。

Install hooks and policies across the 12 agent CLIs

在 12 个 Agent CLI 中安装 hook 和 Policy

bash
failproofai policies --install --cli claude --scope user
failproofai policies add block-rm-rf
Supported: 
claude
, 
codex
, 
copilot
, 
cursor
, 
opencode
, 
pi
, 
hermes
, 
openclaw
, 
factory
(binary 
droid
), 
devin
, 
antigravity
(binary 
agy
), 
goose
.
Four things to get right:
  • Scope is not just a location. 
    --scope project
    writes a committable 
    npx -y failproofai
    command with no machine-specific paths; 
    user
    /
    local
    write an absolute binary path. Hermes and OpenClaw are user-scope only — they have no project config at all.
  • Bare 
    --install
    with no policy names is interactive on a TTY     (an arrow-key picker that will block an agent forever) and, off a TTY, silently installs only the 11 default-enabled builtins out of 39. Name the policies explicitly.
  • Installs are additive. Repeated 
    --install
    unions with what is already enabled; a second 
    --custom
    adds another path. There is no "exactly these and nothing else" — use 
    --uninstall
    to subtract.
  • Convention policies load by filename. Any file matching 
    policies.{js,mjs,ts}
    in 
    .failproofai/policies/
    (project) or 
    ~/.failproofai/policies/
    (user) auto-loads. 
    block-force-push.mjs
    is skipped silently and enforces nothing; name it 
    block-force-push-policies.mjs
    .
Enforcement is not uniform across the 12 harnesses. A 
deny
only stops something where that harness consumes the verdict — 
PreToolUse
is the only event that blocks everywhere. 
PostToolUse
is observation-only on 10 of 12. 
references/harnesses.md
has the matrix; for authoring, 
failproofai-policy-author
owns it in depth.
One builtin, 
block-failproofai-commands
, is always on and cannot be disabled — it bypasses the enabled set entirely, including during a pause and when the config fails to parse. That is deliberate: it is what stops an agent disabling its own guardrails.
bash
failproofai policies --install --cli claude --scope user
failproofai policies add block-rm-rf
支持：
claude
、
codex
、
copilot
、
cursor
、
opencode
、
pi
、
hermes
、
openclaw
、
factory
（binary 为 
droid
）、
devin
、
antigravity
（binary 为 
agy
）、
goose
。
有四件事必须处理正确：
  • Scope 不只是位置。 
    --scope project
    写入可提交到版本库的 
    npx -y failproofai
    命令，不包含机器专属路径；
    user
    /
    local
    则写入 binary 的绝对路径。Hermes 和 OpenClaw 仅支持 user scope——它们完全没有项目配置。
  • 在 TTY 上直接执行不带 Policy 名称的 
    --install
     会进入交互模式（方向键选择器会让 Agent 永久阻塞）；在非 TTY 环境中，则会静默只安装 39 个内置 Policy 中默认启用的 11 个。应明确指定 Policy 名称。
  • 安装是累加式的。 重复执行 
    --install
    会与已启用项取并集；第二次执行 
    --custom
    会新增另一条路径。不存在“只启用这些且不启用其他任何项”的选项——需要移除时使用 
    --uninstall
    。
  • 约定 Policy 按文件名加载。 
    .failproofai/policies/
    （项目）或 
    ~/.failproofai/policies/
    （用户）中，任何匹配 
    policies.{js,mjs,ts}
    的文件都会自动加载。
    block-force-push.mjs
    会被静默跳过，不会执行任何强制措施；应命名为 
    block-force-push-policies.mjs
    。
12 个 harness 的强制执行机制并不统一。 只有当某个 harness 会处理 verdict 时，
deny
才能阻止相应行为——
PreToolUse
是唯一能在所有 harness 上阻止操作的事件。在 12 个 harness 中，有 10 个仅能通过 
PostToolUse
进行观察。
references/harnesses.md
提供了矩阵；若需编写 Policy，则由 
failproofai-policy-author
深入负责。
内置 Policy 
block-failproofai-commands
始终启用且无法禁用——它会绕过启用集合，包括暂停期间以及配置解析失败时。这是有意设计的：它用于阻止 Agent 禁用自己的 guardrail。

Audits: pick the right one

审计：选择正确的审计方式

This fork is unavoidable and is the most common source of wasted effort.
Local auditCloud audit
Command
failproofai audit
dashboard, or 
fp audits …
Scansthis machine's own agent history, offlinesessions already delivered to the cloud
Accountnot neededrequired
Scheduling
audit --schedule [days]
, emails you		server-side cadence
Outputlocalhost:8020 dashboard + a JSON cachefindings → issues in the dashboard
failproofai audit
parses exactly six arguments — 
--help
/
-h
, 
--status
, 
--schedule [days]
, 
--no-schedule
, 
--email
(one of the four flags product-wide that also accepts an 
=
), and the undocumented daemon-spawned 
--scheduled
. Everything else is rejected by a catch-all, so 
--since
, 
--cli
, 
--json
and 
--port
all fail: there is no way to narrow or redirect a scan. A bare 
failproofai audit
also does not exit — it serves the dashboard until Ctrl+C. Never call it in a foreground agent shell. The cache is written before the server starts, so if you must run it unattended:
bash
timeout 180 failproofai audit >/dev/null 2>&1 || true    # exits 124; cache is written
cat ~/.failproofai/audit/dashboard.json                  # layout 4 path
Turning findings into enforcement is 
failproofai-policy-author
's job — it reads that same cache. Send them there rather than hand-writing policies here.
这个分支无法回避，也是最常导致效率损失的问题。
本地审计Cloud 审计
命令
failproofai audit
dashboard，或 
fp audits …
扫描范围离线扫描本机自身的 Agent 历史已交付至 Cloud 的 session
账号不需要需要
调度
audit --schedule [days]
，通过电子邮件发送		服务端周期执行
输出localhost:8020 dashboard + JSON 缓存dashboard 中形成 finding → issue
failproofai audit
只解析六个参数——
--help
/
-h
、
--status
、
--schedule [days]
、
--no-schedule
、
--email
（全产品四个也接受 
=
的 flag 之一），以及 daemon 启动时使用的未公开参数 
--scheduled
。其他所有参数都会被兜底逻辑拒绝，因此 
--since
、
--cli
、
--json
和 
--port
都会失败：无法缩小扫描范围或更改输出位置。直接执行 
failproofai audit
也不会退出——它会持续提供 dashboard，直到按下 Ctrl+C。绝不能在 Agent 的前台 shell 中调用它。缓存会在 server 启动前写入，因此如果必须无人值守地运行：
bash
timeout 180 failproofai audit >/dev/null 2>&1 || true    # exits 124; cache is written
cat ~/.failproofai/audit/dashboard.json                  # layout 4 path
将 finding 转化为强制执行是 
failproofai-policy-author
的职责——它会读取同一份缓存。请将任务交给它，而不要在这里手动编写 Policy。

Read sessions and traces

阅读 session 和 trace

A trace is the ordered, nested view of one session. The documented investigation order:
  1. Confirm the goal and the environment the run actually had.
  2. Find the first divergence, not the last error — the last error is usually a symptom.
  3. Inspect the model context and the tool input immediately before it.
  4. Check retries, latency, human interventions and policy decisions around that point.
Most of this surface is the dashboard. The queryable slice is the cloud CLI — hand off to 
fp-cloud-cli
for anything beyond a one-shot setup verification. 
references/sessions.md
has the event kinds and what is CLI-reachable versus dashboard-only.
trace 是单个 session 的有序嵌套视图。推荐的排查顺序如下：
  1. 确认该次运行实际具有的目标和环境。
  2. 找出首次偏离点，而不是最后一个错误——最后一个错误通常只是症状。
  3. 检查紧邻该位置之前的模型上下文和工具输入。
  4. 检查该位置附近的 retry、延迟、人工干预和 Policy decision。
此操作入口主要位于 dashboard。可查询的部分由 Cloud CLI 提供——除一次性安装验证外，其余任务应移交给 
fp-cloud-cli
。
references/sessions.md
介绍了 event 类型，以及哪些内容可通过 CLI 获取、哪些只能在 dashboard 中查看。

Prevent: observe → enforce → roll back

预防：观察 → 执行 → 回滚

The rollout the product actually supports, and every step of it is CLI-drivable — no dashboard required:
StepCommand
1. Prove the policy decides correctly, offline
fp policies test ./rule.mjs --command "…"
2. Publish an immutable version
fp policies publish <policy-id> ./rule.mjs
3. Deploy it pinned, in observe, to one machine
fp fleet deploy <machine-id> --add <policy-id>@3:observe
4. Run a real session, then read what it would have done
fp guardrails summary
, 
fp guardrails timeline
5. Promote that one machine to enforce, then expand
fp fleet deploy <machine-id> --add <policy-id>@3:enforce
6. Roll back
fp fleet rollback <machine-id>
Three things that bite before you get through it:
  • fp policies publish
    deploys nothing.     It mints a new version, never edits one in place, and that version sits unused until a 
    fleet deploy
    names it. Publishing and shipping are separate acts.
  • A bare 
    --add
    on a new policy enforces it.     
    :observe
    is not the default — omitting the effect is how a first deploy goes straight to enforcement on a live machine. Always write the effect. Effects are exactly 
    enforce
    and 
    observe
    .
  • Every 
    policies
    /
    fleet
    /
    guardrails
    subcommand except 
    policies test
    exits 2 under an API key.     This rollout is a human-session operation; CI cannot drive it.
Step 1 needs no server, no auth, no fleet and nothing installed in the working directory — the CLI shims the 
failproofai
module itself. It wants only 
node
on PATH:
bash
fp policies test ./rule.mjs --command "git push --force origin main"
以下是产品实际支持的 rollout 流程，每一步均可通过 CLI 完成，不需要 dashboard：
步骤命令
1. 离线证明 Policy 能正确作出 decision
fp policies test ./rule.mjs --command "…"
2. 发布不可变版本
fp policies publish <policy-id> ./rule.mjs
3. 将其固定版本部署到一台机器，并设为 observe 模式
fp fleet deploy <machine-id> --add <policy-id>@3:observe
4. 运行一次真实 session，然后读取其原本会执行的操作
fp guardrails summary
、
fp guardrails timeline
5. 将该机器提升为 enforce，然后再扩大范围
fp fleet deploy <machine-id> --add <policy-id>@3:enforce
6. 回滚
fp fleet rollback <machine-id>
有三个问题会在完成流程前造成阻碍：
  • fp policies publish
    不会部署任何内容。     它只生成新版本，绝不会原地修改已有版本；除非 
    fleet deploy
    明确引用该版本，否则它会一直闲置。发布和交付是两个独立操作。
  • 对新 Policy 直接使用 
    --add
    会立即执行它。     
    :observe
    并不是默认值——省略 effect 会导致首次部署直接对运行中的机器执行强制措施。务必明确写出 effect。effect 只能是 
    enforce
    和 
    observe
    。
  • 除 
    policies test
    外，所有 
    policies
    /
    fleet
    /
    guardrails
    子命令在 API key 下都会以 2 退出。     此 rollout 必须由人类会话操作；CI 无法驱动。
步骤 1 不需要 server、认证、fleet，也不需要在工作目录中安装任何内容——CLI 会对 
failproofai
module 本身进行 shim。它只要求 PATH 中存在 
node
：
bash
fp policies test ./rule.mjs --command "git push --force origin main"

{"ok":true,"decision":"deny","policies":[{"name":"no-force-push","decision":"deny",…}]}

{"ok":true,"decision":"deny","policies":[{"name":"no-force-push","decision":"deny",…}]}


State its limit honestly: that proves the policy parses, registers and decides for the input
you handed it. It cannot prove the daemon feeds it the same context on a real machine. Only
step 4 shows that.

`fp-cloud-cli` owns this in depth — the `id@v:effect` ref grammar, `--set` versus
`--add`, the concurrency guard, and why `disable` stops enforcement while `delete` does not.

应如实说明其局限：这只能证明 Policy 能够解析、注册，并针对传入输入作出 decision。它无法证明真实机器上的 daemon 会提供完全相同的上下文。只有步骤 4 能够证明这一点。

`fp-cloud-cli` 会深入处理相关内容——包括 `id@v:effect` 引用语法、`--set` 与 `--add` 的区别、并发保护，以及为什么 `disable` 会停止强制执行而 `delete` 不会。

Operate the fleet and the organization

运维 fleet 和组织

Admin → enforcement shows assigned versus reported deployment plus last check-in, and 
fp fleet list
/ 
fp fleet diff <machine-id>
show the same split from the terminal. The two diverging is the signal: a machine that never pulled, or stopped reporting.
Permissions are flat 
resource:action
tokens (
events:add
, 
policies:pull
, 
audits:write
). Presets 
read-only
/ 
standard
/ 
admin
seed grants. Two rules worth carrying:
  • keys:update
    and 
    orgs:admin
    are human-only and must never sit on an API key — an "admin" key is deliberately weaker than an admin user.
  • The server widens grants at auth time (
    alerts:read
    also carries 
    issues:read
    ), but the dashboard and CLI display the stored grant. Stored ≠ effective.
Depth is in 
references/cloud.md
; live key/user/org operations belong to 
fp-cloud-cli
.
Admin → enforcement 会显示 assigned 部署与 reported 部署的差异，以及最后一次 check-in；
fp fleet list
/ 
fp fleet diff <machine-id>
也会在终端中显示同样的区分。两者不一致就是信号：某台机器可能从未拉取配置，或已停止上报。
权限采用扁平的 
resource:action
token（
events:add
、
policies:pull
、
audits:write
）。预设 
read-only
/ 
standard
/ 
admin
用于初始化授权。有两条规则值得记住：
  • keys:update
    和 
    orgs:admin
    仅限人类使用，绝不能放在 API key 上——这里的“admin” key 被有意限定为弱于 admin user。
  • 服务端在认证时会扩大授权范围（
    alerts:read
    同时包含 
    issues:read
    ），但 dashboard 和 CLI 显示的是已存储的授权。已存储 ≠ 实际生效。
深度内容位于 
references/cloud.md
；涉及实时 key、用户和 org 的操作应交给 
fp-cloud-cli
。

Troubleshoot by symptom

按症状排查故障

SymptomFirst checkUsual cause
Nothing in the cloud dashboard
config --status
no daemon (ran 
--connect
only), or ingest rejected
Machine not receiving policies
config --status
policy row		key lacks 
policies:pull
, or daemon not running
Every tool call denied, on every CLI
config --status
daemon row		daemon unreachable or version-skewed → fail-closed
Custom policy does nothingfilenamemust end 
policies.{js,mjs,ts}
Sessions stop at a date
backfill --since
cursor advanced before there was anywhere to send
flush
says "Nothing spooled" but dashboard is empty		ran it too soon after 
backfill
the daemon tick had not run
Fail-closed is deliberate. Once daemon configuration is recorded there is no silent in-process fallback: an unreachable or protocol-skewed daemon denies everything, including 
UserPromptSubmit
, so the user cannot even ask their agent what happened. Fix the daemon (
failproofai update
, or restart the unit); as a last resort set 
daemon.configured
to false in 
~/.failproofai/config.json
. Running any CLI command self-heals three provable cases automatically.
Windows is unsupported for everything cloud- or capture-related — the daemon is Linux/macOS only. 
flush
refuses outright, but 
config --connect
still stores credentials, so a Windows machine can look connected and never ship anything.
症状首先检查常见原因
Cloud dashboard 中没有任何内容
config --status
没有 daemon（仅运行了 
--connect
），或 ingest 被拒绝
机器未收到 Policy
config --status
中的 Policy 行		key 缺少 
policies:pull
，或 daemon 未运行
所有 CLI 上的每次工具调用都被拒绝
config --status
中的 daemon 行		daemon 无法访问或版本不一致 → fail closed
自定义 Policy 无任何作用文件名必须以 
policies.{js,mjs,ts}
结尾
session 截止到某个日期后停止
backfill --since
cursor 在数据有可用去向之前就已推进
flush
显示“Nothing spooled”，但 dashboard 为空		在 
backfill
后执行得太早		daemon tick 尚未运行
Fail closed 是有意设计的。 一旦记录了 daemon 配置，就不会再静默回退到进程内处理：daemon 无法访问或协议版本不一致时，会拒绝所有操作，包括 
UserPromptSubmit
，因此用户甚至无法询问 Agent 发生了什么。请修复 daemon（执行 
failproofai update
，或重启 unit）；作为最后手段，可将 
~/.failproofai/config.json
中的 
daemon.configured
设置为 false。运行任何 CLI 命令都会自动修复三种可证明的情况。
所有与 Cloud 或采集相关的能力均不支持 Windows——daemon 仅支持 Linux/macOS。
flush
会直接拒绝执行，但 
config --connect
仍会存储凭据，因此 Windows 机器可能显示已连接，却永远不会发送任何数据。

Upgrade, relocate, remove

升级、迁移位置和卸载

There is a version triad — npm CLI, daemon binary, 
~/.failproofai
layout — and they move independently.
bash
npm install -g failproofai@latest    # replaces the CLI and NOTHING else
failproofai update                   # migrations + matching daemon binary + restart
npm i -g failproofai@latest
alone is never enough on a daemon machine: the old daemon binary stays, the layout stays, and the machine goes fail-closed on version skew. Always follow with 
failproofai update
. Use 
failproofai migrate --dry-run
to see layout steps alone.
bash
failproofai uninstall            # hook entries from every CLI + the daemon service
failproofai uninstall --purge    # also deletes ~/.failproofai
Run 
uninstall
before 
npm rm -g failproofai
— npm runs no uninstall script, so removing the package alone leaves the hooks and the root-owned service behind. 
--yes
removes the service without asking.
系统存在一个版本三元组——npm CLI、daemon binary、
~/.failproofai
布局——三者的版本会独立变化。
bash
npm install -g failproofai@latest    # replaces the CLI and NOTHING else
failproofai update                   # migrations + matching daemon binary + restart
在带 daemon 的机器上，单独执行 
npm i -g failproofai@latest
永远不够：旧 daemon binary 和旧布局会保留下来，机器会因版本不一致而进入 fail closed。始终应在之后执行 
failproofai update
。使用 
failproofai migrate --dry-run
可单独查看布局迁移步骤。
bash
failproofai uninstall            # hook entries from every CLI + the daemon service
failproofai uninstall --purge    # also deletes ~/.failproofai
必须在 
npm rm -g failproofai
之前运行 
uninstall
——npm 不会运行 uninstall script，因此仅删除包会遗留 hook 和以 root 身份运行的服务。
--yes
会跳过确认并移除服务。

Running these tools as an agent

以 Agent 身份运行这些工具

Collected here because getting one wrong wastes a turn or hangs the session:
  • No 
    --flag=value
    .     Every parser is hand-rolled and rejects the equals form. Across both binaries there are exactly four exceptions — 
    --cli=
    , 
    --effect=
    , 
    --out=
    and 
    --email=
    . Everything else takes a space, 
    pack --only
    and 
    --category
    included.
  • fp
    globals go before the command.     
    fp --json sessions
    works; 
    fp sessions --json
    is a usage error and exits 2. A command's own options come after it: 
    fp --json keys create ci-bot
    . The globals are 
    --json --base-url --org --token --api-key --insecure/--secure --timeout --quiet --no-color
    .
  • Commands that never exit: 
    failproofai audit
    (serves until Ctrl+C) and the bare 
    failproofai
    dashboard. Use 
    timeout
    , or ask the user to run them.
  • Commands that need a TTY: the 
    failproofai config
    wizard, and 
    policies --install
    with no policy names. Off a TTY the latter silently narrows to the 11 defaults.
  • Exit codes that lie: 
    config --connect
    reports only the policy half; 
    flush --wait
    exits 0 on an empty spool whether or not delivery works. Read stdout.
  • Nothing here needs sudo except the daemon, and only the wizard and 
    update
    ask for it.
  • Never run 
    --connect
    , 
    --disconnect
    , 
    uninstall
    , a user-scope install or 
    fp fleet deploy
    on your own initiative. They change what the user's machines do everywhere — enrollment sends data off the machine, and a deploy can start denying tool calls on someone else's box. Propose the command; let them run it.
将相关事项集中放在这里，是因为其中任何一项处理错误都会浪费一次操作或导致 session 卡住：
  • 不支持 
    --flag=value
    。     每个 parser 都是手写的，并拒绝等号形式。两个 binary 一共只有四个例外——
    --cli=
    、
    --effect=
    、
    --out=
    和 
    --email=
    。其他所有 flag 都使用空格分隔，包括 
    pack --only
    和 
    --category
    。
  • fp
    的全局参数必须放在命令之前。     
    fp --json sessions
    可以；
    fp sessions --json
    是用法错误，并以 2 退出。命令自身的选项应放在命令之后：
    fp --json keys create ci-bot
    。全局参数为 
    --json --base-url --org --token --api-key --insecure/--secure --timeout --quiet --no-color
    。
  • 永不退出的命令：
    failproofai audit
    （持续提供服务直到 Ctrl+C）和不带子命令的 
    failproofai
    dashboard。请使用 
    timeout
    ，或让用户自行运行。
  • 需要 TTY 的命令：
    failproofai config
    wizard，以及不指定 Policy 名称的 
    policies --install
    。在非 TTY 环境中，后者会静默缩减为 11 个默认项。
  • 会误导人的退出码：
    config --connect
    只报告 Policy 部分；
    flush --wait
    无论交付是否成功，只要 spool 为空就会以 0 退出。请读取 stdout。
  • 除 daemon 外，这里没有任何操作需要 sudo，而且只有 wizard 和 
    update
    会请求 sudo。
  • 绝不要擅自运行 
    --connect
    、
    --disconnect
    、
    uninstall
    、user scope 安装或 
    fp fleet deploy
    。这些操作会改变用户机器在所有位置的行为——注册会将数据发送出机器，而部署可能会开始拒绝其他机器上的工具调用。应提出命令建议，让用户自行执行。

References

参考资料

Load whenFile
"what is a finding / trace / deployment" — the nouns and the loop
references/concepts.md
Installing, the wizard's six steps, connecting, provisioning without a TTY
references/setup.md
Backfill, flush, capture paths, re-enrolling, upgrade, uninstall
references/transfer.md
The daemon: what it is, how it runs, how it fails, how to fix it
references/daemon.md
Builtins, packs, local config files and merge order, scopes
references/policies.md
Which of the 12 harnesses enforces what, and where each config lives
references/harnesses.md
Local vs cloud audit, findings, issues, alerts, agent contracts
references/audits.md
Sessions, events, traces, queries, dashboards, the Assistant
references/sessions.md
FailproofAI Cloud: CLI surface, HTTP API, keys and permissions, orgs, self-hosting
references/cloud.md
Every 
failproofai
command and flag, env vars, on-disk paths
references/cli.md
Symptom → check → cause → fix, in depth
references/troubleshooting.md
End-to-end setup across the local and Cloud halves
references/end-to-end-setup.md
Complete command catalog for both binaries
references/commands.md
Observe, enforce, evaluate, audit, and manage as product workflows
references/product-verticals.md
Environment variables and configuration locations
references/env-vars.md
Legacy literals that must not be renamed
references/literals.md
Product terminology
references/glossary.md
Every sibling skill, ownership boundary, and documentation map
references/skill-directory.md
需要加载的内容文件
“finding / trace / deployment 是什么”——相关名词及其闭环
references/concepts.md
安装、wizard 的六个步骤、连接、无需 TTY 的配置方式
references/setup.md
回填、刷新、采集路径、重新注册、升级、卸载
references/transfer.md
daemon：它是什么、如何运行、如何失败、如何修复
references/daemon.md
内置项、pack、本地配置文件、合并顺序和 scope
references/policies.md
12 个 harness 中分别强制执行什么，以及配置位于何处
references/harnesses.md
本地与 Cloud 审计、finding、issue、告警、Agent 契约
references/audits.md
session、event、trace、查询、dashboard、Assistant
references/sessions.md
FailproofAI Cloud：CLI 接口、HTTP API、key 与权限、org、自托管
references/cloud.md
所有 
failproofai
命令和 flag、环境变量、磁盘路径
references/cli.md
深入理解“症状 → 检查 → 原因 → 修复”
references/troubleshooting.md
本地与 Cloud 两部分的端到端配置
references/end-to-end-setup.md
两个 binary 的完整命令目录
references/commands.md
观察、执行、评估、审计，以及作为产品工作流进行管理
references/product-verticals.md
环境变量和配置位置
references/env-vars.md
绝不能重命名的旧版字面量
references/literals.md
产品术语
references/glossary.md
所有 sibling skill、职责边界和文档地图
references/skill-directory.md