Skip to content

Document the Experiment onboarding lifecycle - #42

Merged
xormania merged 1 commit into
devfrom
work/docs-experiments
Aug 2, 2026
Merged

Document the Experiment onboarding lifecycle#42
xormania merged 1 commit into
devfrom
work/docs-experiments

Conversation

@xor-machine

Copy link
Copy Markdown
Collaborator

Summary

  • make Experiments a fourth top-level Agent Lab documentation journey
  • turn the Experiment reference into an operator-facing onboarding guide with a verified walkthrough
  • separate Experiment evidence from Docker workload execution and image admission
  • make linked installation and image-catalog command examples safe syntax notation

Motivation / Context

Experiment onboarding was implemented and documented in one dense reference page, but it was absent from the public documentation map, command map, ownership table, and top-level documentation paths. Prerequisites appeared after the first commands, and the page did not clearly expose the Linux boundary, fixed unauthenticated compatibility principal, permit-only persistence, schema limits, missing lifecycle operations, or exit meanings.

This one-slice workstream makes the current v0alpha1 surface discoverable without implying that an installed Experiment is running, admitted, or ready to run.

Changes

  • add a dedicated Experiments section to the public README and documentation map
  • distinguish the installed agent-lab experiment lifecycle from the ./scripts/agent Docker workload launcher
  • add a fail-closed checkout-local walkthrough covering install, init, config verification, pinned-tool provisioning, check, authorization, permitted install, and inspect
  • organize the Experiment guide by lifecycle, schema, directory/ZIP/Git intake, image selection, stored-state limits, and result classification
  • state authorization, platform, no-runtime, no-admission, permit-only publication, retry, conflict, and cooperative-account tamper boundaries explicitly
  • convert linked installation and local-image command blocks from unsafe shell-like placeholders to labeled syntax notation

Testing

  • documented checkout-local walkthrough: passed end to end from a fresh temporary prefix and home; returned a source-bound plan, permit decision, installed receipt, and verified inspect result
  • bash tests/experiment/contract-cases.sh: SUMMARY assertions=43 expected=43 failures=0 infra=0
  • bash tests/experiment/authorization-cases.sh: SUMMARY assertions=1 expected=1 failures=0 infra=0
  • bash tests/experiment/source-adapter-cases.sh: SUMMARY assertions=83 expected=83 failures=0 infra=0
  • bash tests/experiment/local-lifecycle-cases.sh: SUMMARY assertions=133 expected=133 failures=0 infra=0
  • ./scripts/dev/check default quick: SECURITY GATE SUMMARY pass=32 fail=0 skip=0 infra=0
  • ./tools/validate.sh --strict: validate: PASS; containment lint reported 0 failures and 0 warnings
  • relative Markdown link and target check: all links in the five changed documents resolved
  • git diff --check: passed
  • slice PR Document the Experiment onboarding lifecycle #40: Fast, Static, Docker security, Analyze, CodeQL, and Required gates all passed

@xormania
xormania marked this pull request as ready for review August 2, 2026 21:11
@xormania
xormania merged commit 0514697 into dev Aug 2, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants