@forgezero/agent 0.1.40 → 0.1.41

package/README.md

@@ -1,472 +1,408 @@
+<!--
+  GENERATED FILE — do not edit.
+
+  Change scripts/generate-guides.ts or its typed sources, run `bun run guides`,
+  and commit the generator and rendered files together.
+-->
+
 # @forgezero/agent
 
-**`fz` controls the machine; `fz-agent` runs its managed work.**
+The node agent deploys on a compute; tenant mode also holds one complete project across environments in RAM and serves it over a group-scoped unix socket, while platform mode never duplicates the API vault.
 
-The agent keeps a project-scoped copy of your vault in RAM and answers over a
-unix socket. `@forgezero/vault` prefers that socket over an API key whenever it
-exists, so an application on a machine running the agent reads its secrets
-because of *where it is*, not because it holds something that could be stolen
-from it.
+## Global package root and supported runtimes
 
-```bash
-bun add -g @forgezero/agent      # or let `fz agent install` do it
-fz --help
+Every managed compute. It owns node identity, attestation and repository pipelines. Tenant mode additionally holds one whole project across its environments in RAM and answers over a unix socket; platform mode never replicates the API vault beside the process that already holds every unlocked realm seed. Supported runtimes: bun, node. The global base/root import is @forgezero/agent. Every public import or command is listed below; the documentation inventory is checked in both directions against package.json exports.
+
+```text
+import * as root from '@forgezero/agent';
 ```
 
-The one public package installs both commands. Keeping bootstrap and the daemon
-in one version prevents a newly installed `fz` from provisioning a different
-agent protocol. Both executable artifacts bundle their ForgeZero runtime
-dependencies, so the constrained SSH bootstrap can transfer the reviewed pair
-to a new host without relying on a checkout, `node_modules`, or a second remote
-package-resolution step. Library subpath exports remain modular packages.
+## Commands
 
-The operator command starts browser-first platform genesis, inspects status,
-wraps processes, and installs the daemon. Genesis opens the one-use founder
-invitation, waits for the new passkey account to approve this CLI through device
-authorization, then continues custody in the browser. Passkey PRF output and
-both recovery phrases never enter the terminal:
+bun add -g @forgezero/agent — Install the version-matched fz operator CLI and fz-agent daemon.
+fz bootstrap platform --help — Inspect attended platform bootstrap inputs before applying them.
+fz bootstrap tenant --help — Inspect tenant enrolment/bootstrap inputs.
+fz status — Read installed service and bootstrap evidence.
 
-```bash
+```text
+bun add -g @forgezero/agent
+fz bootstrap platform --help
+fz bootstrap tenant --help
 fz status
-fz genesis --mode 2-of-3 --api https://api.example --app https://console.example
-fz unlock --phrase-file /secure/offline-phrase.txt # run once per participating custodian
-```
-
-Install the service explicitly:
-
-```bash
-fz agent install --apply         # writes a hardened systemd unit
-```
-
-## Host bootstrap
-
-The package is also the host installer. There is no separate shell setup
-script and no second implementation for tenant or platform machines:
-
-```bash
-fz bootstrap platform                         # interactive plan, no mutation
-sudo fz bootstrap platform prepare --bootstrap-config ./platform.json --apply
-# Register the printed read-only deploy key. For genesis, run --apply on all
-# three Agency members concurrently; later agency:none joiners run alone.
-sudo fz bootstrap platform --bootstrap-config ./platform.json --apply
-sudo fz bootstrap tenant --bootstrap-config ./tenant.json --apply
-sudo fz bootstrap metal --bootstrap-config ./metal.json --apply
-sudo fz bootstrap status
-sudo fz bootstrap repair --bootstrap-config ./original.json --apply
-```
-
-Interactive bootstrap prompts only for missing typed inputs and validates every
-answer before it changes the host. It must then render a secret-free plan, apply
-idempotently, and verify the external and local result. Initial platform bring-up
-has exactly three attended owner gates:
-
-1. SMTP host, port, sender, optional user, and an owner-only password file; the
-   resulting provider must pass its configured health/send acceptance.
-2. The separate Cloudflare phase consumes owner-only management and KV-runtime
-   token files, reconciles Tunnel/hostname state, and emits the node handoff; the
-   normal API/Agent never receives the management token.
-3. `prepare` prints that machine's read-only Git deploy public key. The owner adds
-   it to the repository and confirms completion; bootstrap then proves repository
-   access before the first deployment.
-
-Browser authentication is deliberately not automated away. If npm or another
-provider prints an authentication URL, leave the command attached to its TTY,
-open the URL, complete the passkey flow, and let the same command continue.
-
-Platform database participation is explicit in the private JSON configuration.
-The three genesis nodes use `database.agency: "member"`; later DB+API joiners
-normally use `database.agency: "none"`, which starts a Coordinator and DBServer
-without adding a fourth Agency member. Enrolment is likewise explicit:
-`enrolment.source: "genesis-derived"` only for the offline genesis fleet, or
-`"api-token"` with `tokenFile` for every API-authorized later node. No behavior
-is inferred from a hostname or numeric suffix.
-
-Repair is not a second installation path: the CLI detects the installed
-platform/tenant or metal state and dispatches to that profile's validator. It
-fails closed if both state formats are present or neither is present. A private
-intent journal binds an interrupted first apply, and later repair refuses a
-config whose immutable host identity differs from the installed profile. Status checks the persisted
-identity record, both Agent sockets, profile-owned systemd units and, for a
-platform host, the active API health endpoint, nginx configuration and live
-Coordinator-mode evidence.
-
-Platform bootstrap supports an elastic Community ArangoDB 3.11.14 fleet. The
-first three database-capable computes establish the writable cluster; later
-database joiners and API-only computes use the same command with their typed
-profile and an API-issued one-time enrolment file. Nothing treats three as a
-maximum.
-
-After genesis, a tenant can designate an enrolled compute as a bootstrap
-runner. The API creates a project-bound, expiring job containing only public
-SSH coordinates and a pinned Ed25519 host-key fingerprint. The runner claims it
-with its hybrid node identity, reads its SSH key only from a local systemd
-credential, pins one vetted DNS answer, transfers this packaged CLI, and runs
-the same `fz bootstrap tenant` flow on the target. Claim renewal, completion,
-retry and cancellation are fenced in the compute aggregate; the API never
-stores the SSH private key or a plaintext enrolment token.
-
-The attended Cloudflare resource phase is part of the same published command,
-but remains separate from the root host install so its management token never
-enters the API or Agent service environment:
-
-```bash
-chmod 600 cloudflare-bootstrap.json cloudflare-management.token cloudflare-runtime-kv.token
-fz bootstrap platform cloudflare --bootstrap-config ./cloudflare-bootstrap.json
-fz bootstrap platform cloudflare --bootstrap-config ./cloudflare-bootstrap.json --apply
-# After every host is bootstrapped and publishing healthy KV state:
-fz bootstrap platform cloudflare verify --bootstrap-config ./cloudflare-handoff.json
-```
-
-Tenant-owned public origins use the identical reviewed request and handoff with
-`fz bootstrap tenant cloudflare ...`; `fz bootstrap tenant` consumes only that
-tenant node's handoff. Both host kinds seal the connector and supplied KV token
-and can repair after the plaintext handoff has been removed.
-
-The reviewed JSON has `format: 1`, kind
-`forgezero-cloudflare-bootstrap-request`, a `checkpointPath`, the typed
-`coordinates`, and token **file paths only**. The recommended token split is:
-
-```json
-{
-  "format": 1,
-  "kind": "forgezero-cloudflare-bootstrap-request",
-  "checkpointPath": "./cloudflare-handoff.json",
-  "coordinates": {
-    "accountId": "0123456789abcdef0123456789abcdef",
-    "zoneId": "0123456789abcdef0123456789abcdef",
-    "hostname": "dev-api-n1.example.com",
-    "service": "http://127.0.0.1:3000",
-    "tunnelName": "dev-api-n1",
-    "kvNamespaceId": "0123456789abcdef0123456789abcdef",
-    "nodes": [
-      {
-        "nodeName": "dev-api-n1",
-        "hostname": "dev-api-n1.example.com",
-        "service": "http://127.0.0.1:3000",
-        "tunnelName": "dev-api-n1"
-      }
-    ]
-  },
-  "tokenFiles": {
-    "managementApiTokenFile": "./cloudflare-management.token",
-    "runtimeApiTokenFile": "./cloudflare-runtime-kv.token"
-  }
-}
-```
-
-The management token has exact-account **Cloudflare Tunnel Write** and
-exact-zone **DNS Write**. The runtime token has exact-account **Workers KV
-Storage Write**. Apply creates or adopts one remotely managed Tunnel per node,
-checkpoints its connector token, configures the public-hostname ingress, and
-reconciles the exact proxied CNAME. DNS reconciliation lists the hostname
-without a type filter: it updates one existing CNAME, creates only when absent,
-and refuses ambiguity or an incompatible A/AAAA/other owner before changing
-Tunnel ingress. It does not create a Worker, KV namespace, Access application,
-Access service token, or Cloudflare API token.
-
-The Worker and its KV/DO bindings are deployed separately through Cloudflare's
-Git integration. Durable Objects are reached through the Worker's binding, not
-with a Cloudflare REST token. The complete 0600 checkpoint stays on the
-operator machine; `<checkpoint>.hosts/<node>.json` contains only that node's
-connector plus the supplied KV runtime token. Host bootstrap seals them as the
-`cloudflared-token` and `cloudflare-kv-token` systemd credentials and removes
-the plaintext node handoff. The API resolves `cloudflare.kvApiToken` from the
-platform Vault first and falls back to the same systemd credential while the
-Vault is locked or unavailable. Management credentials are never persisted or
-loaded into the API/Agent service.
-
-Platform and tenant bootstrap configs may declare a bounded
-`deploymentCredentials` map from the exact pipeline secret name to its
-encrypted `.cred` source, for example
-`{"SMTP_PASSWORD":"/etc/forgezero/creds/SMTP_PASSWORD.cred"}`. The supervised
-Agent loads only those named credentials. A deployment asks for the same name;
-the Agent reads its project-scoped in-memory Vault replica first and uses the
-same-name systemd credential only until the replica can supply it. There is no
-directory scan, cross-project lookup, or differently named fallback.
-
-This is a versioned runtime schema, not a naming convention. The enrolled
-binding supplies the exact project and environment; `credential-schema.ts`
-maps a requested name to that environment's Vault cache coordinate. Platform
-and tenant computes use this Vault-first policy. Physical metal has no project
-Vault and loads only its fixed `metal-agent-seed` systemd credential. Attended
-operator Cloudflare/bootstrap tokens are owner-only input files and are never a
-runtime fallback. The schema is exported as `@forgezero/agent/credential-schema`.
+```
 
-## What changes for an application
+## fz
 
-Nothing.
+The operator command: keys, status, genesis, unlock, run, and agent install. This entry requires a Bun/Node host runtime.
 
-```ts
-import { ForgeZero } from '@forgezero/vault';
-const fz = new ForgeZero({ project: 'altpilot', environment: 'production' });
-await fz.get('STRIPE_KEY');
+```text
+fz --help
 ```
 
