Document the Experiment onboarding lifecycle

README.md

@@ -112,6 +112,21 @@ injected into workloads run by Agent Lab.
 See [Architecture](docs/architecture.md) for the complete data flow, state model, configuration
 authority, and control-plane/data-plane split.
 
+## Experiments
+
+Agent Lab also has a separate v0alpha1 onboarding path for Experiments. An Experiment is authored as
+one declarative `experiment.cue` file and can enter from a closed directory, a bounded ZIP archive,
+or an exact commit in a supported public GitHub repository. Agent Lab snapshots the source,
+validates it with the pinned CUE contract, resolves every image selector to an immutable subject,
+freshly evaluates the install policy with Cedar, and, only on a permit, can retain the resulting
+evidence in a private local Agent Lab home.
+
+This path stops at onboarding evidence. It does not run Experiment content, invoke Docker, acquire
+image bytes, claim image admission, or create a workload network. Start with the
+[Experiments guide](docs/experiments.md); use [Local installation](docs/installation.md) to prepare
+the CLI and private home, and [Local image names](docs/images.md) for operator-managed image
+mappings.
+
 ## Controlled configuration
 
 The workload path exposes four primary adaptation seams, a persistence switch, and bounded
@@ -149,9 +164,10 @@ See [Development and verification](docs/development.md) and [CI gate mapping](do
 
 ## Documentation
 
-Use the [documentation map](docs/README.md) for the complete index. The three main paths are:
+Use the [documentation map](docs/README.md) for the complete index. The four main paths are:
 
 - [Operate Agent Lab](docs/operations.md)
+- [Author, check, and install Experiments](docs/experiments.md)
 - [Understand the architecture and security model](docs/architecture.md)
 - [Develop and verify the repository](docs/development.md)
 
@@ -169,6 +185,8 @@ Formal hard stops and guarantees remain in [SECURITY.md](SECURITY.md) and
   audit before relying on the same boundary.
 - Browser automation, cloud infrastructure, and production deployment are outside the current
   guarantee.
+- Experiment onboarding retains checked and authorized local evidence only. Experiment execution,
+  image acquisition and admission, start/stop, and stored-artifact uninstall are not implemented.
 
 Do not weaken containment to work around a failed command. A refusal or exit status 125 is evidence
 to diagnose, not permission to bypass the control.

docs/README.md

@@ -1,7 +1,7 @@
 # Agent Lab documentation
 
-This directory separates normal Agent Lab operation from repository development and from the formal
-security model. Use the guide that matches the job you are doing.
+This directory separates normal Agent Lab operation, Experiment onboarding, repository development,
+and the formal security model. Use the guide that matches the job you are doing.
 
 ## I want to…
 
@@ -14,12 +14,15 @@ security model. Use the guide that matches the job you are doing.
 | Permit a narrow set of outbound destinations | [Operations: egress](operations.md#enable-narrow-egress) |
 | Understand what persists and erase Agent Lab state | [Operations: state and cleanup](operations.md#state-and-cleanup) |
 | Diagnose a startup, mount, image, or network refusal | [Operations: troubleshooting](operations.md#troubleshooting) |
+| Install the local CLI and initialize a private Agent Lab home | [Local installation](installation.md) |
+| Author, check, authorize, install, or inspect an Experiment | [Experiments](experiments.md) |
+| Manage shared local image names for Experiments | [Local image names](images.md) |
 | Develop this repository | [Development and verification](development.md) |
 | Configure Claude, Codex, or Grok for repository development | [Development-agent configuration](agent-config.md) |
 | Reproduce a GitHub check locally | [CI gate mapping](ci.md) |
 | Audit the security claims and residual risks | [Security policy](../SECURITY.md) and [threat model](../THREAT_MODEL.md) |
 
-## Command map
+## Runtime and verification command map
 
 | Command | Role |
 |---|---|
@@ -38,6 +41,44 @@ The commands are not interchangeable. In particular, a successful `doctor`, Comp
 external acceptance request does not prove runtime containment. The Docker gate supplies that
 evidence.
 
+## Experiments
+
+Experiment onboarding is a separate local control-plane workflow. Read these guides in order for a
+first installation, or jump directly to the guide that owns the state you are changing:
+
+| Guide | Canonical subject |
+|---|---|
+| [Local installation](installation.md) | install the verified CLI bundle, initialize a private home, and provision pinned CUE and Cedar tools |
+| [Experiments](experiments.md) | author, check, authorize, install, and inspect one declarative Experiment |
+| [Local image names](images.md) | map an operator-owned name to an immutable OCI subject for use by Experiments |
+
+The current Experiment lifecycle stops after a permitted install stores verified onboarding
+evidence. It does not run content, invoke Docker, acquire or admit image bytes, create a network, or
+start a workload. Linux is the supported v0alpha1 host; see the Experiments guide for the
+operation-specific limits.
+
+### Experiment command map
+
+These commands use the installed `agent-lab` CLI and its explicit or configured private home. They
+are distinct from the `./scripts/agent` workload launcher above.
+
+| Command | Role |
+|---|---|
+| `agent-lab --home ABSOLUTE_HOME init` | initialize the private local control-plane home |
+| `agent-lab --home ABSOLUTE_HOME tools provision` | acquire and verify the pinned CUE and Cedar tools |
+| `agent-lab --home ABSOLUTE_HOME experiment check SOURCE` | validate and resolve one source without durable Experiment state |
+| `agent-lab --home ABSOLUTE_HOME experiment authorize install SOURCE` | preview a fresh source- and plan-bound install decision |
+| `agent-lab --home ABSOLUTE_HOME experiment install SOURCE` | freshly check and authorize, then retain a closed evidence envelope only on permit |
+| `agent-lab --home ABSOLUTE_HOME experiment inspect NAME` | verify and report one retained Experiment without repair |
+| `agent-lab --home ABSOLUTE_HOME image add NAME DIGEST_REF` | add an operator-local image-name mapping |
+| `agent-lab --home ABSOLUTE_HOME image inspect NAME` | verify and report one image-name mapping |
+| `agent-lab --home ABSOLUTE_HOME image list` | list active local image-name mappings |
+| `agent-lab --home ABSOLUTE_HOME image remove NAME --expect ENTRY_DIGEST` | compare-and-swap remove one image-name mapping |
+
+Uppercase words are syntax placeholders. `SOURCE` is a directory, `--zip ARCHIVE`, or
+`--git https://github.com/OWNER/REPOSITORY.git --commit COMMIT_ID`. The
+[Experiments guide](experiments.md#source-formats) defines each form and its bounds.
+
 ## Documentation ownership
 
 | Document | Canonical subject |
@@ -50,6 +91,9 @@ evidence.
 | [Development](development.md) | maintainer workflow and local evidence |
 | [CI](ci.md) | required GitHub checks and exact replay model |
 | [Development-agent configuration](agent-config.md) | repository agent policy and adapters |
+| [Local installation](installation.md) | verified local program bundle, private home, tools, and stored evidence layout |
+| [Experiments](experiments.md) | authored format, source intake, planning, authorization, and onboarding lifecycle |
+| [Local image names](images.md) | shared local Experiment image-name authority and mutation rules |
 
 Component READMEs document only their local implementation: