Onboarding Proof Matrix

This matrix maps the beginner onboarding claims to executable proof. The repeatable proof runner is:

pnpm proof:onboarding -- --remote-docker

For demos and local audits where live AI, documentation deployment checks, Docker, GitHub mutation, and remote worker access should not be required, use:

pnpm proof:onboarding -- --skip-ai --skip-docs

It writes command logs and a summary under:

.x4/proofs/onboarding/<timestamp>/

The focused local proof commands are:

pnpm test:onboarding
pnpm test:complex

The focused local test uses four temporary local Git repos and a local fake OpenAI-compatible endpoint for deterministic AI profile validation. The complex local proof adds a five-repo dependency mesh with Yarn, pnpm, npm, and Bun-style package-manager commands, a dashboard, public API, billing service, worker, and observability/runbook repo. The repeatable proof runner also performs a live x4 ai sandbox-plan --run smoke against the configured provider unless --skip-ai is passed. It does not require real GitHub repos, production credentials, or cloud resources.

Proven Claims

Claim	Evidence
X4 can generate a starter registry from normal repo checkouts.	x4 registry init runs against app, pnpm API, worker, and docs/manual repos; the generated registry validates and includes repo ids, package managers, setup/test/dev/preview commands, env policy, env bundle, and starter sandbox profiles.
X4 bootstrap creates a Cursor-compatible multi-repo workspace.	x4 workspace bootstrap creates .x4/context.md, .x4/workspace.yaml, .x4/workspace.lock.yaml, and .x4/x4-workspace.code-workspace; the workspace file lists all four repos.
X4's Cursor/VS Code adapter exposes the documented onboarding controls.	pnpm test:extension validates the extension manifest, X4 sidebar, command list, multi-repo source picker, generated-workspace switching, per-repo env selection, sandbox command arguments, PATH normalization, and feature workspace helpers.
X4 keeps a shared feature branch across the repo set.	The proof checks the entry repo and all attached repos are on feat/onboarding-proof.
X4 runs meaningful cross-repo validation.	The app test reads the attached API contract, worker manifest, and docs runbook; API, worker, and docs tests validate their own artifacts; x4 test --continue-on-error records passed artifacts across npm and pnpm commands.
X4 handles more complex repo interaction meshes, not only a simple app/API pair.	pnpm test:complex creates five temporary repos for a dashboard, public API, billing service, worker, and observability runbook. It verifies mixed package-manager inference (yarn, pnpm, npm, bun), bootstraps from the worker repo, keeps all repos on one branch, runs cross-repo contract checks across all five repos, starts the dashboard preview command, and verifies cleanup planning.
X4 supports one env file per repo without printing secrets.	x4 sandbox up --profile env-file --repo-env-source ... writes one runtime env file per repo for all four repos and the AI prompt includes env key names but not env values.
X4 AI setup adds value without executing unreviewed AI output.	x4 ai sandbox-plan writes a non-secret prompt that includes repo structure, contracts, jobs, and docs runbook context; x4 ai sandbox-profile validates a model proposal before writing sandboxProfiles.ai-proof into the registry.
X4 can use the configured live AI provider for sandbox planning.	pnpm proof:onboarding runs node scripts/proof-live-ai-sandbox-plan.mjs ..., which creates a disposable four-repo workspace, runs x4 ai sandbox-plan --run, verifies prompt redaction, and stores the live model response under the proof evidence directory.
The deployable documentation site is wired to GitHub Pages.	pnpm proof:onboarding runs npm run docs:build and node scripts/verify-docs-deployment.mjs, which verifies .github/workflows/deploy-documentation.yml builds documentation/, uploads documentation/build, and publishes it into X4Org/X4Org.github.io:x4/ for https://x4org.github.io/x4/.
X4 rejects AI-proposed inline secrets.	The fake model returns a profile containing OPENAI_API_KEY; x4 ai sandbox-profile refuses it and does not print the proposed value.
X4 rejects AI-proposed unusable preview routes.	The fake model returns a profile with root routePath: "/"; x4 ai sandbox-profile refuses it before writing a proposal file because sandbox preview routes must be non-root paths such as /web or /api.
X4 fails clearly when a service sandbox is requested on a host without Docker.	The proof runs x4 sandbox up --profile ai-proof --serve-preview --wait and expects the Docker Compose preflight error when Docker is unavailable.
X4 can run and inspect an AI-proposed multi-service sandbox on a Docker-capable worker.	The remote proof runner executes pnpm test:onboarding and pnpm test:complex on x4-testbox-standard-1; when Docker Compose is available, the onboarding test runs x4 sandbox up --profile ai-proof --wait, verifies app/API/worker service URLs and /health responses, verifies private preview route planning when a tailnet host is available, checks x4 sandbox status, reads Docker Compose logs, checks x4 status, and destroys the sandbox.
X4 can run a real Docker Compose sidecar lifecycle on a Docker-capable worker.	X4_RUN_DOCKER_TESTS=1 node --test --test-name-pattern "postgres-local sandbox starts" test/cli.integration.test.mjs passed on x4-testbox-standard-1, proving x4 sandbox up, Docker Compose state, x4 sandbox down, x4 sandbox logs, and x4 sandbox destroy.
X4 previews can start and stop a registry preview command.	x4 preview up --start starts the app dev server, /health responds, x4 status records the running preview, and x4 preview down stops it.

Docker-Gated Scope

Container-backed service sandboxes still need a Docker-capable host or worker. Use:

pnpm test:docker

or the repeatable remote proof runner to prove real Docker Compose startup, service readiness, logs, preview route planning, and teardown. The local onboarding proof also verifies the generated profile and Docker-less error path for hosts where Docker is not installed.