-With no agent, that needs `FORGEZERO_API_KEY` in the environment. With the
-agent, it does not — and the key that would have been in the environment does
-not exist on the box.
+## fz run
 
-## A local copy, not a cache
+The fallback for software that cannot read the local socket: start a process with scoped vault values in its environment. This entry requires a Bun/Node host runtime.
 
-The agent holds the **whole assigned project across every environment**, not
-just what has already been read. Each application still selects one environment
-and cannot cross the enrolled project boundary. That is the difference between surviving an outage and not: a
-cache only has what you fetched, so a secret you have never read is exactly the
-one you cannot get when the platform is unreachable.
+```text
+fz run --help
+```
 
-The cost, stated rather than buried: a compromised guest exposes everything in
-scope rather than only what was read. It is bounded by the scope the compute is
-assigned to, and by SEV-SNP keeping the host out of guest memory.
+## fz agent install
 
-**Never on disk.** A cache file would hand an attacker with filesystem access
-every secret this guest has ever held — the exact artefact the design exists to
-remove. A restart re-fetches.
+Provision the same hardened agent service locally that the platform provisions remotely. This entry requires a Bun/Node host runtime.
 
-**Invalidated by cursor, not by a timer.** A TTL alone means a rotated secret
-keeps working for the length of the TTL, which is the window rotation exists to
-close. The agent polls a change cursor and drops what moved.
+```text
+fz agent install --help
+```
 
