@forgezero/agent 0.1.40 → 0.1.42

package/README.md

@@ -1,472 +1,621 @@
+<!--
+  GENERATED FILE — do not edit.
+
+  Change tools/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.
+## Package overview
 
-```bash
-bun add -g @forgezero/agent      # or let `fz agent install` do it
+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. Package root: @forgezero/agent. The sections below show the actual named imports emitted by each declaration entry point; wildcard imports are intentionally not used in the documentation.
+
+```text
+bun add -g @forgezero/agent
+```
+
+## ForgeZero package family
+
+The five packages are installation boundaries. Choose a package by who installs it; choose a subpath by the capability used in that file.
+
+| package | short description | runtimes | documentation |
+|---|---|---|---|
+| @forgezero/vault | Scoped secret access with Agent, API-key and systemd-credential sources. | bun, node, workers, deno | [Open](https://www.forgezero.net/docs/vault-package) |
+| @forgezero/access | Typed route, principal, factor, RBAC and request-pipeline contracts. | bun, node, workers, deno | [Open](https://www.forgezero.net/docs/access) |
+| @forgezero/providers | Typed external providers with priority, health and classified fallback. | bun, node, workers, deno | [Open](https://www.forgezero.net/docs/providers) |
+| @forgezero/runtime | Portable runtime primitives for queries, jobs, events, schemas and finance. | bun, node | [Open](https://www.forgezero.net/docs/runtime) |
+| @forgezero/agent | Operator CLI and managed-node agent for bootstrap, deploy and lifecycle. | bun, node | [Open](https://www.forgezero.net/docs/agent) |
+
+## @forgezero/agent public imports and commands
+
+Every row links to the detailed explanation and named-import/example area below. This table and those details are generated from the package inventory and emitted declarations.
+
+| public entry | short description | runtime | details |
+|---|---|---|---|
+| fz | The operator command: keys, status, genesis, unlock, run, and agent install. | Bun/Node host | [Details + example](#fz) |
+| fz run | The fallback for software that cannot read the local socket: start a process with scoped vault values in its environment. | Bun/Node host | [Details + example](#fz-run) |
+| fz agent install | Provision the same hardened agent service locally that the platform provisions remotely. | Bun/Node host | [Details + example](#fz-agent-install) |
+| fz-agent | 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. | Bun/Node host | [Details + example](#fz-agent) |
+| fz-agent (socket) | identity, sign, attest, get, sync and held — the whole interface an application sees. | Bun/Node host | [Details + example](#fz-agent-socket) |
+| @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. | Bun/Node host | [Details + example](#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. | Bun/Node host | [Details + example](#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. | Bun/Node host | [Details + example](#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. | Bun/Node host | [Details + example](#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. | Bun/Node host | [Details + example](#forgezero-agent-ssh-listen) |
+| @forgezero/agent/ssh-server | 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. | Bun/Node host | [Details + example](#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. | Bun/Node host | [Details + example](#forgezero-agent-pipeline) |
+| @forgezero/agent/agent-heartbeat | Signed node health publication with bounded renewal and shutdown withdrawal. | Bun/Node host | [Details + example](#forgezero-agent-agent-heartbeat) |
+| @forgezero/agent/agent-update | Verified Agent update planning against the platform release coordinate. | Bun/Node host | [Details + example](#forgezero-agent-agent-update) |
+| @forgezero/agent/agent-update-helper | Root-owned fixed update operations with registry origin and integrity validation. | Bun/Node host | [Details + example](#forgezero-agent-agent-update-helper) |
+| @forgezero/agent/bootstrap | Typed one-time platform bootstrap and internal API-driven enrolled-compute activation contracts. | Bun/Node host | [Details + example](#forgezero-agent-bootstrap) |
+| @forgezero/agent/operator-bootstrap | Pinned-host operator transport that stages owner-only handoffs and invokes the same typed platform bootstrap through the caller-approved SSH agent. | Bun/Node host | [Details + example](#forgezero-agent-operator-bootstrap) |
+| @forgezero/agent/host-maintenance | Closed host maintenance plans for staging transaction rehearsal and fleet-fenced schema consolidation through fixed transient systemd units. | Bun/Node host | [Details + example](#forgezero-agent-host-maintenance) |
+| @forgezero/agent/capacity-calibration | One-time target-local safe-concurrency calibration with private evidence. | Bun/Node host | [Details + example](#forgezero-agent-capacity-calibration) |
+| @forgezero/agent/cloudflare-bootstrap | Attended two-token Cloudflare Tunnel/DNS reconciliation and per-node connector/KV runtime handoff for existing KV resources. | Bun/Node host | [Details + example](#forgezero-agent-cloudflare-bootstrap) |
+| @forgezero/agent/cloudflare-edge | Strict Cloudflare REST operations used by the attended bootstrap controller. | Bun/Node host | [Details + example](#forgezero-agent-cloudflare-edge) |
+| @forgezero/agent/mesh-connector | Fixed Cloudflare Mesh/WARP connector enrollment using only the unit-loaded connector credential. | Bun/Node host | [Details + example](#forgezero-agent-mesh-connector) |
+| @forgezero/agent/compute | Compute claim, renewal, execution and completion client contracts. | Bun/Node host | [Details + example](#forgezero-agent-compute) |
+| @forgezero/agent/credential-schema | Canonical systemd credential names and validation shared by bootstrap and services. | Bun/Node host | [Details + example](#forgezero-agent-credential-schema) |
+| @forgezero/agent/definition | Validated project deployment definition and workload profiles. | Bun/Node host | [Details + example](#forgezero-agent-definition) |
+| @forgezero/agent/deploy-file | Read and validate a checked-out .fz deployment file without executing project input. | Bun/Node host | [Details + example](#forgezero-agent-deploy-file) |
+| @forgezero/agent/metal-bootstrap | Physical-metal bootstrap planning, application and status evidence. | Bun/Node host | [Details + example](#forgezero-agent-metal-bootstrap) |
+| @forgezero/agent/metal-provision | Validated confidential guest provisioning profiles and cloud-init rendering. | Bun/Node host | [Details + example](#forgezero-agent-metal-provision) |
+| @forgezero/agent/platform-bootstrap-runtime | Pure platform bootstrap validation, render and resumable phase-state contracts. | Bun/Node host | [Details + example](#forgezero-agent-platform-bootstrap-runtime) |
+| @forgezero/agent/project-context | Project identity and repository context validation for operator and managed runs. | Bun/Node host | [Details + example](#forgezero-agent-project-context) |
+| @forgezero/agent/provisioning-pull | Signed provisioning work claim, renewal, execution and acknowledgement. | Bun/Node host | [Details + example](#forgezero-agent-provisioning-pull) |
+| @forgezero/agent/schema/deploy-v3.json | Published JSON Schema for deployment definition version 3 with exact argv execution. | Bun/Node host | [Details + example](#forgezero-agent-schema-deploy-v3-json) |
+| @forgezero/agent/software | Exact managed-software inventory, requirement and evidence contracts. | Bun/Node host | [Details + example](#forgezero-agent-software) |
+| @forgezero/agent/software-helper | Root-owned fixed installation/update boundary for declared software. | Bun/Node host | [Details + example](#forgezero-agent-software-helper) |
+| @forgezero/agent/ubuntu | Ubuntu host validation and deterministic systemd/unit rendering helpers. | Bun/Node host | [Details + example](#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. | Bun/Node host | [Details + example](#fz-agent-replica) |
+
+## Commands
+
+bun add -g @forgezero/agent — Install the version-matched fz operator CLI and fz-agent daemon.
+fz bootstrap platform remote prepare --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json — Dry-plan one pinned operator-to-guest bootstrap; add --apply only after review.
+fz bootstrap platform --help — Inspect attended platform bootstrap inputs before applying them.
+fz bootstrap metal --help — Inspect the identity-only physical provisioner bootstrap.
+fz host transactions|schema-plan|schema-apply — Plan fixed supervised database maintenance; add --apply only after reviewing the exact argv and credential names.
+fz status — Read installed service and bootstrap evidence.
+
+```text
+bun add -g @forgezero/agent
+fz bootstrap platform remote prepare --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json
+fz bootstrap platform --help
+fz bootstrap metal --help
+fz host transactions|schema-plan|schema-apply
+fz status
+```
+
+<a id="fz"></a>
+## fz
+
+The operator command: keys, status, genesis, unlock, run, and agent install. This entry requires a Bun/Node host runtime. Run the command with `--help` before applying it.
+
+```text
 fz --help
 ```
 
-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.
+## fz — Keep project truth synchronized
 
-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:
+One versioned ForgeZero manifest generates thin AI-tool adapters and CI rejects drift.
 
-```bash
-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`.
+```text
+fz project init
+fz project sync
+fz project check
+```
 
-## What changes for an application
+<a id="fz-run"></a>
+## fz run
 
-Nothing.
+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. Run the command with `--help` before applying it.
 
-```ts
-import { ForgeZero } from '@forgezero/vault';
-const fz = new ForgeZero({ project: 'altpilot', environment: 'production' });
-await fz.get('STRIPE_KEY');
+```text
+fz run --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.
+<a id="fz-agent-install"></a>
+## fz agent install
 
-## A local copy, not a cache
+Provision the same hardened agent service locally that the platform provisions remotely. This entry requires a Bun/Node host runtime. Run the command with `--help` before applying it.
 
-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 agent install --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.
+<a id="fz-agent"></a>
+## fz-agent
 
-**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.
+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. Run the command with `--help` before applying it.
 
-**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 --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.
+<a id="fz-agent-socket"></a>
+## fz-agent (socket)
 
-## Two postures, decided by the hardware
+identity, sign, attest, get, sync and held — the whole interface an application sees. This entry requires a Bun/Node host runtime. Run the command with `--help` before applying it.
 
-| | |
-|---|---|
-| `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. |
+```text
+fz-agent (socket) --help
+```
 
