@forgezero/agent 0.1.41 → 0.1.43

package/README.md

@@ -1,7 +1,7 @@
 <!--
   GENERATED FILE — do not edit.
 
-  Change scripts/generate-guides.ts or its typed sources, run `bun run guides`,
+  Change tools/generate-guides.ts or its typed sources, run `bun run guides`,
   and commit the generator and rendered files together.
 -->
 
@@ -9,309 +9,522 @@
 
 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.
 
-## Global package root and supported runtimes
+## Package overview
 
-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.
+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
-import * as root from '@forgezero/agent';
+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 tenant --help — Inspect tenant enrolment/bootstrap inputs.
+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 tenant --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.
+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
 ```
 
+## fz — Keep project truth synchronized
+
+One versioned ForgeZero manifest generates thin AI-tool adapters and CI rejects drift.
+
+```text
+fz project init
+fz project sync
+fz project check
+```
+
+<a id="fz-run"></a>
 ## fz run
 
-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 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.
 
 ```text
 fz run --help
 ```
 
+<a id="fz-agent-install"></a>
 ## fz agent install
 
-Provision the same hardened agent service locally that the platform provisions remotely. This entry requires a Bun/Node host runtime.
+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.
 
 ```text
 fz agent install --help
 ```
 
+<a id="fz-agent"></a>
 ## 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. This entry requires a Bun/Node host runtime.
+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.
 
 ```text
 fz-agent --help
 ```
 
+<a id="fz-agent-socket"></a>
 ## fz-agent (socket)
 
-identity, sign, attest, get, sync and held — the whole interface an application sees. This entry requires a Bun/Node host runtime.
+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.
 
 ```text
 fz-agent (socket) --help
 ```
 
+## fz-agent (socket) — 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
+```
+
+<a id="forgezero-agent-migration-pull"></a>
 ## @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.
+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 * as api from '@forgezero/agent/migration-pull';
+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';
 ```
 
+<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.
+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 * as api from '@forgezero/agent/lifecycle-helper';
+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';
 ```
 
+<a id="forgezero-agent-provision"></a>
 ## @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.
+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.
 
 ```text
-import * as api from '@forgezero/agent/provision';
+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';
 ```
 
+<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.
+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 * as api from '@forgezero/agent/subscribe';
+import { backoffMs, subscribe } from '@forgezero/agent/subscribe';
+import type { ChangeFrame, SocketLike, SubscribeOptions, Subscriber } from '@forgezero/agent/subscribe';
 ```
 
+<a id="forgezero-agent-ssh-listen"></a>
 ## @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.
+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.
 
 ```text
-import * as api from '@forgezero/agent/ssh-listen';
+import { MAX_MESSAGE_BYTES, startSshAgent } from '@forgezero/agent/ssh-listen';
+import type { SshListenOptions } from '@forgezero/agent/ssh-listen';
 ```
 
+<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.
+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 * as api from '@forgezero/agent/ssh-server';
+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.
+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 * as api from '@forgezero/agent/pipeline';
+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.
+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 * as api from '@forgezero/agent/agent-heartbeat';
+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.
+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 * as api from '@forgezero/agent/agent-update';
+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.
+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 * as api from '@forgezero/agent/agent-update-helper';
+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 platform and tenant bootstrap planning, application and status contracts.
+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';
+```
+
+## @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 * as api from '@forgezero/agent/bootstrap';
+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.
+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 * as api from '@forgezero/agent/capacity-calibration';
+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 Cloudflare Tunnel, KV and runtime-token bootstrap with private resumable handoff.
+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 * as api from '@forgezero/agent/cloudflare-bootstrap';
+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.
+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 * as api from '@forgezero/agent/cloudflare-edge';
+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.
+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 * as api from '@forgezero/agent/compute';
+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.
+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 * as api from '@forgezero/agent/credential-schema';
+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';
 ```
 
+<a id="forgezero-agent-definition"></a>
 ## @forgezero/agent/definition
 
-Validated project deployment definition and workload profiles.
+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 * as api from '@forgezero/agent/definition';
+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.
+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 * as api from '@forgezero/agent/deploy-file';
+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.
+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 * as api from '@forgezero/agent/metal-bootstrap';
+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.
+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 * as api from '@forgezero/agent/metal-provision';
+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.
+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 * as api from '@forgezero/agent/platform-bootstrap-runtime';
+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.
+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 * as api from '@forgezero/agent/project-context';
+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.
+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 * as api from '@forgezero/agent/provisioning-pull';
+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';
 ```
 
-## @forgezero/agent/schema/deploy-v2.json
+<a id="forgezero-agent-schema-deploy-v3-json"></a>
+## @forgezero/agent/schema/deploy-v3.json
 
-Published JSON Schema for deployment definition version 2.
+Published JSON Schema for deployment definition version 3 with exact argv execution. This entry is JSON data rather than a JavaScript namespace.
 
 ```text
-import * as api from '@forgezero/agent/schema/deploy-v2.json';
+import schema from '@forgezero/agent/schema/deploy-v3.json' with { type: 'json' };
 ```
 
-## @forgezero/agent/software
+## @forgezero/agent/schema/deploy-v3.json — Validate a deployment definition against the published schema
 
-Exact managed-software inventory, requirement and evidence contracts.
+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 * as api from '@forgezero/agent/software';
-```
-
-## @forgezero/agent/software-helper
-
-Root-owned fixed installation/update boundary for declared software.
+import deploySchema from '@forgezero/agent/schema/deploy-v3.json' with { type: 'json' };
+import Ajv from 'ajv';
 
-```text
-import * as api from '@forgezero/agent/software-helper';
+const validate = new Ajv({ allErrors: true, strict: true }).compile(deploySchema);
+if (!validate(deploymentDefinition)) throw new Error(JSON.stringify(validate.errors));
 ```
 
-## @forgezero/agent/ubuntu
+<a id="forgezero-agent-software"></a>
+## @forgezero/agent/software
 
-Ubuntu host validation and deterministic systemd/unit rendering helpers.
+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 * as api from '@forgezero/agent/ubuntu';
+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';
 ```
 
-## fz-agent (replica)
+<a id="forgezero-agent-software-helper"></a>
+## @forgezero/agent/software-helper
 
-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.
+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
-fz-agent (replica) --help
+import { DEFAULT_SOFTWARE_HELPER_SOCKET, SOFTWARE_HELPER_GROUP, SOFTWARE_HELPER_UNIT_PATH, requestServiceActivation, requestSoftware, startSoftwareHelper } from '@forgezero/agent/software-helper';
 ```
 
-## Outbound control boundary
+<a id="forgezero-agent-ubuntu"></a>
+## @forgezero/agent/ubuntu
 
-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.
+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
-metal/compute Agent -> outbound signed HTTPS -> platform API
-application -> local Unix socket -> project-scoped Vault replica
+import { SUPPORTED_GUEST_IMAGE, assertSupportedGuestImage } from '@forgezero/agent/ubuntu';
 ```
 
-## Keep project truth synchronized
+<a id="fz-agent-replica"></a>
+## fz-agent (replica)
 
-One versioned ForgeZero manifest generates thin AI-tool adapters and CI rejects drift.
+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 project init
-fz project sync
-fz project check
+fz-agent (replica) --help
 ```
 
 ## Install both machine commands
@@ -340,7 +553,7 @@ fz project check         # CI/handoff drift gate
 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 genesis --mode 1-of-1
 fz status
 fz unlock --phrase-file /secure/offline-phrase.txt
 ```