Cut 1.0.2 and overhaul the documentation

CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## 1.0.2-beta.9 — 2026-08-27
+## 1.0.2 — 2026-08-27
+
+The stable cut of the `1.0.2-beta.*` line, which stays documented in its own
+sections underneath. The entries below shipped in no beta — `next` stopped at
+`1.0.2-beta.8` — so they reach users for the first time here.
+
+Worth stating plainly for anyone arriving from 1.0.1: **`policies` is now the
+one noun**, and the package ships NO policies of its own. `policy`, `pack` and
+`p` still reach the same command, but a policy set is something you add
+(`failproofai policies add FailproofAI/policies`) or publish
+(`failproofai publish`) rather than something the install carries. A pack is
+pinned by the digest of its artifact and by the commit it was built from, and a
+pack that cannot be loaded DENIES within the scope it declared rather than
+disappearing quietly.
+
+### Docs
+
+- The documentation is rewritten against the shipped 1.0.2 CLI. An audit of all 68 English pages plus the README found 219 factual errors, and the whole of `start/` documented a setup path that no longer exists: bare `failproofai config` — the verb that installs the daemon and wires every supported agent CLI — appeared on no page, and neither did `failproofai policies add FailproofAI/policies`, so a reader who followed the quickstart end to end finished with hook entries, no daemon, and one enforcing policy. The retired `pack`/`policy` spellings, `pack add core`, `--bundled` and `config --connect <url> --token <key>` are gone; the local no-account path (the dashboard on `localhost:8020`, local findings from `failproofai audit`, and separately documented telemetry controls) is documented for the first time; and `start/integrations.mdx`, which five pages linked to and nothing in the navigation reached, is wired in (#756)
+- Observe mode is documented as what it is: the policy is EVALUATED for real, under the same timeout and error handling as an enforcing one, and its verdict recorded — only the enforcement is withheld. Both layers that set it are named, `failproofai publish --effect observe` for a pack and `fp fleet deploy <machine> --add <id>:observe` for a Cloud deployment, and every page showing `--add` now says that a bare one ENFORCES immediately, which is how a shadow rollout turns into a production incident. `policies/deploy.mdx` had described the workflow entirely as dashboard clicks and named no `fp` command at all; the CLI lane — `fp fleet list/show/deploy/diff/history/rollback`, `fp guardrails summary|timeline`, and `fp policies test`, which decides a policy locally with no server and no auth — is now covered (#756)
+- Enforcement is no longer described as uniform across the twelve harnesses. `docs/index.mdx` claimed "the same events, the same policies, and the same session history apply to every one" — the exact claim `src/hooks/enforcement-capability.ts` exists to stop drifting. A `PreToolUse` deny is verified to stop the tool on all twelve; a `Stop` deny is verified on eight, is `observe` on Pi, and is unverified on OpenCode, Hermes and Goose. Goose has no `Stop` event and we install none on Hermes, so the five `require-*-before-stop` builtins never fire on either. A pair with no row in that file now reads as unverified rather than as blocking (#756)
+- The install no longer claims that policies come with it. "39 built-in policies activate immediately" and "eleven are on when you accept the defaults" were both false: `configure-wizard.ts` enables nothing, so `enabledPolicies` is empty and `builtin-policies.ts` registers only what carries `alwaysOn` — exactly one policy, `block-failproofai-commands`. The eleven `defaultEnabled` flags are catalog metadata that decide nothing until a pack is installed (#756)
+- The Policy Hub at befailproof.ai/policy-hub is documented, including that `failproofai publish` does not set the `failproofai-policies` topic the hub indexes on — so publishing is publish-then-tag-by-hand until it does (#756)
+- Two claims copied out of the CLI's own `--help` are corrected, because the help is wrong. Scope support is not "Codex, Copilot, Cursor, OpenCode and Pi take user or project only": `types.ts` makes Hermes and OpenClaw **user-only** and gives `local` to Claude alone. And `backfill --help` names `~/.failproofai/config.toml`, a layout-2 file no current build writes; the file is `config.json` (#756)
+- Six fabricated commands and flags were caught by an adversarial verification pass before they shipped, among them `fp fleet rename --name` (the command takes two positionals and declares no options), a `tool` filter on the local dashboard's activity view (`HookActivityFilters` has six keys and tool is not one), and `failproofai config --token <key> --machine-label <name>` as a setup one-liner — which sets nothing up, since any invocation carrying `--machine-label` without `--connect` routes straight to the rename path and exits 1 on a machine that is not yet connected (#756)
 
 ### Fixes
 

Cargo.toml

@@ -3,7 +3,7 @@ resolver = "3"
 members = ["crates/*"]
 
 [workspace.package]
-version = "1.0.2-beta.10"
+version = "1.0.2"
 edition = "2024"
 license-file = "LICENSE"
 repository = "https://github.com/FailproofAI/failproofai"

README.md

@@ -14,11 +14,11 @@
 
 **Translations:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md)
 
-**Observability and enforcement for every harness your agents run in.**
-Wherever your agents run, we see it — and we can say no. Failproof hooks 12 agent
-harnesses — coding CLIs like Claude Code and Codex, chat gateways like Hermes,
-self-hosted assistants like OpenClaw — capturing every run and blocking dangerous
-tool calls before they execute. 39 built-in policies. Zero latency. Runs locally.
+**See what your agents do. Stop known failures before they repeat.**
+Failproof AI works wherever your agents run: coding tools like Claude Code and
+Codex, chat gateways like Hermes, self-hosted assistants like OpenClaw, and agents
+you instrument yourself. It records each run and can block dangerous tool calls
+before they execute.
 
 </div>
 
@@ -30,9 +30,9 @@ 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.
+Twelve harnesses in two classes are supported: ten coding CLIs, plus two
+gateways: Hermes, OpenClaw. The policy API and session history are shared; which
+events can block varies by harness.
 
 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
@@ -134,13 +134,31 @@ your own runtime — [talk to us](mailto:support@befailproof.ai) and we'll map i
 
 ## Install
 
+Give a compatible agent the Failproof AI skill if you want it to guide setup,
+inspect the machine, and route policy, audit, session, and Cloud work correctly:
+
+```sh
+npx skills add FailproofAI/skills
+```
+
+This installs the umbrella skill and its specialist siblings. To install only the
+umbrella, add `--skill failproofai`. Skills supply operating instructions; install
+and configure the product itself with:
+
 ```sh
 npm install -g failproofai
-failproofai policies --install   # or just run `failproofai` and accept the first-run prompt
-failproofai
+failproofai config
+failproofai policies add FailproofAI/policies
+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 connects supported agents and installs the background service. It chooses no
+policy pack: before you add one, only `block-failproofai-commands` runs to stop an
+agent disabling Failproof AI.
+
+Connect Cloud without prompts with `failproofai config --token <machine-key>`. On a
+shared machine or in CI, set `FAILPROOFAI_CLOUD_TOKEN` and run `failproofai config`
+so the key does not appear in command history.
 
 ---
 
@@ -157,8 +175,8 @@ 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.
+These policies protect files, credentials, infrastructure, databases, and agent
+workflows. Exact enforcement support varies by harness and event.
 
 → [All 39 built-in policies](https://docs.befailproof.ai/policies/builtin)
 
@@ -195,6 +213,33 @@ Three decisions available to every policy:
 
 ---
 
+## Policy packs
+
+A policy pack is a versioned set of policies published from a public GitHub
+repository. Inspect one before installing it:
+
+```sh
+failproofai policies show FailproofAI/policies
+failproofai policies add FailproofAI/policies
+```
+
+Anything with a slash is a pack source; anything without one is a policy name.
+You can install selected categories or policies, and pin a release when needed.
+
+```sh
+failproofai policies add FailproofAI/policies --category git,database
+failproofai policies add owner/repo@a1b2c3d4e5f6
+```
+
+Browse published packs in the [Policy Hub](https://befailproof.ai/policy-hub/), or
+run `failproofai publish --init` to start your own. Observe mode lets a pack record
+what it would have done without blocking: `failproofai publish --effect observe`.
+
+→ [Policy packs](https://docs.befailproof.ai/policies/packs) ·
+[Publish a pack](https://docs.befailproof.ai/policies/publish-a-pack)
+
+---
+
 ## Observability
 
 Enforcement is one half. The other half is seeing what the agent actually did.

docs/admin/keys-and-permissions.mdx

@@ -1,74 +1,54 @@
 ---
 title: "Keys and permissions"
-description: "Create scoped API keys for machines, automation, and operators."
+description: "Create credentials for people, automation, and machines."
 icon: "key-round"
 ---
 
-API keys belong to an organization and carry explicit permissions. Use separate keys for agent ingestion, policy delivery, evaluators, CI automation, and administrative scripts.
+Use a separate key for each person, machine, or automation job. Grant only the permissions it needs.
 
 ## Create and rotate a key
 
-<Tabs>
-  <Tab title="Dashboard">
-    1. Go to **Administration → Keys**, select **new key**, and enter a workload name.
-    2. Choose a permission set and adjust individual permissions only when the preset is insufficient.
-    3. Create the key and copy its one-time secret immediately.
-    4. Open the key later to update grants, disable it, or regenerate the secret.
+Use **Admin → Keys**, or the Cloud CLI:
 
-    The creation drawer is where you choose the narrowest grants required by the workload.
+```bash
+fp keys list
+fp keys create "audit automation" --add audits:read
+fp keys disable "audit automation"
+```
 
-    ![The new API key drawer with permission presets and individual grants.](/images/dashboard/key-create.png)
+Store the secret when it is created; it is not shown again. Rotate by creating a replacement, updating the consumer, then disabling the old key.
 
-    After creation, the Keys page shows the persistent metadata and management actions. The one-time secret is not shown again.
+## Machine keys
 
-    ![The API Keys page showing key permissions, creation time, and regenerate and disable actions.](/images/dashboard/api-keys.png)
+A machine key connects the local service to Cloud:
 
-    Use this list to review grants regularly and disable keys that no longer map to an active workload.
-  </Tab>
-  <Tab title="CLI">
-    ```bash
-    fp keys create production-agents \
-      --add events:add \
-      --add policies:pull
-    fp keys show production-agents
-    fp keys update production-agents --add events:read
-    fp keys regenerate production-agents --yes
-    fp keys disable production-agents
-    ```
+```bash
+export FAILPROOFAI_CLOUD_TOKEN="<key>"
+failproofai config
+```
 
-    Redirect or capture create/regenerate output securely; the secret is returned once.
-  </Tab>
-</Tabs>
+A connected machine may need two capabilities:
 
-The two permissions required by a connected Failproof AI machine are independent:
+- `policies:pull` to receive Cloud-managed policies.
+- `events:add` to send decisions and sessions.
 
-- `events:add` sends events and session data.
-- `policies:pull` retrieves assigned policy deployments.
+Status reports these separately because one may work while the other does not.
 
-Key secrets are shown when created or regenerated. Store them in a secret manager and rotate them without reusing an operator's interactive credentials.
+## Common permissions
 
-## Permission catalog
-
-| Area | Permissions |
+| Permission | Allows |
 | --- | --- |
-| Events | `events:add`, `events:read` |
-| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` is human-session only |
-| Users | `users:create`, `users:read`, `users:update`, `users:delete` |
-| Evaluations | `evaluations:read`, `evaluations:trigger` |
-| Dashboards | `dashboards:read`, `dashboards:write`, `dashboards:delete` |
-| Queries | `queries:read`, `queries:write`, `queries:delete`, `queries:run` |
-| Assistant | `agent:use` |
-| Settings | `settings:read`, `settings:write` |
-| Alerts | `alerts:read`, `alerts:write` |
-| Issues | `issues:read`, `issues:create`, `issues:close` |
-| Audits | `audits:read`, `audits:write` |
-| Policies | `policies:read`, `policies:write`, `policies:pull` |
-| Usage | `usage:read` |
-
-`orgs:admin` is reserved for the instance operator and cannot be granted to an organization key or ordinary member. Retired `incidents:*` and `alerts:ack` tokens are accepted for compatibility and normalize to current `issues:*` permissions.
+| `events:add` | Send events |
+| `events:read` | Read events and errors |
+| `evaluations:read` | Read sessions and evaluations |
+| `audits:read` / `audits:write` | Review or manage audits |
+| `policies:read` / `policies:write` | Review or deploy policies |
+| `policies:pull` | Pull machine policy assignments |
+| `keys:create` / `keys:disable` | Create or disable keys |
+| `orgs:admin` | Instance-level organization administration; not assignable to an organization key |
 
-Builtin permission sets are `read-only`, `standard`, and `admin`. `standard` adds evaluation triggering, query execution, issue response, and assistant use to read permissions. Key creation strips human-only grants even when a permission set contains them.
+Some administrative `fp fleet` and `fp guardrails` commands require a signed-in user session rather than an API key. Their help text states this before making a request.
 
 <Warning>
-  Instance-scoped keys can select an organization with the `X-AgentEye-Org` header. Set it explicitly on multi-organization deployments; omission may select the default organization.
+  Never reuse ingest credentials such as `AGENTEYE_KEY` or `AGENTEYE_API_KEY` as an `FP_API_KEY`. They serve different systems and permissions.
 </Warning>