Docs Pilot

Pilot Runbook

Creator Engine — Pilot Runbook (v3.1 pilot-ready)

The end-to-end pilot onboarding path: install CE, provision a repo + the GitHub App, open a governed terminal session with ce session, file work as a Scope, and get cost-safe PRs + merges on your own agent. Brand new? Begin at the Welcome / Start Here front door. Plain-language intro: understanding-ce.md. The mechanics live in the cited contracts/designs. For the shortest command sequence, see quickstart.md.

Pilot scope. The E1 one-liner now performs a real authenticated inventory bootstrap: it verifies the signed spec, installs CE into a user-local venv from hash-pinned artifacts, and runs onboard --inventory. Runtime provisioning and the interactive GitHub-App click remain later human-approved apply seams.

0. What you need

1. Install (one engine, two modes — operator-typeless)

You type nothing during setup; you approve only the remaining human seams the plan reports: the GitHub-App authorization click and, only for backends that plan privileged host dependencies, sudo. Contract: ../contracts/installer.md.

Default one-liner installs need outbound access to creator-engine.dev for the signed spec and wheelhouse artifacts, https://dns.google for the default out-of-band trust anchor (CE_TRUST_ANCHOR_URL), and github.com for the astral-sh/uv releases used to acquire the manifest-pinned uv and CPython 3.14 when the host has no local Python >=3.14. Egress-restricted environments must allow all three destinations before running the one-liner, or installation can fail non-obviously during trust verification or Python acquisition.

Both modes are the SAME journey; the only difference is where answers come from (interactive > answers-file > detected > default). You can prepare every answer upfront, IaC-style, in a committable ce-install.answers.yaml (schema: ../../schemas/install-answers.schema.yaml) — or answer interactively as each journey step batches its asks. The agent loop:

# the one-liner runs this once with verified absolute paths:
<venv>/bin/ce install --spec <verified-spec> --trust-root <verified-trust-root> --answers-schema <verified-schema> --inventory
# prepare ce-install.answers.yaml (secrets ONLY as env:// file:// prompt:// refs;
# leave host.sudo_grant empty for the solo-pilot os-native default)
ce install --spec <verified-spec> --trust-root <verified-trust-root> --answers-schema <verified-schema> --answers ce-install.answers.yaml --plan
ce install --spec <verified-spec> --trust-root <verified-trust-root> --answers-schema <verified-schema> --answers ce-install.answers.yaml --apply --non-interactive

--plan shows the full plan plus the exact remaining asks; --apply --non-interactive is fail-closed — it refuses with that list instead of ever asking (unattended/VPS runs). The one-liner passes a file through too: CE_ANSWERS=ce-install.answers.yaml curl … | bash (or bash -s -- --answers <file>). An answers value can configure anything except a weaker grader — weakening (the cost opt-out, protections below the CE floor) requires your explicit ratified binding, educate-first.

The E1 venv installs the user-facing ce command. Durable user-local exposure belongs to the later apply path, not a system-wide E1 symlink.