-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.
+## fz-agent (socket) — Outbound control boundary
 
-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.
+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.
 
-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.
+```text
+metal/compute Agent -> outbound signed HTTPS -> platform API
+application -> local Unix socket -> project-scoped Vault replica
+```
 
-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.
+<a id="forgezero-agent-migration-pull"></a>
+## @forgezero/agent/migration-pull
 
-## The socket interface
+PQ-authenticated outbound lifecycle claims with fenced renewal, awaited async execution, idempotent acknowledgement and bounded shutdown drain. The executor reports local facts only. Named value imports: pullMigrationOnce, startMigrationPull. Named type imports: MigrationAction, MigrationEvidence, MigrationEvidenceProfile, MigrationNetwork, MigrationPullOptions, MigrationPullResult, RemoteMigrationClaim. Import only the names used by this file.
 
+```text
+import { pullMigrationOnce, startMigrationPull } from '@forgezero/agent/migration-pull';
+import type { MigrationAction, MigrationEvidence, MigrationEvidenceProfile, MigrationNetwork, MigrationPullOptions, MigrationPullResult } from '@forgezero/agent/migration-pull';
+import type { RemoteMigrationClaim } from '@forgezero/agent/migration-pull';
 ```
-get        one secret
-sync       what changed since a cursor
-held       what this guest is holding, by name only
+
+<a id="forgezero-agent-lifecycle-helper"></a>
+## @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. Named value imports: DEFAULT_LIFECYCLE_HELPER_SOCKET, executeLifecycleAction, loadLifecycleProfile, requestLifecycleAction, spawnLifecycleCommand, startLifecycleHelper, validateLifecycleProfile. Named type imports: LifecycleCommandResult, LifecycleExec, LifecycleProfile. Import only the names used by this file.
+
+```text
+import { DEFAULT_LIFECYCLE_HELPER_SOCKET, executeLifecycleAction, loadLifecycleProfile, requestLifecycleAction, spawnLifecycleCommand, startLifecycleHelper } from '@forgezero/agent/lifecycle-helper';
+import { validateLifecycleProfile } from '@forgezero/agent/lifecycle-helper';
+import type { LifecycleCommandResult, LifecycleExec, LifecycleProfile } from '@forgezero/agent/lifecycle-helper';
 ```
 