-**A stale read is refused, not served.** If sync has not succeeded within the
-staleness bound, `get` fails rather than returning a value it can no longer
-vouch for. An application that receives a revoked credential and succeeds with
-it is worse off than one that receives an error — the error is visible.
+## fz-agent
 
-## Two postures, decided by the hardware
+The service entry point. Identity and private Git material arrive only as systemd credentials. A platform bootstrap may use a statically configured local control socket; an enrolled tenant guest instead builds each deployment manager from the signed server claim and reads all commands from the checked-out .fz definition. Tenant cache scope and live attestation still need to be constructed from enrolment. This entry requires a Bun/Node host runtime.
+
+```text
+fz-agent --help
+```
+
+## fz-agent (socket)
+
+identity, sign, attest, get, sync and held — the whole interface an application sees. This entry requires a Bun/Node host runtime.
+
+```text
+fz-agent (socket) --help
+```
+
+## @forgezero/agent/migration-pull
+
+PQ-authenticated outbound lifecycle claims with fenced renewal, awaited async execution, idempotent acknowledgement and bounded shutdown drain. The executor reports local facts only.
+
+```text
+import * as api from '@forgezero/agent/migration-pull';
+```
+
+## @forgezero/agent/lifecycle-helper
+
+The root-owned fixed-operation boundary for migration work. Signed controller claims can request only private reachability probes, local health checks, or stops of units named in a root-owned profile; they cannot carry commands.
+
+```text
+import * as api from '@forgezero/agent/lifecycle-helper';
+```
+
+## @forgezero/agent/provision
+
+The install plan as data, with no transport — so `fz` running locally and the platform running over SSH provision an identical machine.
+
+```text
+import * as api from '@forgezero/agent/provision';
+```
+
+## @forgezero/agent/subscribe
+
+Realtime scope sync over a WebSocket, with the poll kept underneath it: the poll is what establishes freshness, and a change it finds that the socket never sent is proof the socket is lying.
+
+```text
+import * as api from '@forgezero/agent/subscribe';
+```
+
+## @forgezero/agent/ssh-listen
+
+The socket SSH_AUTH_SOCK points at. The protocol handler had nowhere to speak — an agent protocol with no socket is a parser. The containing directory is 0700 before anything binds, because the socket’s own mode is only corrected after it already exists.
+
+```text
+import * as api from '@forgezero/agent/ssh-listen';
+```
+
+## @forgezero/agent/ssh-server
 
-| | |
-|---|---|
-| `attested` | SEV-SNP guest. The credential is a hardware report, and the platform can refuse a node whose measurement is wrong. |
-| `enrolled` | No SNP. The credential is the enrolment token plus a hybrid Ed25519 + ML-DSA-65 signature. |
+Serve the SSH agent protocol so SSH_AUTH_SOCK points at the vault — two operations implemented, and ADD_IDENTITY refused so no process can inject a key ssh would offer to every host.
 
-Both are real. `enrolled` is still strictly better than an API key in the
-application: the key never leaves the agent, rotation reaches every process, and
-the socket is filesystem-scoped. The socket is mode `0660` under the dedicated
-`forgezero-vault` group; add only the intended application service account to
-that group. The credential-free deployment runner is not a member.
+```text
+import * as api from '@forgezero/agent/ssh-server';
+```
+
+## @forgezero/agent/pipeline
+
+CI/CD on the compute: secrets reach the step that named them and nothing else, attestation gates the run, and a required attestation that fails is a refusal rather than a downgrade.
+
+```text
+import * as api from '@forgezero/agent/pipeline';
+```
+
+## @forgezero/agent/agent-heartbeat
+
+Signed node health publication with bounded renewal and shutdown withdrawal.
+
+```text
+import * as api from '@forgezero/agent/agent-heartbeat';
+```
+
+## @forgezero/agent/agent-update
+
+Verified Agent update planning against the platform release coordinate.
+
+```text
+import * as api from '@forgezero/agent/agent-update';
+```
+
+## @forgezero/agent/agent-update-helper
+
+Root-owned fixed update operations with registry origin and integrity validation.
+
+```text
+import * as api from '@forgezero/agent/agent-update-helper';
+```
+
+## @forgezero/agent/bootstrap
+
+Typed platform and tenant bootstrap planning, application and status contracts.
+
+```text
+import * as api from '@forgezero/agent/bootstrap';
+```
 
-The attested posture is the intended production upgrade, not current live
-evidence: report acquisition and AMD-rooted measurement verification still have
-to cross the production fleet. Until then the node is honestly `enrolled`; the
-Agent never manufactures an attestation-shaped fallback.
+## @forgezero/agent/capacity-calibration
 
-Every Agent request uses the same hybrid signature codec as an external API key
-and signs its one-use hybrid ML-KEM-768 + X25519 response key. Vault replication,
-deployment claims, attestation and metal provisioning responses are AES-256-GCM
-sealed to that request before crossing the edge; there is no Ed25519-only or
-successful plaintext-response downgrade.
+One-time target-local safe-concurrency calibration with private evidence.
 
-The first guest enrolment uses the same contract before the identity exists in
-the database: the guest signs the exact token and public-key body with both keys
-it is asking the API to admit, and it accepts only an ML-KEM-sealed
-acknowledgement. The short-lived token is therefore not an unsigned Agent path.
+```text
+import * as api from '@forgezero/agent/capacity-calibration';
+```
+
+## @forgezero/agent/cloudflare-bootstrap
 
