feat: improve state migration and delivery visibility

.gitignore

@@ -8,4 +8,4 @@ coverage/
 *.log
 .mill/
 .mill-scratch/
-TEMP_MILL_GREENFIELD_WORK_PLAN_*.md
+/TEMP_MILL_GREENFIELD_WORK_PLAN_*.md

README.md

@@ -78,9 +78,13 @@ For its one qualified shape, Mill can:
     names the next attended safe action without taking it;
 13. report the built-in builder's trusted-host boundary and reject an
     unqualified request for isolated execution rather than silently claiming
-    containment. Mill does not autonomously research the web or invent a product
-    specification in this alpha. The operator supplies the structured proposal
-    that Mill assesses and freezes.
+    containment; and
+14. report redacted aggregate lifecycle, attempt and repair counts for the
+    current repository with `millctl stats`.
+
+Mill does not autonomously research the web or invent a product specification in
+this alpha. The operator supplies the structured proposal that Mill assesses and
+freezes.
 
 ## Repository playbooks, run timelines and outcomes
 
@@ -183,6 +187,22 @@ npx --no-install millctl inspect --prd product/PRD.md
 npx --no-install millctl adopt --scan-only
 ```
 
+If the repository already has one approved ready outcome, use the shortest
+attended delivery route:
+
+```sh
+millctl --json start --prd product/PRD.md --attended
+millctl --json status
+millctl --json stats
+```
+
+`start` selects that one outcome or resumes its existing lifecycle. It checks
+authority before dependency or model spend. `status` explains the selected run;
+`stats` gives a redacted aggregate for the repository. None of these commands
+approve a push, pull request, merge or release. Use the expert sequence below
+when you need to inspect each boundary. See the [glossary](docs/glossary.md)
+before creating or reviewing authority files.
+
 ### Discover a TypeScript repository
 
 The remaining examples use `millctl` as shorthand for the installed executable;
@@ -367,6 +387,18 @@ conditions and outstanding live evidence for delivery
 `01801a1b-58f9-480f-8cee-54ea2bbeabb2`. Human readiness, merge authority, and
 exact candidate/tree checks remain required.
 
+## Public interface
+
+The supported programmatic surface is the `millctl` CLI, its versioned JSON
+result envelope, and the published JSON schemas. Shell automation should invoke
+the CLI with `--json` and check `ok`, `status`, and `reasons`; it should not
+parse the human-readable formatter.
+
+The package also exports TypeScript modules for repository development and
+experimentation. Those direct JavaScript imports are prerelease APIs and can
+change in a minor Mill release. Build integrations on the CLI and schemas until
+Mill publishes a separately supported library contract.
+
 ## Trust model
 
 Mill separates four principals:
@@ -383,6 +415,11 @@ billing. GitHub operations use your existing `gh` session. Another maintainer
 can clone Mill and use their own Codex and GitHub accounts after the downstream
 repo explicitly allows their identity. Mill stores neither credential.
 
+Use a separate, repository-scoped GitHub identity where the risk warrants it.
+The [delivery credential guide](docs/delivery-access.md) describes the required
+review and current limits. Mill does not inspect or attest the permissions of
+the `gh` session it invokes.
+
 The Codex worker runs on the trusted host with a workspace-write sandbox. This
 is not containment against hostile code, host files, keychains, processes, or
 network access. Native candidate verification is the stronger boundary: a
@@ -405,6 +442,7 @@ interrupted, inspect before acting:
 millctl --json status --run <run-id>
 millctl --json continuation --run <run-id>
 millctl --json timeline --run <run-id>
+millctl --json stats
 millctl --json resume --task product/tasks/TASK.yaml --run <run-id>
 millctl --json cancel --run <run-id>
 millctl --json pr reconcile --task product/tasks/TASK.yaml --run <run-id>

docs/delivery-access.md

@@ -0,0 +1,29 @@
+# Delivery credentials
+
+Mill does not collect, store, create or distribute credentials. The attended
+shipper invokes the operator's existing `gh` session only after a delivery or
+merge plan is approved. The builder and reviewer are instructed not to use forge
+credentials, but the built-in worker runs on a trusted host. Treat a host
+session as unsuitable for hostile repositories or sensitive source.
+
+## Scope the GitHub identity
+
+Use a separate GitHub identity for delivery when the repository's risk warrants
+it. A fine-grained token or GitHub App installation should be limited to the one
+repository and the smallest permissions required by the delivery policy:
+
+- repository contents write for the approved branch push;
+- pull requests write for draft creation and attended readiness; and
+- checks and commit-status read for exact-head observation.
+
+Add issue, administration, organization, workflow, package or environment
+permissions only when a separately reviewed repository policy requires them.
+Mill's current `gh` integration cannot inspect or attest the effective token or
+App scope. Configure and review that identity in GitHub, keep the credential in
+the operator's credential store, and record any exception in the repository's
+delivery authority. Never put a token, client secret, or browser session in
+`mill.yaml`, a task packet, a prompt, or a support bundle.
+
+The existing operator `gh` session remains supported. Using a narrower identity
+is an operational hardening step, not a new Mill trust claim or an automated
+credential rotation system.

docs/glossary.md

@@ -0,0 +1,27 @@
+# Glossary
+
+Use these terms consistently when operating or reviewing Mill.
+
+- **Acceptance item:** an approved statement that a task must prove. A test or
+  review note is evidence for an item, never a replacement for it.
+- **Authority:** approved repository material that may constrain a run, such as
+  the product contract, scenarios, impact manifest and task packet.
+- **Baseline qualification:** a declared-command result for the unchanged task
+  base. Its digest may authorize one matching run; it does not authorize a
+  patch, push or merge.
+- **Candidate:** the exact local commit produced for a run. Verification and
+  review bind to this commit.
+- **Impact manifest:** the approved statement of affected outcomes, invariants,
+  scenarios and exceptions for one change.
+- **Outcome:** one planned, dependency-aware unit of delivery. `start` selects
+  one approved ready outcome or resumes its existing lifecycle.
+- **Playbook:** small repository-owned operational context. It can guide work,
+  but it cannot alter acceptance criteria or approve an action.
+- **Task packet:** the versioned, bounded execution authority for one outcome.
+- **Timeline:** a redacted projection of durable lifecycle events. It exposes
+  event order and state transitions, never event payloads.
+- **Verification:** execution of declared repository commands against the
+  committed candidate. It is separate from review and owner acceptance.
+
+See [planning](planning.md), [run timelines](run-timeline.md), and
+[run outcomes](run-outcome.md) for their exact contracts.