-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.
+<a id="forgezero-agent-provision"></a>
+## @forgezero/agent/provision
 
-## Project context for any repository
+The install plan as data, with no transport — so `fz` running locally and the platform running over SSH provision an identical machine. Named value imports: AGENT_EGRESS_UNIT_PATH, AGENT_SOCKET_PROXY_UNIT_PATH, AGENT_SOCKET_UNIT_PATH, APPLICATION_RUNTIME_USER, CAPABILITY_CHECKS, DEFAULT_RUNNER_PUBLIC_TCP_PORTS, DEPLOYMENT_GROUP, DEPLOYMENT_RUNNER_SOCKET, DEPLOYMENT_RUNNER_UNIT_PATH, DEPLOYMENT_RUNNER_USER, ENROLMENT_UNIT_PATH, LIFECYCLE_GROUP, LIFECYCLE_HELPER_SOCKET, LIFECYCLE_HELPER_UNIT_PATH, UNIT_PATH, VAULT_GROUP, WARP_CONFIG_UNIT_PATH, WARP_SERVICE_DROP_IN_PATH, agentBackendSocketPath, agentEgressUnit, agentEnrolmentUnit, agentSocketProxyUnit, agentSocketUnit, agentUnit, agentUpdateHelperUnit, atLeast, deploymentRunnerUnit, lifecycleHelperUnit, modeFor, planProvision, reasonFor, softwareHelperUnit, warpConfigUnit, warpServiceDropIn. Named type imports: AgentMode, Capabilities, CapabilityId, CapabilityOperation, Check, DirectorySpec, FixedHostCommand, ProvisionOperation, ProvisionPlan, Step, UnitOptions. Import only the names used by this file.
 
-Conversation memory is not a project database. Initialize one vendor-neutral,
-Git-owned context and generate the small files each AI product discovers:
+```text
+import { AGENT_EGRESS_UNIT_PATH, AGENT_SOCKET_PROXY_UNIT_PATH, AGENT_SOCKET_UNIT_PATH, APPLICATION_RUNTIME_USER, CAPABILITY_CHECKS, DEFAULT_RUNNER_PUBLIC_TCP_PORTS } from '@forgezero/agent/provision';
+import { DEPLOYMENT_GROUP, DEPLOYMENT_RUNNER_SOCKET, DEPLOYMENT_RUNNER_UNIT_PATH, DEPLOYMENT_RUNNER_USER, ENROLMENT_UNIT_PATH, LIFECYCLE_GROUP } from '@forgezero/agent/provision';
+import { LIFECYCLE_HELPER_SOCKET, LIFECYCLE_HELPER_UNIT_PATH, UNIT_PATH, VAULT_GROUP, WARP_CONFIG_UNIT_PATH, WARP_SERVICE_DROP_IN_PATH } from '@forgezero/agent/provision';
+import { agentBackendSocketPath, agentEgressUnit, agentEnrolmentUnit, agentSocketProxyUnit, agentSocketUnit, agentUnit } from '@forgezero/agent/provision';
+import { agentUpdateHelperUnit, atLeast, deploymentRunnerUnit, lifecycleHelperUnit, modeFor, planProvision } from '@forgezero/agent/provision';
+import { reasonFor, softwareHelperUnit, warpConfigUnit, warpServiceDropIn } from '@forgezero/agent/provision';
+import type { AgentMode, Capabilities, CapabilityId, CapabilityOperation, Check, DirectorySpec } from '@forgezero/agent/provision';
+import type { FixedHostCommand, ProvisionOperation, ProvisionPlan, Step, UnitOptions } from '@forgezero/agent/provision';
+```
 
-```bash
-fz project init
-# edit .forgezero/project.json and create its named truth sources
-fz project sync
-fz project check
+<a id="forgezero-agent-subscribe"></a>
+## @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. Named value imports: backoffMs, subscribe. Named type imports: ChangeFrame, SocketLike, SubscribeOptions, Subscriber. Import only the names used by this file.
+
+```text
+import { backoffMs, subscribe } from '@forgezero/agent/subscribe';
+import type { ChangeFrame, SocketLike, SubscribeOptions, Subscriber } from '@forgezero/agent/subscribe';
 ```
 
-`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.
+<a id="forgezero-agent-ssh-listen"></a>
+## @forgezero/agent/ssh-listen
 
-## Browser-authorized project control
+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. Named value imports: MAX_MESSAGE_BYTES, startSshAgent. Named type imports: SshListenOptions. Import only the names used by this file.
 
-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:
+```text
+import { MAX_MESSAGE_BYTES, startSshAgent } from '@forgezero/agent/ssh-listen';
+import type { SshListenOptions } from '@forgezero/agent/ssh-listen';
+```
 
-```bash
-fz login --api https://api.forgezero.net --realm acme
-fz whoami
-fz ui routes --json
+<a id="forgezero-agent-ssh-server"></a>
+## @forgezero/agent/ssh-server
+
+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. Named value imports: MAX_MESSAGE_BYTES, SSH_AGENT_FAILURE, SSH_AGENT_IDENTITIES_ANSWER, SSH_AGENT_SIGN_RESPONSE, SSH_AGENT_SUCCESS, SshAgentError, describeIdentities, frame, handleMessage, readMessage. Named type imports: AgentBackend, AgentIdentity. Import only the names used by this file.
+
+```text
+import { MAX_MESSAGE_BYTES, SSH_AGENT_FAILURE, SSH_AGENT_IDENTITIES_ANSWER, SSH_AGENT_SIGN_RESPONSE, SSH_AGENT_SUCCESS, SshAgentError } from '@forgezero/agent/ssh-server';
+import { describeIdentities, frame, handleMessage, readMessage } from '@forgezero/agent/ssh-server';
+import type { AgentBackend, AgentIdentity } from '@forgezero/agent/ssh-server';
+```
+
+<a id="forgezero-agent-pipeline"></a>
+## @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. Named value imports: PipelineError, redact, runPipeline. Named type imports: Pipeline, PipelineStep, RunOptions, RunResult, StepOutcome, StepResult. Import only the names used by this file.
+
+```text
+import { PipelineError, redact, runPipeline } from '@forgezero/agent/pipeline';
+import type { Pipeline, PipelineStep, RunOptions, RunResult, StepOutcome, StepResult } from '@forgezero/agent/pipeline';
+```
+
+<a id="forgezero-agent-agent-heartbeat"></a>
+## @forgezero/agent/agent-heartbeat
+
+Signed node health publication with bounded renewal and shutdown withdrawal. Named value imports: heartbeatAgentOnce, observeAgentHost, startAgentHeartbeat. Named type imports: AgentHeartbeatOptions, AgentHeartbeatResponse, AgentObservation. Import only the names used by this file.
+
+```text
+import { heartbeatAgentOnce, observeAgentHost, startAgentHeartbeat } from '@forgezero/agent/agent-heartbeat';
+import type { AgentHeartbeatOptions, AgentHeartbeatResponse, AgentObservation } from '@forgezero/agent/agent-heartbeat';
+```
+
+<a id="forgezero-agent-agent-update"></a>
+## @forgezero/agent/agent-update
+
+Verified Agent update planning against the platform release coordinate. Named value imports: DEFAULT_AGENT_RELEASE_ROOT, DEFAULT_AGENT_UPDATE_SOCKET, MAX_AGENT_TARBALL_BYTES, compareVersions, restoreAgentRelease, selectAgentRelease, stageAgentRelease, validateAgentRelease. Named type imports: AgentRelease, StagedAgentRelease, UpdateCommand, UpdateCommandResult. Import only the names used by this file.
+
+```text
+import { DEFAULT_AGENT_RELEASE_ROOT, DEFAULT_AGENT_UPDATE_SOCKET, MAX_AGENT_TARBALL_BYTES, compareVersions, restoreAgentRelease, selectAgentRelease } from '@forgezero/agent/agent-update';
+import { stageAgentRelease, validateAgentRelease } from '@forgezero/agent/agent-update';
+import type { AgentRelease, StagedAgentRelease, UpdateCommand, UpdateCommandResult } from '@forgezero/agent/agent-update';
+```
+
+<a id="forgezero-agent-agent-update-helper"></a>
+## @forgezero/agent/agent-update-helper
+
+Root-owned fixed update operations with registry origin and integrity validation. Named value imports: AGENT_UPDATE_GROUP, AGENT_UPDATE_HELPER_UNIT_PATH, AGENT_UPDATE_JOURNAL, AGENT_UPDATE_RECEIPT, activateAgentRelease, probeAgentSocket, readAgentUpdateReceipt, recoverInterruptedAgentUpdate, requestAgentUpdate, startAgentUpdateHelper. Named type imports: AgentUpdateOutcome, AgentUpdateReceipt, AgentUpdateRequest, AgentUpdateResponse. Import only the names used by this file.
+
+```text
+import { AGENT_UPDATE_GROUP, AGENT_UPDATE_HELPER_UNIT_PATH, AGENT_UPDATE_JOURNAL, AGENT_UPDATE_RECEIPT, activateAgentRelease, probeAgentSocket } from '@forgezero/agent/agent-update-helper';
+import { readAgentUpdateReceipt, recoverInterruptedAgentUpdate, requestAgentUpdate, startAgentUpdateHelper } from '@forgezero/agent/agent-update-helper';
+import type { AgentUpdateOutcome, AgentUpdateReceipt, AgentUpdateRequest, AgentUpdateResponse } from '@forgezero/agent/agent-update-helper';
+```
+
+<a id="forgezero-agent-bootstrap"></a>
+## @forgezero/agent/bootstrap
+
+Typed one-time platform bootstrap and internal API-driven enrolled-compute activation contracts. Named value imports: BOOTSTRAP_STATE_PATH, PLATFORM_BOOTSTRAP_PROFILES, applyBootstrap, bootstrapIdentityDigest, bootstrapStatus, localBootstrapHost, planBootstrap, preparePlatformBootstrap, readBootstrapConfig, resolveInstalledBootstrapKind, validateBootstrapConfig. Named type imports: BootstrapConfig, BootstrapEnvironment, BootstrapHost, BootstrapPlan, BootstrapResult, BootstrapStatus, BootstrapStep, DatabaseAgencyParticipation, DatabaseBootstrapRole, EnrolledComputeActivationConfig, InstalledBootstrapKind, PlatformBootstrapConfig, PlatformBootstrapPreparation, PlatformBootstrapProfile, PlatformEnrolmentSource. Import only the names used by this file.
+
+```text
+import { BOOTSTRAP_STATE_PATH, PLATFORM_BOOTSTRAP_PROFILES, applyBootstrap, bootstrapIdentityDigest, bootstrapStatus, localBootstrapHost } from '@forgezero/agent/bootstrap';
+import { planBootstrap, preparePlatformBootstrap, readBootstrapConfig, resolveInstalledBootstrapKind, validateBootstrapConfig } from '@forgezero/agent/bootstrap';
+import type { BootstrapConfig, BootstrapEnvironment, BootstrapHost, BootstrapPlan, BootstrapResult, BootstrapStatus } from '@forgezero/agent/bootstrap';
+import type { BootstrapStep, DatabaseAgencyParticipation, DatabaseBootstrapRole, EnrolledComputeActivationConfig, InstalledBootstrapKind, PlatformBootstrapConfig } from '@forgezero/agent/bootstrap';
+import type { PlatformBootstrapPreparation, PlatformBootstrapProfile, PlatformEnrolmentSource } from '@forgezero/agent/bootstrap';
+```
+
+<a id="forgezero-agent-operator-bootstrap"></a>
+## @forgezero/agent/operator-bootstrap
+
+Pinned-host operator transport that stages owner-only handoffs and invokes the same typed platform bootstrap through the caller-approved SSH agent. Named value imports: applyOperatorMetalBootstrap, applyOperatorPlatformBootstrap, planOperatorMetalBootstrap, planOperatorPlatformBootstrap, readOperatorMetalBootstrapRequest, readOperatorPlatformBootstrapRequest. Named type imports: OperatorCommand, OperatorCommandResult, OperatorMetalBootstrapMode, OperatorMetalBootstrapPlan, OperatorMetalBootstrapRequest, OperatorPlatformBootstrapMode, OperatorPlatformBootstrapOptions, OperatorPlatformBootstrapPlan, OperatorPlatformBootstrapRequest, OperatorSshHop. Import only the names used by this file.
+
+```text
+import { applyOperatorMetalBootstrap, applyOperatorPlatformBootstrap, planOperatorMetalBootstrap, planOperatorPlatformBootstrap, readOperatorMetalBootstrapRequest, readOperatorPlatformBootstrapRequest } from '@forgezero/agent/operator-bootstrap';
+import type { OperatorCommand, OperatorCommandResult, OperatorMetalBootstrapMode, OperatorMetalBootstrapPlan, OperatorMetalBootstrapRequest, OperatorPlatformBootstrapMode } from '@forgezero/agent/operator-bootstrap';
+import type { OperatorPlatformBootstrapOptions, OperatorPlatformBootstrapPlan, OperatorPlatformBootstrapRequest, OperatorSshHop } from '@forgezero/agent/operator-bootstrap';
 ```
 
-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.
+## @forgezero/agent/operator-bootstrap — Run the same typed platform bootstrap from an operator laptop
+
+The request contains only an explicit target IP, pinned host public key/fingerprint, the caller public-key file, SSH-agent socket and a path to the reviewed platform config. Credential values stay in owner-only files, the private SSH key stays in the operator agent, and the default command is a non-contacting plan.
+
+```text
+fz bootstrap platform remote prepare \
+  --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json
+# Review, then allow the SSH-agent approval prompt:
+fz bootstrap platform remote prepare \
+  --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json --apply
+```
+
+<a id="forgezero-agent-host-maintenance"></a>
+## @forgezero/agent/host-maintenance
+
+Closed host maintenance plans for staging transaction rehearsal and fleet-fenced schema consolidation through fixed transient systemd units. Named value imports: applyHostMaintenance, planHostMaintenance. Named type imports: HostMaintenanceOperation, HostMaintenancePlan, HostMaintenanceRequest, HostMaintenanceResult, HostMaintenanceRuntime. Import only the names used by this file.
+
+```text
+import { applyHostMaintenance, planHostMaintenance } from '@forgezero/agent/host-maintenance';
+import type { HostMaintenanceOperation, HostMaintenancePlan, HostMaintenanceRequest, HostMaintenanceResult, HostMaintenanceRuntime } from '@forgezero/agent/host-maintenance';
+```
+
+## @forgezero/agent/host-maintenance — Plan a fixed supervised host operation
+
+The library discovers only a trusted blue/green slot, attaches fixed credential names and returns exact argv as reviewable data. The public fz host commands use the same operation and require root only for apply.
+
+```text
+import { planHostMaintenance } from '@forgezero/agent/host-maintenance';
+
+const plan = planHostMaintenance({ operation: 'schema-plan' });
+console.log(plan.argv);
+```
+
+<a id="forgezero-agent-capacity-calibration"></a>
+## @forgezero/agent/capacity-calibration
+
+One-time target-local safe-concurrency calibration with private evidence. Named value imports: calibrateHttpConcurrency, localCalibrationEndpoint, validateCapacityCalibrationOptions. Named type imports: CapacityCalibration, CapacityCalibrationOptions, CapacityStage, ValidatedCapacityCalibrationOptions. Import only the names used by this file.
+
+```text
+import { calibrateHttpConcurrency, localCalibrationEndpoint, validateCapacityCalibrationOptions } from '@forgezero/agent/capacity-calibration';
+import type { CapacityCalibration, CapacityCalibrationOptions, CapacityStage, ValidatedCapacityCalibrationOptions } from '@forgezero/agent/capacity-calibration';
+```
+
+<a id="forgezero-agent-cloudflare-bootstrap"></a>
+## @forgezero/agent/cloudflare-bootstrap
+
+Attended two-token Cloudflare Tunnel/DNS reconciliation and per-node connector/KV runtime handoff for existing KV resources. Named value imports: applyCloudflareBootstrap, cloudflareHostHandoffPath, finalizeCloudflareBootstrapAcceptance, planCloudflareBootstrap, readCloudflareBootstrapAcceptanceEvidence, readCloudflareBootstrapTokens, readCloudflareConnectorHandoff, readCloudflareHostHandoff, readOwnerApiToken, runAttendedCloudflareBootstrap, validateCloudflareBootstrapCoordinates, verifyCloudflareBootstrapAcceptance, writeOwnerBootstrapOutput. Named type imports: AttendedCloudflareBootstrapRequest, CloudflareBootstrapAcceptanceEvidence, CloudflareBootstrapAcceptedNode, CloudflareBootstrapCoordinates, CloudflareBootstrapDependencies, CloudflareBootstrapEvidence, CloudflareBootstrapFinalizeRequest, CloudflareBootstrapNodeCoordinates, CloudflareBootstrapOutput, CloudflareBootstrapPhaseRunner, CloudflareBootstrapPlan, CloudflareBootstrapTokenFiles, CloudflareBootstrapTokens, CloudflareConnectorHandoff, CloudflareHostHandoff, CloudflareMeshCoordinates, CloudflareRealtimeCoordinates. Import only the names used by this file.
+
+```text
+import { applyCloudflareBootstrap, cloudflareHostHandoffPath, finalizeCloudflareBootstrapAcceptance, planCloudflareBootstrap, readCloudflareBootstrapAcceptanceEvidence, readCloudflareBootstrapTokens } from '@forgezero/agent/cloudflare-bootstrap';
+import { readCloudflareConnectorHandoff, readCloudflareHostHandoff, readOwnerApiToken, runAttendedCloudflareBootstrap, validateCloudflareBootstrapCoordinates, verifyCloudflareBootstrapAcceptance } from '@forgezero/agent/cloudflare-bootstrap';
+import { writeOwnerBootstrapOutput } from '@forgezero/agent/cloudflare-bootstrap';
+import type { AttendedCloudflareBootstrapRequest, CloudflareBootstrapAcceptanceEvidence, CloudflareBootstrapAcceptedNode, CloudflareBootstrapCoordinates, CloudflareBootstrapDependencies, CloudflareBootstrapEvidence } from '@forgezero/agent/cloudflare-bootstrap';
+import type { CloudflareBootstrapFinalizeRequest, CloudflareBootstrapNodeCoordinates, CloudflareBootstrapOutput, CloudflareBootstrapPhaseRunner, CloudflareBootstrapPlan, CloudflareBootstrapTokenFiles } from '@forgezero/agent/cloudflare-bootstrap';
+import type { CloudflareBootstrapTokens, CloudflareConnectorHandoff, CloudflareHostHandoff, CloudflareMeshCoordinates, CloudflareRealtimeCoordinates } from '@forgezero/agent/cloudflare-bootstrap';
+```
+
+<a id="forgezero-agent-cloudflare-edge"></a>
+## @forgezero/agent/cloudflare-edge
+
+Strict Cloudflare REST operations used by the attended bootstrap controller. Named value imports: configureCloudflareEdge, configureCloudflareRealtimeSecrets, ensureCloudflareMeshConnector, ensureCloudflarePrivateDatabaseRoute, ensureCloudflarePrivateRoute, ensureCloudflareTunnel, ensureCloudflareWarpDatabaseInclude, ensureCloudflareWarpNetworkIncludes, removeCloudflarePrivateDatabaseRoute, removeCloudflarePrivateRoute, removeCloudflareWarpDatabaseInclude, verifyCloudflareWorkerDurableObjects. Named type imports: CloudflareDurableObjectNamespace, CloudflareEdgeConfig, CloudflareMeshConnector, CloudflarePrivateRoute, CloudflarePrivateRouteConfig, CloudflareTunnel, CloudflareWarpIncludeConfig. Import only the names used by this file.
+
+```text
+import { configureCloudflareEdge, configureCloudflareRealtimeSecrets, ensureCloudflareMeshConnector, ensureCloudflarePrivateDatabaseRoute, ensureCloudflarePrivateRoute, ensureCloudflareTunnel } from '@forgezero/agent/cloudflare-edge';
+import { ensureCloudflareWarpDatabaseInclude, ensureCloudflareWarpNetworkIncludes, removeCloudflarePrivateDatabaseRoute, removeCloudflarePrivateRoute, removeCloudflareWarpDatabaseInclude, verifyCloudflareWorkerDurableObjects } from '@forgezero/agent/cloudflare-edge';
+import type { CloudflareDurableObjectNamespace, CloudflareEdgeConfig, CloudflareMeshConnector, CloudflarePrivateRoute, CloudflarePrivateRouteConfig, CloudflareTunnel } from '@forgezero/agent/cloudflare-edge';
+import type { CloudflareWarpIncludeConfig } from '@forgezero/agent/cloudflare-edge';
+```
+
+<a id="forgezero-agent-mesh-connector"></a>
+## @forgezero/agent/mesh-connector
+
+Fixed Cloudflare Mesh/WARP connector enrollment using only the unit-loaded connector credential. Named value imports: configureMeshConnector, readMeshConnectorCredential. Named type imports: MeshConnectorCommandResult, MeshConnectorExec. Import only the names used by this file.
+
+```text
+import { configureMeshConnector, readMeshConnectorCredential } from '@forgezero/agent/mesh-connector';
+import type { MeshConnectorCommandResult, MeshConnectorExec } from '@forgezero/agent/mesh-connector';
+```
+
+<a id="forgezero-agent-compute"></a>
+## @forgezero/agent/compute
+
+Compute claim, renewal, execution and completion client contracts. Named value imports: ComputeError, deviceInUse, guestUnit, parseCensus, qemuArgv, shapeEgressCommands, shapeEgressUnitDirectives, tapFor, unitName. Named type imports: GuestSpec, RunningGuest. Import only the names used by this file.
+
+```text
+import { ComputeError, deviceInUse, guestUnit, parseCensus, qemuArgv, shapeEgressCommands } from '@forgezero/agent/compute';
+import { shapeEgressUnitDirectives, tapFor, unitName } from '@forgezero/agent/compute';
+import type { GuestSpec, RunningGuest } from '@forgezero/agent/compute';
+```
+
+<a id="forgezero-agent-credential-schema"></a>
+## @forgezero/agent/credential-schema
+
+Canonical systemd credential names and validation shared by bootstrap and services. Named value imports: AGENT_CREDENTIAL_LOCATIONS, AGENT_CREDENTIAL_POLICY, CLOUDFLARE_CREDENTIAL_NAMES, CLOUDFLARE_CREDENTIAL_SCHEMA, METAL_SYSTEMD_CREDENTIALS, credentialBinding, deploymentCredentialSchema. Named type imports: AgentCredentialLocation, DeploymentCredentialBinding, DeploymentCredentialSchema. Import only the names used by this file.
+
+```text
+import { AGENT_CREDENTIAL_LOCATIONS, AGENT_CREDENTIAL_POLICY, CLOUDFLARE_CREDENTIAL_NAMES, CLOUDFLARE_CREDENTIAL_SCHEMA, METAL_SYSTEMD_CREDENTIALS, credentialBinding } from '@forgezero/agent/credential-schema';
+import { deploymentCredentialSchema } from '@forgezero/agent/credential-schema';
+import type { AgentCredentialLocation, DeploymentCredentialBinding, DeploymentCredentialSchema } from '@forgezero/agent/credential-schema';
+```
 
-Any ordinary website operation is available to developers and AI agents through
-the same API and access matrix:
+<a id="forgezero-agent-definition"></a>
+## @forgezero/agent/definition
 
-```bash
+Validated project deployment definition and workload profiles. Named value imports: DEPLOY_SCHEMA_URL, DefinitionError, PIPELINE_VERSION, parseDeployDefinition, phasePipeline, validateDeploymentService. Named type imports: DeployDefinition, DeployStep, DeploymentPortAllocation, DeploymentService, PipelineProfile. Import only the names used by this file.
+
+```text
+import { DEPLOY_SCHEMA_URL, DefinitionError, PIPELINE_VERSION, parseDeployDefinition, phasePipeline, validateDeploymentService } from '@forgezero/agent/definition';
+import type { DeployDefinition, DeployStep, DeploymentPortAllocation, DeploymentService, PipelineProfile } from '@forgezero/agent/definition';
+```
+
+<a id="forgezero-agent-deploy-file"></a>
+## @forgezero/agent/deploy-file
+
+Read and validate a checked-out .fz deployment file without executing project input. Named value imports: DEPLOY_FILE, DEPLOY_SCHEMA_URL, DEPLOY_TODO_PREFIX, defaultDeployFile, deployDefinitionDigest, initializeDeployFile, inspectDeployFile. Named type imports: DeployFileSummary, InitializedDeployFile. Import only the names used by this file.
+
+```text
+import { DEPLOY_FILE, DEPLOY_SCHEMA_URL, DEPLOY_TODO_PREFIX, defaultDeployFile, deployDefinitionDigest, initializeDeployFile } from '@forgezero/agent/deploy-file';
+import { inspectDeployFile } from '@forgezero/agent/deploy-file';
+import type { DeployFileSummary, InitializedDeployFile } from '@forgezero/agent/deploy-file';
+```
+
+<a id="forgezero-agent-metal-bootstrap"></a>
+## @forgezero/agent/metal-bootstrap
+
+Physical-metal bootstrap planning, application and status evidence. Named value imports: METAL_BOOTSTRAP_STATE_PATH, MetalBootstrapError, applyMetalBootstrap, metalBootstrapStatus, planMetalBootstrap, readMetalBootstrapConfig, renderMetalUnits, validateMetalBootstrapConfig, validateOwnerOnlyPath. Named type imports: MetalBootstrapApplyOptions, MetalBootstrapConfig, MetalBootstrapExec, MetalBootstrapPlan, MetalBootstrapResult, MetalBootstrapStatus. Import only the names used by this file.
+
+```text
+import { METAL_BOOTSTRAP_STATE_PATH, MetalBootstrapError, applyMetalBootstrap, metalBootstrapStatus, planMetalBootstrap, readMetalBootstrapConfig } from '@forgezero/agent/metal-bootstrap';
+import { renderMetalUnits, validateMetalBootstrapConfig, validateOwnerOnlyPath } from '@forgezero/agent/metal-bootstrap';
+import type { MetalBootstrapApplyOptions, MetalBootstrapConfig, MetalBootstrapExec, MetalBootstrapPlan, MetalBootstrapResult, MetalBootstrapStatus } from '@forgezero/agent/metal-bootstrap';
+```
+
+<a id="forgezero-agent-metal-provision"></a>
+## @forgezero/agent/metal-provision
+
+Validated confidential guest provisioning profiles and cloud-init rendering. Named value imports: MetalProvisionError, allocateAddress, allocateCpuPool, cloudInit, guestBootstrapOperations, guestNameFor, macForAddress, provisionMetalGuest, removeMetalGuest, tapNameFor, validateMetalProfile. Named type imports: GuestManifest, MetalCommandResult, MetalCpuPool, MetalExec, MetalImage, MetalProvisionProfile. Import only the names used by this file.
+
+```text
+import { MetalProvisionError, allocateAddress, allocateCpuPool, cloudInit, guestBootstrapOperations, guestNameFor } from '@forgezero/agent/metal-provision';
+import { macForAddress, provisionMetalGuest, removeMetalGuest, tapNameFor, validateMetalProfile } from '@forgezero/agent/metal-provision';
+import type { GuestManifest, MetalCommandResult, MetalCpuPool, MetalExec, MetalImage, MetalProvisionProfile } from '@forgezero/agent/metal-provision';
+```
+
+<a id="forgezero-agent-platform-bootstrap-runtime"></a>
+## @forgezero/agent/platform-bootstrap-runtime
+
+Pure platform bootstrap validation, render and resumable phase-state contracts. Named value imports: activatePlatformRelease, planLocalOtlpProof, planPlatformActivation, platformApiCredentialSpecs, renderPlatformActivationFiles, renderPlatformApiUnits, renderPlatformNginx, renderPlatformSharedEnvironment, validatePlatformSharedEnvironment. Named type imports: ActivationBoundary, ApiRuntimeRenderOptions, ApiSlot, LocalOtlpProofPlan, PlatformActivationCommandResult, PlatformActivationConfig, PlatformActivationExec, PlatformBootstrapEmail, PlatformDatabaseRole, PlatformSharedEnvironment, PlatformSoftwareProfile, SystemdCredentialSpec. Import only the names used by this file.
+
+```text
+import { activatePlatformRelease, planLocalOtlpProof, planPlatformActivation, platformApiCredentialSpecs, renderPlatformActivationFiles, renderPlatformApiUnits } from '@forgezero/agent/platform-bootstrap-runtime';
+import { renderPlatformNginx, renderPlatformSharedEnvironment, validatePlatformSharedEnvironment } from '@forgezero/agent/platform-bootstrap-runtime';
+import type { ActivationBoundary, ApiRuntimeRenderOptions, ApiSlot, LocalOtlpProofPlan, PlatformActivationCommandResult, PlatformActivationConfig } from '@forgezero/agent/platform-bootstrap-runtime';
+import type { PlatformActivationExec, PlatformBootstrapEmail, PlatformDatabaseRole, PlatformSharedEnvironment, PlatformSoftwareProfile, SystemdCredentialSpec } from '@forgezero/agent/platform-bootstrap-runtime';
+```
+
+<a id="forgezero-agent-project-context"></a>
+## @forgezero/agent/project-context
+
+Project identity and repository context validation for operator and managed runs. Named value imports: PROJECT_CONTEXT_VERSION, ProjectContextError, checkProjectContext, defaultProjectContext, initializeProjectContext, parseProjectContext, projectContextFiles, renderProjectContext, syncProjectContext. Named type imports: ContextCheck, ContextFile, ProjectContextManifest, ProjectTruthSource. Import only the names used by this file.
+
+```text
+import { PROJECT_CONTEXT_VERSION, ProjectContextError, checkProjectContext, defaultProjectContext, initializeProjectContext, parseProjectContext } from '@forgezero/agent/project-context';
+import { projectContextFiles, renderProjectContext, syncProjectContext } from '@forgezero/agent/project-context';
+import type { ContextCheck, ContextFile, ProjectContextManifest, ProjectTruthSource } from '@forgezero/agent/project-context';
+```
+
+<a id="forgezero-agent-provisioning-pull"></a>
+## @forgezero/agent/provisioning-pull
+
+Signed provisioning work claim, renewal, execution and acknowledgement. Named value imports: pullProvisioningOnce, startProvisioningPull. Named type imports: CreateRemoteProvisionClaim, GuestAccess, ProvisionPullResult, ProvisionResult, ProvisionRunner, ProvisioningPullOptions, RemoteProvisionClaim. Import only the names used by this file.
+
+```text
+import { pullProvisioningOnce, startProvisioningPull } from '@forgezero/agent/provisioning-pull';
+import type { CreateRemoteProvisionClaim, GuestAccess, ProvisionPullResult, ProvisionResult, ProvisionRunner, ProvisioningPullOptions } from '@forgezero/agent/provisioning-pull';
+import type { RemoteProvisionClaim } from '@forgezero/agent/provisioning-pull';
+```
+
+<a id="forgezero-agent-schema-deploy-v3-json"></a>
+## @forgezero/agent/schema/deploy-v3.json
+
+Published JSON Schema for deployment definition version 3 with exact argv execution. This entry is JSON data rather than a JavaScript namespace.
+
+```text
+import schema from '@forgezero/agent/schema/deploy-v3.json' with { type: 'json' };
+```
+
+## @forgezero/agent/schema/deploy-v3.json — Validate a deployment definition against the published schema
+
+Definition version 3 rejects unknown fields and shell command strings; every step is a bounded exact argv vector. Credentials remain named references resolved by Vault or the same-named encrypted systemd fallback.
+
+```text
+import deploySchema from '@forgezero/agent/schema/deploy-v3.json' with { type: 'json' };
+import Ajv from 'ajv';
+
+const validate = new Ajv({ allErrors: true, strict: true }).compile(deploySchema);
+if (!validate(deploymentDefinition)) throw new Error(JSON.stringify(validate.errors));
+```
+
+<a id="forgezero-agent-software"></a>
+## @forgezero/agent/software
+
+Exact managed-software inventory, requirement and evidence contracts. Named value imports: BUN_RELEASE_SHA256, OS_CATALOG, PINNED_BUN_VERSION, SOFTWARE_CATALOG, ensureSoftwareRequirements, executeSoftwareOperation, observeSoftwareHost, validateSoftwareRequirements. Named type imports: CatalogStatus, DeploymentChannel, OsCatalogEntry, SoftwareCatalogEntry, SoftwareCommandResult, SoftwareExec, SoftwareId, SoftwareObservation, SoftwareOperation, SoftwareRequirement. Import only the names used by this file.
+
+```text
+import { BUN_RELEASE_SHA256, OS_CATALOG, PINNED_BUN_VERSION, SOFTWARE_CATALOG, ensureSoftwareRequirements, executeSoftwareOperation } from '@forgezero/agent/software';
+import { observeSoftwareHost, validateSoftwareRequirements } from '@forgezero/agent/software';
+import type { CatalogStatus, DeploymentChannel, OsCatalogEntry, SoftwareCatalogEntry, SoftwareCommandResult, SoftwareExec } from '@forgezero/agent/software';
+import type { SoftwareId, SoftwareObservation, SoftwareOperation, SoftwareRequirement } from '@forgezero/agent/software';
+```
+
+<a id="forgezero-agent-software-helper"></a>
+## @forgezero/agent/software-helper
+
+Root-owned fixed installation/update boundary for declared software. Named value imports: DEFAULT_SOFTWARE_HELPER_SOCKET, SOFTWARE_HELPER_GROUP, SOFTWARE_HELPER_UNIT_PATH, requestServiceActivation, requestSoftware, startSoftwareHelper. Named type imports: none. Import only the names used by this file.
+
+```text
+import { DEFAULT_SOFTWARE_HELPER_SOCKET, SOFTWARE_HELPER_GROUP, SOFTWARE_HELPER_UNIT_PATH, requestServiceActivation, requestSoftware, startSoftwareHelper } from '@forgezero/agent/software-helper';
+```
+
+<a id="forgezero-agent-ubuntu"></a>
+## @forgezero/agent/ubuntu
+
+Ubuntu host validation and deterministic systemd/unit rendering helpers. Named value imports: SUPPORTED_GUEST_IMAGE, assertSupportedGuestImage. Named type imports: none. Import only the names used by this file.
+
+```text
+import { SUPPORTED_GUEST_IMAGE, assertSupportedGuestImage } from '@forgezero/agent/ubuntu';
+```
+
+<a id="fz-agent-replica"></a>
+## 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. Run the command with `--help` before applying it.
+
+```text
+fz-agent (replica) --help
+```
+
+## 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
+```
+
+## One project memory for every AI tool
+
+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.
+
+```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
+```
+
+## 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 1-of-1
+fz status
+fz unlock --phrase-file /secure/offline-phrase.txt
+```
+
+## Use website operations from a project or an AI agent
+
+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