-## The socket interface
+Attended Cloudflare Tunnel, KV and runtime-token bootstrap with private resumable handoff.
 
+```text
+import * as api from '@forgezero/agent/cloudflare-bootstrap';
 ```
-get        one secret
-sync       what changed since a cursor
-held       what this guest is holding, by name only
+
+## @forgezero/agent/cloudflare-edge
+
+Strict Cloudflare REST operations used by the attended bootstrap controller.
+
+```text
+import * as api from '@forgezero/agent/cloudflare-edge';
 ```
 
-The application Vault socket never accepts identity, signing, attestation,
-commands or deployment definitions. The Agent signs and attests only inside its
-own outbound clients. Otherwise a compromised application could ask for a valid
-node signature over a deployment or whole-project sync request and impersonate
-the Agent without ever extracting its key. Deployment enters through the
-root-only control socket or signed outbound claim path, then the deployment
-manager validates the checked-in definition and submits it to the common keyed
-queue.
+## @forgezero/agent/compute
+
+Compute claim, renewal, execution and completion client contracts.
 
-## Project context for any repository
+```text
+import * as api from '@forgezero/agent/compute';
+```
+
+## @forgezero/agent/credential-schema
+
+Canonical systemd credential names and validation shared by bootstrap and services.
+
+```text
+import * as api from '@forgezero/agent/credential-schema';
+```
 
-Conversation memory is not a project database. Initialize one vendor-neutral,
-Git-owned context and generate the small files each AI product discovers:
+## @forgezero/agent/definition
 
-```bash
+Validated project deployment definition and workload profiles.
+
+```text
+import * as api from '@forgezero/agent/definition';
+```
+
+## @forgezero/agent/deploy-file
+
+Read and validate a checked-out .fz deployment file without executing project input.
+
+```text
+import * as api from '@forgezero/agent/deploy-file';
+```
+
+## @forgezero/agent/metal-bootstrap
+
+Physical-metal bootstrap planning, application and status evidence.
+
+```text
+import * as api from '@forgezero/agent/metal-bootstrap';
+```
+
+## @forgezero/agent/metal-provision
+
+Validated confidential guest provisioning profiles and cloud-init rendering.
+
+```text
+import * as api from '@forgezero/agent/metal-provision';
+```
+
+## @forgezero/agent/platform-bootstrap-runtime
+
+Pure platform bootstrap validation, render and resumable phase-state contracts.
+
+```text
+import * as api from '@forgezero/agent/platform-bootstrap-runtime';
+```
+
+## @forgezero/agent/project-context
+
+Project identity and repository context validation for operator and managed runs.
+
+```text
+import * as api from '@forgezero/agent/project-context';
+```
+
+## @forgezero/agent/provisioning-pull
+
+Signed provisioning work claim, renewal, execution and acknowledgement.
+
+```text
+import * as api from '@forgezero/agent/provisioning-pull';
+```
+
+## @forgezero/agent/schema/deploy-v2.json
+
+Published JSON Schema for deployment definition version 2.
+
+```text
+import * as api from '@forgezero/agent/schema/deploy-v2.json';
+```
+
+## @forgezero/agent/software
+
+Exact managed-software inventory, requirement and evidence contracts.
+
+```text
+import * as api from '@forgezero/agent/software';
+```
+
+## @forgezero/agent/software-helper
+
+Root-owned fixed installation/update boundary for declared software.
+
+```text
+import * as api from '@forgezero/agent/software-helper';
+```
+
+## @forgezero/agent/ubuntu
+
+Ubuntu host validation and deterministic systemd/unit rendering helpers.
+
+```text
+import * as api from '@forgezero/agent/ubuntu';
+```
+
+## fz-agent (replica)
+
+The project-scoped vault replica: resident in RAM, never on disk, invalidated by cursor rather than by timer, and refusing a read it can no longer vouch for.
+
+```text
+fz-agent (replica) --help
+```
+
+## Outbound control boundary
+
+The Metal Agent initiates outbound signed HTTPS for orchestration. Applications use the project-scoped local Unix socket; the platform never opens an inbound shell control plane.
+
+```text
+metal/compute Agent -> outbound signed HTTPS -> platform API
+application -> local Unix socket -> project-scoped Vault replica
+```
+
+## Keep project truth synchronized
+
+One versioned ForgeZero manifest generates thin AI-tool adapters and CI rejects drift.
+
+```text
 fz project init