Cost safety (the #1 pilot question)

Cost-runaway protection is on by default (spend_cap_enforcement: enforce). You may opt out of the per-run / per-fleet lane caps only with an explicit, ratified choice — and CE educates you first:

Turning this off won't speed up your runs; it only removes per-run / per-fleet lane-cap friction. The runaway-detection net (global ceiling + anomaly → escalate) stays on.

So even opted-out, you are never blind — see ../contracts/spend-envelope.md.

2. Provision the repo + the GitHub App

The later apply path provisions the Plane-C runtime box (gVisor runsc + a deny-by-default egress proxy) and the GitHub App (its private key lives on tmpfs and mints a JIT scoped token only at open/merge, then revokes — never in the box). You complete the GitHub-App authorization click in your browser. CE opens and merges as the App bot identity (≠ you), so on a solo repo you are the reviewer and no-self-approval holds.

The GitHub leg is fully decomposed and re-run convergent:

For a brand-new project, set github.mode: new, github.repo, project.name (optional; defaults to the repo basename), and project.scaffold.kind: minimal in the answers file. ce install --plan then shows first_project: the project root under host.workspace_root, the minimal scaffold input supplied to E2's workspace_checkout leg, and the Frame→Ship flags that remain false until your first real Scope ships. The bootstrap README and initial branch are onboarding evidence only; they do not count as first ship.

For an existing repo, ce install --inventory and --plan also report brownfield / brownfield_adoption: workflows and checks to preserve, detected test commands, Git history posture, branch/commit conventions, scrub preflight, project skill artifacts, and a first Scope seed. Clone the target repository first, then run the brownfield onboard commands from inside that checkout; the adoption planner resolves the project root from the current working directory. These paths are read-only until E2's onboard_apply brownfield extension legs perform the writes. To run brownfield --apply, the host environment must set CE_FORGE_LIVE_FORGE=1 and CE_FORGE_ADOPTION_WRITE=1, and the GitHub App credentials must resolve: CE_FORGE_APP_CLIENT_ID, the installation id (CE_FORGE_INSTALLATION_ID or github.app.installation_id), and either CE_FORGE_APP_PEM for the local signer path or both CE_FORGE_MINT_BROKER_URL and CE_FORGE_MINT_BROKER_USER_TOKEN for the shared-App mint-broker path. If those write-authority flags or credentials are absent, apply refuses with e2_brownfield_seam_unavailable; satisfy the flags and credential source, then re-run apply from the target repo checkout.

A minimal brownfield answers file still uses the same versioned answers schema:

answers_version: 1
github:
  mode: existing
  repo: owner/repo
brownfield:
  enabled: true

3. Drive work as a Scope (Frame → Shape → Build → Review → Ship)

From the repository you want CE to govern, open the terminal session:

ce session
◆ Creator Engine · governed session · repo <owner/repo> · transport cc-hooks · backend gvisor · state .ce/state
◆ CE · Frame 0 · Shape 0 · Build 0 · Review 0 · Ship 0  │  ctx 8%  │  spend —

ce session starts the governed launcher around your coding-agent terminal. The status line shows your stage (the canon Frame→Shape→Build→Review→Ship over the conserved machine), plus a unified context + spend meter with a boundary-aware checkpoint//clear nudge. Vocabulary canon: ../architecture/stage-vocabulary.md.

  1. Frame — just chat with your agent about what you want. Nothing is tracked.
  2. Shape — when a concrete change emerges, CE offers to crystallize it into a Scope (the chat→Scope detect-and-offer; cheap, inline, cancel-safe). The Scope card fills in the required labels — Goal · Done-when · Change-type. Readiness is shown separately as the card state. The agent drafts the Scope and may make a change safer on its own but only you can make it riskier. Shaping design: ../architecture/shaping-ux.md. When the card reads Ready ✓, ratify the Scope: ce ratify <scope>.
  3. Build — ce drive <scope> dispatches one governed, boxed run (the front gate refuses unless Ready + ratified).
  4. Review — read the ◆ CE Completion Report: ce report <scope>:
┌─ ◆ CE COMPLETION REPORT · run r-91a · Scope cs-4f2 ──────────────────
│ Outcome   PR opened → #7
│ Verdict   Done-when 3/3 met · tests green · in scope ✓
│ Next      → Review PR #7  (Change-type code → your approval)
│ Inspect   gh pr view 7   |   ce show cs-4f2   |   ce artifacts r-91a
└──────────────────────────────────────────────────────────

You judge artifacts (the PR, the manifest-scoped diff, the evidence) — not a transcript. The grader lives outside the agent.

  1. Ship — approve and merge the PR (the back gate is mutation_class-tiered; branch protection enforces independent review). Ship is plural — a merged PR, delivered research, or a ratified "no change."

4. Inspect anything

ce artifacts <run> and ce show <scope> enumerate every artifact (PR · Scope · ratification · closed manifest · evidence-chain · spend) with its inspect command. For the plain-language tour, run ce guide.

5. Greenfield-OSS quickstart

For a fresh open-source repo: prepare answers with github.mode: new, run ce install --spec llms-install.md --answers ce-install.answers.yaml --plan, then apply after the plan is clean:

ce install --spec llms-install.md --answers ce-install.answers.yaml --apply --non-interactive

Authorize the App when prompted, then run ce session from the repo terminal. Chat in Frame, confirm a real first Scope, ratify it, drive the Build, review the PR in a distinct venue, and merge through ce merge --apply. From there, every change is a governed, cost-safe, evidence-backed Scope.

Deferred (after E1)

Runtime provisioning · the interactive GitHub-App click · live status-line tap · live run dispatch. These are the human-gated live seams the authenticated inventory bootstrap prepares but does not claim.

Companions

understanding-ce.md · ../architecture/pilot-uiux-model.md · ../architecture/pilot-deployment-transport.md · ../contracts/installer.md · ../contracts/scope.md · the project README's Current Status section.