From e8effef4159644e91aeba3daf4247b9dc89380e5 Mon Sep 17 00:00:00 2001
From: Jon Chery <jchery@jccapital.xyz>
Date: Sat, 1 Aug 2026 13:20:33 +0000
Subject: [PATCH] =?UTF-8?q?verify(P17):=20getting-started-consolidation=20?=
 =?UTF-8?q?=E2=80=94=204-layer=20verify=20PASS=20+=20ship?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

VERIFY: structural — offline-first restructure; behavioral — CI PASS; quality — single getting-started path.

---ci---
project: acdl
phase: 17
milestone: v1.16
status: complete
phase_role: execution
requirements:
  covered: [REQ-181]
  partial: []
---/ci---
---
 README.md | 76 +++++++++++++++++++++++++++----------------------------
 1 file changed, 37 insertions(+), 39 deletions(-)

diff --git a/README.md b/README.md
index 4e81f21..2664425 100644
--- a/README.md
+++ b/README.md
@@ -126,20 +126,46 @@ engine-specific code. `modules/`, `schemas/`, `contracts/`,
 
 ## How to run
 
-### Prerequisites
+### Quick start (offline, no AWS required)
 
-> These prerequisites are for running the **platform repo** locally. A
-> consumer does not need any of these — see the
-> [Consumer guide](docs/consumer-guide.md) for the consumer happy path.
+The fastest way to verify the platform works — no AWS credentials, no
+bootstrap, no cost. See the [Consumer guide](docs/consumer-guide.md)
+for the consumer happy path (a consumer owns only a contract + app code).
 
-- A platform-managed environment (see [docs/environments/](docs/environments/)).
-  For local testing, `core/environments/dev.json` is provided as the sample.
-- AWS credentials for the dev environment (in `.env.secrets`, gitignored;
-  see [Credentials & zero-trust](#credentials--zero-trust)).
-- `terraform` (pin `1.9.*`), `checkov` (pin `>=3.2,<4`), `python3` + `boto3`
-  + `jsonschema`.
+```bash
+# Install test dependencies
+pip install -r requirements-test.txt
 
-### Run the platform pipeline end-to-end
+# 1. Run the test suite (all offline — uses moto for DynamoDB mocking)
+python3 -m pytest tests/ -v
+
+# 2. Run the platform in check-only mode (offline — contract -> resolver ->
+#    adapter -> structure validation). Uses the default sample contract
+#    (contracts/static-assets.yaml) + sample dev environment.
+bash scripts/run_platform.sh --check-only
+# Expected: "=== PLATFORM CHECK OK ==="
+
+# 3. Run the headline E2E against the local emulating tier (emulates ECS,
+#    outbox, S3 state, Lambda in-process; D-092).
+bash scripts/run_platform.sh --local
+# Expected: "=== LOCAL E2E OK ==="
+
+# 4. Reproduce the full CI pipeline locally (lint -> test -> check-only)
+bash scripts/run_ci.sh
+# Expected: "=== CI PIPELINE OK ==="
+
+# Show all run_platform.sh flags:
+bash scripts/run_platform.sh --help
+```
+
+### Run against live AWS (requires credentials + bootstrap)
+
+> Prerequisites: a platform-managed environment (see
+> [docs/environments/](docs/environments/); `core/environments/dev.json`
+> is the sample), AWS credentials for dev (in `.env.secrets`, gitignored;
+> see [Credentials & zero-trust](#credentials--zero-trust)), `terraform`
+> (pin `1.9.*`), `checkov` (pin `>=3.2,<4`), `python3` + `boto3` +
+> `jsonschema`.
 
 ```bash
 # 1. Bootstrap the AWS state backend + runner IAM user (one-time, idempotent)
@@ -168,34 +194,6 @@ bash scripts/run_platform.sh --plan-only contracts/static-assets.yaml
 bash scripts/run_platform.sh --quiet contracts/static-assets.yaml
 ```
 
-### Test the platform (offline, no AWS required)
-
-```bash
-# Install test dependencies
-pip install -r requirements-test.txt
-
-# Run the test suite (all offline — uses moto for DynamoDB mocking)
-python3 -m pytest tests/ -v
-
-# Run the platform in check-only mode (offline — no AWS, no policy checks,
-# no outbox). Uses the default sample contract (contracts/static-assets.yaml)
-# and the sample dev environment (core/environments/dev.json).
-bash scripts/run_platform.sh --check-only
-# Expected: "=== PLATFORM CHECK OK ==="
-
-# Run the headline E2E against the local emulating tier (no AWS credentials
-# needed — emulates ECS, outbox, S3 state, Lambda in-process; D-092).
-bash scripts/run_platform.sh --local
-# Expected: "=== LOCAL E2E OK ==="
-
-# Reproduce the full CI pipeline locally (lint -> test -> check-only)
-bash scripts/run_ci.sh
-# Expected: "=== CI PIPELINE OK ==="
-
-# Show all run_platform.sh flags + a one-line description each.
-bash scripts/run_platform.sh --help
-```
-
 ### CI/CD pipelines
 
 The CI/CD pipeline is defined by a **central pipeline contract** — a