-# edit .forgezero/project.json and create its named truth sources
 fz project sync
 fz project check
 ```
 
-`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot instructions and the Cursor rule
-are generated adapters. They contain no independent architecture or progress.
-`fz project check` fails when a truth source is missing or an adapter was edited
-by hand. Tools and skills remain optional execution aids; accepted decisions and
-status live in the repository and therefore survive switching AI agents.
+## Install both machine commands
+
+One public package installs `fz` and `fz-agent` at the same version. `fz` breaks the bootstrap circle from an operator machine; `fz-agent` runs managed work. Keeping them together prevents a new bootstrap command from provisioning an old daemon protocol.
+
+```text
+bun add -g @forgezero/agent
+fz --help
+fz-agent --help
+```
 
-## Browser-authorized project control
+## One project memory for every AI tool
 
-Sign in from any checkout with the public CLI. The terminal displays a device
-code and the browser approves it in the selected tenant realm:
+Conversation memory and dated audits are observations, not architecture. `fz project init` creates one strict, vendor-neutral manifest in Git; `sync` renders only the thin discovery files Claude, Codex, Gemini, Copilot and Cursor expect, and `check` fails if a named truth source disappeared or an adapter was edited independently. Teams can switch tools without restating the project and without maintaining five competing plans.
 
-```bash
-fz login --api https://api.forgezero.net --realm acme
-fz whoami
-fz ui routes --json
+```text
+fz project init          # creates .forgezero/project.json
+# edit the manifest and its named truth sources
+fz project sync          # generate vendor adapters
+fz project check         # CI/handoff drift gate
 ```
 
-The short session is stored by API origin and realm in an owner-only local file.
-It is never committed to `.fz/config.json`. A protected mutation opens a browser
-page for passkey or TOTP proof and then replays the exact request once; the CLI
-has no privileged server mode.
+## Genesis is browser-first; recovery can remain headless
+
+The CLI starts device authorization before the founder exists and opens the one-use invitation created by `fz bootstrap platform`. The browser creates the account, registers and freshly proves its passkey, confirms the account recovery phrase, then explicitly approves the displayed terminal code and continues to custody. The CLI receives only a bounded session. Custody phrases and passkey PRF output remain in the browser. After restart, each participating custodian opens only their own phrase envelope using an owner-only phrase file or stdin and contributes the share from their own authenticated, freshly proved session. No CLI process collects several custodians’ phrases. SSH remains transport and Git interoperability only; it is not a ForgeZero authentication or custody factor. Neither path creates a privileged server bypass.
+
+```text
+fz genesis --mode 2-of-3 --api https://api.example --app https://console.example
+fz status
+fz unlock --phrase-file /secure/offline-phrase.txt
+```
 
-Any ordinary website operation is available to developers and AI agents through
-the same API and access matrix:
+## Use website operations from a project or an AI agent
 
-```bash
+Every UI operation is an API operation. `fz ui routes --json` discovers the exact actions allowed by the signed-in account’s current realm, lifecycle stage and grants from the API’s enforced matrix, so the CLI and AI agents carry no copied route list. `fz api` (also `fz ui`) executes authenticated JSON GET, POST, PUT, PATCH and DELETE without requiring a browser visit for ordinary work. Paths are forced onto the signed-in origin, query values are repeatable, bodies can be inline, stdin or a file, and server grants plus fresh-proof rules remain authoritative. `fz project init|sync|check` separately gives AI tools one Git-persisted project memory.
+
+```text
+fz ui routes --json
 fz ui routes pipeline
 fz ui get /workspace/pipelines --query projectKey=my-project
-fz api post /workspace/pipelines/status \
-  --data '{"pipelineKey":"pl_…","enabled":false}'
+fz api post /workspace/pipelines/status --data '{"pipelineKey":"pl_…","enabled":false}'
 generate-request | fz api post /workspace/action --data -
 ```
 
-Only realm-relative paths are accepted, so the saved session cannot be forwarded
-to another origin. Inline JSON, stdin and JSON files are supported. Use
-`fz logout` to revoke the remote session and remove the local copy.
-
-`fz ui routes --json` reads the action catalog from the API's enforced access
-matrix. It lists only the current account's current realm, stage and grants, so
-developers and AI agents can discover the available control surface without a
-copied CLI command list or a visit to the website. Execute any listed action
-with `fz ui <method> <path>`; sensitive actions open the same fresh-proof flow
-as the website and replay the exact request once.
-
-## Deployment definitions
-
-A repository may commit `.fz/deploy.json` with its own profiles, prerequisite
-checks, commands, and the exact secret names each step needs. ForgeZero does not
-choose a tenant's database, framework, or deploy shape. The agent validates the
-file before executing any command, prepares only the selected profile, and gives a
-step only the vault values it explicitly names. `await` returns the complete
-pipeline result; no polling service or persistent queue is required.
-
-Create and validate that file with the same public package that executes it:
-
-```bash
-fz deploy catalog --channel production
-fz deploy init --profile app --software bun@1.3.14
-# Replace the explicit safe blockers with this project's release and health commands.
-fz deploy check
-fz deploy sync
-```
-
-After sign-in, create and operate the durable pipeline from the same checkout.
-The project defaults to `.fz/config.json`; compute/profile attachments remain
-control-plane state rather than fields in the deploy file:
-
-```bash
-fz deploy connect --provider github --repository acme/web \
-  --clone-url https://github.com/acme/web.git --auth public \
-  --target compute-eu@api --target compute-us@api
-fz deploy list
-fz deploy runs --pipeline <pipeline-key>
-fz deploy release --pipeline <pipeline-key> \
-  --revision <full-40-character-commit> --wait
-```
-
-`init` refuses to invent a generic release or health check: both generated steps
-exit non-zero until the project replaces them. `check` validates the published
-v2 schema and active software coordinates, then prints a formatting-independent
-semantic SHA-256 digest. The schema ships at
-`@forgezero/agent/schema/deploy-v2.json` and is served from
-`https://www.forgezero.net/schemas/deploy-v2.json`.
-
-Git is the only local-to-live synchronization mechanism. `sync` validates and
-prints that rule; it does not create a second mutable command copy in the API.
-The verified webhook identifies one exact commit, and a successful Agent result
-persists the definition digest so the Applications screen can prove which local
-contract became live.
-
-Catalog status is an admission boundary, not a suggestion. `testing` coordinates
-are visible in the development catalog for ForgeZero qualification but cannot be
-selected by any deploy file. A repository cannot promote software by calling
-itself development; only a reviewed catalog change to `active` unlocks it.
-
-The daemon owns source checkout and command execution. Bootstrap explicitly
-awaits release one because the API does not exist yet, then the Agent consumes a
-one-use platform enrolment capability. There is no branch watcher. Every normal
-platform or tenant release is one durable API delivery atomically expanded to
-one row for every independently attached compute target. Release-scoped steps
-run on one target elected by stable target ordering, never on a user-declared
-coordinator:
-`pending` is written before dispatch, `running` and a fenced lease before project
-code, and only an awaited successful pipeline writes `deployed`. An expired
-claim can be recovered; its stale token cannot renew or finish.
-
-Compute replacement uses the same outbound pattern through
-`@forgezero/agent/migration-pull`: claim one action for this exact compute,
-renew its fencing lease while the awaited function runs, and acknowledge the
-result before accepting more work. The public function accepts the executor as
-an async callback so an embedding Agent can keep privilege and OS policy outside
-the transport. Node evidence is deliberately local-only; it cannot claim
-Agency quorum, replication completion, seed residency, edge exclusion or
-Cloudflare route existence on behalf of the controller.
-
-The managed daemon uses `@forgezero/agent/lifecycle-helper` as that executor.
-It is a separate root service behind a group-scoped Unix socket and accepts only
-fixed lifecycle operations. Unit names and loopback health endpoints come from
-a root-owned profile; a signed claim cannot supply a command or path. For a
-cross-network database member, the common installer enrolls the headless WARP
-client from systemd credentials materialized only in `/run`. Readiness requires
-WARP to be connected and the controller-selected private peer IP and database
-port to be reachable. Database traffic is never exposed through a public IP,
-public hostname, or inbound firewall rule.
-
-The same package also runs the identity-only Metal Agent. It initiates outbound
-hybrid-signed HTTPS and requires request-bound PQ-sealed responses while pulling
-only claims assigned to its enrolled hostname, then passes
-the fixed claim over a local Unix socket to a narrowly privileged root helper.
-The helper can materialize the audited QEMU profile; it cannot clone a project,
-read Vault data, accept arbitrary commands, or retain tenant credentials. Root
-SSH is an operator-only platform recovery path, not the normal tenant
-dispatch mechanism.
-
-New guests also call this same public `fz agent install --apply --enrol` path
-from cloud-init. Metal provisioning does not carry a second handwritten Agent
-unit or deployment runner, so platform and tenant guests cannot drift at that
-foundation boundary.
-
-Shutdown has one process-wide deadline. New deployment claims and background
-sync stop first, claimed work drains under its lease fence, and only then do the
-queues and application socket close. Vault/attestation calls or a stale local
-socket cannot consume systemd's longer stop timeout: exceeding the Agent deadline
-is reported and exits non-zero instead of being silently killed midway by PID 1.
-
-Repository read authorization is explicit per pipeline: public HTTPS, the
-compute's systemd-sealed SSH deploy key, or a fine-grained HTTPS token selected
-by a project-vault secret name. A signed claim contains the mode and secret name
-only. The agent resolves the value from its scoped memory cache, limits the Git
-header to the repository origin, never writes the token into a command, and
-never exposes it to tenant pipeline steps. These provider-neutral modes are the
-complete contract; a GitHub App is not a missing dependency and would be added
-later only as an explicit provider-specific mode with expiry and revocation tests.
-
-An operator may also force a deployment and await the complete result over the
-private control socket:
-
-```bash
-fz-agent deploy --revision=<full-40-character-commit> --release-executor
-fz-agent status
-fz-agent pause
-fz-agent pause-key --key=project:production
-fz-agent stop-key --key=project:production   # running finishes; pending work is removed
-fz-agent start-key --key=project:production
-fz-agent cancel --id=q_42
-```
-
-The node seed and read-only Git private key are loaded with
-`LoadCredentialEncrypted=`. Their encrypted, host-bound blobs persist under
-`/etc/forgezero/creds`; decrypted values exist only in the service's private
-`$CREDENTIALS_DIRECTORY`. Platform bootstrap has no second clone/build path.
-Bootstrap records the forge's SSH host key during the attended access check;
-the daemon uses `StrictHostKeyChecking=yes` and never accepts a new host key by
-itself.
-
-Full documentation: **https://www.forgezero.net/docs/agent**
-
-## Licence
-
-MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
-deploys.
+## What changes for an application
+
+Nothing. With no agent, this needs FORGEZERO_API_KEY in the environment. With the agent, it does not — and the key that would have been on the box does not exist. `@forgezero/vault` prefers the socket automatically.
+
+```text
+import { ForgeZero } from '@forgezero/vault';
+
+const fz = new ForgeZero({ project: 'altpilot', environment: 'production' });
+await fz.get('STRIPE_KEY');
+```
+
+## A local copy, not a cache
+
+The agent holds the whole assigned project across all of its environments, not just what has already been read. Each application still supplies its environment and cannot cross the enrolled project boundary. That is the difference between surviving an outage and not: a read-through cache lacks the never-before-read value precisely when the platform is unreachable. The cost is that a compromised guest exposes everything in the enrolled project rather than only what was read — bounded by the project and by SEV-SNP keeping the host out of guest memory.
+
+## Local access is explicit Unix membership
+
+The socket is mode 0660 in the dedicated forgezero-vault group. A service account must be deliberately added to that group before it can read the project replica; unrelated local users and the credential-free deployment runner cannot connect. Mode 0600 would make the advertised app integration unusable, while a world-readable socket would hand the vault to every process on the guest.
+
+## Never on disk
+
+A cache file would hand an attacker with filesystem access every secret this guest has ever held, which is precisely the artefact this design exists to remove. A restart re-fetches. There is no version of "just persist it, it is encrypted" that survives the key also being on the box.
+
+## Invalidated by cursor, and refused when stale
+
+A TTL alone means a rotated secret keeps working for the length of the TTL — the window rotation exists to close. The agent polls a change cursor and drops what moved, so a rotation propagates regardless of TTL. And if sync has not succeeded within the staleness bound, a read is refused rather than served: an application that receives a revoked credential and succeeds with it is worse off than one that receives an error, because the error is visible.
+
+## Two postures, decided by the hardware
+
+An SNP guest can produce an attestation report and the platform can refuse a node whose measurement is wrong. Anything else authenticates with its enrolment token and a hybrid Ed25519 + ML-DSA-65 signature. Both are real: enrolled is still strictly better than an API key in the application, because the key never leaves the agent, rotation reaches every process, and the socket is filesystem-scoped.
+
+```text
+attested   /dev/sev-guest present  -> hardware report
+enrolled   no SNP device           -> enrolment token + hybrid signature
+```
+
+## The app socket cannot impersonate the node
+
+The group-scoped application socket exposes only replica get, held and sync operations. Node identity, hybrid signing and attestation stay inside the Agent's outbound clients. Every Agent call requires HTTPS outside loopback, signs a one-use hybrid ML-KEM-768 + X25519 recipient and refuses a successful response that is not sealed back to that request. A process allowed to read one environment therefore cannot ask the Agent to sign a deployment, heartbeat or whole-project replication request and act as the node.
+
+```text
+get        one secret in the selected environment
+sync       invalidate rotated values
+held       names held in the selected environment
+
+identity/sign/attest   refused on the application socket
+```
+
+Full rendered documentation: https://www.forgezero.net/docs/agent