docs: sharpen the open-source adoption path

.github/ISSUE_TEMPLATE/adoption_help.yml

@@ -0,0 +1,74 @@
+name: Adoption help
+description: Ask a focused public question about trying CCP in a repository.
+title: "[Adoption help]: "
+labels:
+  - question
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form for setup, fit, or first-run questions. This is not an evidence report: do not attach private receipts, raw logs, secrets, or customer data.
+  - type: input
+    id: ccp_version
+    attributes:
+      label: CCP version
+      description: Which commit-ci-preflight version are you using?
+      placeholder: commit-ci-preflight 0.1.0
+    validations:
+      required: true
+  - type: input
+    id: project_runtime
+    attributes:
+      label: Project runtime
+      description: Which language runtime, toolchain, or interpreter does the repository use?
+      placeholder: Rust 1.96 with Cargo
+    validations:
+      required: true
+  - type: input
+    id: platform
+    attributes:
+      label: Platform
+      description: Include OS, architecture, and relevant container runtime; policy/resource profiles are separate from the project runtime.
+      placeholder: macOS 15, Apple Silicon, Docker Desktop
+    validations:
+      required: true
+  - type: input
+    id: repository_language
+    attributes:
+      label: Repository language
+      description: What primary language and build tooling does the repository use?
+      placeholder: Rust with Cargo
+    validations:
+      required: true
+  - type: textarea
+    id: attempted_step
+    attributes:
+      label: Attempted step
+      description: What were you trying to do, and which documented command or guide did you follow?
+    validations:
+      required: true
+  - type: textarea
+    id: error_summary
+    attributes:
+      label: Bounded error summary
+      description: Summarize the visible result without pasting private or unredacted logs.
+    validations:
+      required: true
+  - type: textarea
+    id: expected_outcome
+    attributes:
+      label: Expected outcome
+      description: What result would let you decide whether CCP fits your repository?
+    validations:
+      required: true
+  - type: checkboxes
+    id: privacy_confirmation
+    attributes:
+      label: Public-safe content
+      options:
+        - label: I have removed secrets, private logs, private receipt fields, customer data, machine identity, and local paths.
+          required: true
+  - type: markdown
+    attributes:
+      value: |
+        For a completed trial with public, redacted results, use the adoption-report form instead. For a security vulnerability, follow SECURITY.md.

CHANGELOG.md

@@ -9,6 +9,14 @@ Semantic Versioning after its first public release.
 
 ### Added
 
+- Added the adoption-help issue-form source and a 1280 × 640 social-preview PNG
+  upload candidate. GitHub form rendering/live chooser remains unverified until
+  the remote gate; preview upload is owner-only and pending.
+
+- Added a benefit-led visitor journey, bounded PR #71 case study, and public
+  support routing for adoption, defects, security reports, and proposals,
+  including concise operator-safety routing for agent-mode questions.
+
 - Shared terminal owned-resource finalization now routes historical and matrix
   runs, benchmarks, and guarded execution through completion-before-release,
   exactly-once admission release, and fail-closed release-error precedence.

README.md

@@ -1,13 +1,18 @@
 # Commit CI Preflight
 
-Proof-carrying CI for developer-owned execution. Commit CI Preflight runs a
-reviewed, pinned execution contract on your hardware, writes a commit-bound
-receipt, and lets GitHub verify that evidence instead of rerunning heavy work.
+> **Run heavy CI locally. Prove the exact commit on GitHub.**
 
-Commit CI Preflight is an independent, vendor-neutral Apache-2.0 project with a
-Rust core. It is designed for teams whose remote CI cost or queue time is
-growing, but who do not want cost control to weaken review, security, or
-platform coverage.
+Commit CI Preflight (CCP) is an independent, vendor-neutral Apache-2.0 Rust
+project that turns expensive, deterministic checks into commit-bound evidence:
+run a reviewed plan on your machine, then let a small GitHub gate verify the
+exact pull-request head. It is for teams whose remote CI cost or queue time is
+growing without weakening review, security, or platform coverage.
+
+Start here:
+
+- [PR #71 case study](docs/CASE_STUDY_PR71.md) — a bounded, public example.
+- [Clean-room tutorial](docs/TUTORIAL.md) — produce and verify a first receipt.
+- [Adoption guide](docs/ADOPTION_GUIDE.md) — decide whether CCP fits your repository.
 
 > Status: **v0.1.0-rc.1 prerelease**. The source implementation and native
 > benchmark evidence are complete. The
@@ -65,6 +70,14 @@ absolute home paths, and personal or machine identity fields.
 A receipt is integrity and policy evidence. It is not an identity attestation,
 a signature, or proof that arbitrary local and hosted workflows are identical.
 
+## Is CCP for this repository?
+
+| If your repository has… | CCP fit |
+|---|---|
+| deterministic, container-friendly checks and pinned runtime images | **Yes — start with a clean-room trial** |
+| trusted secrets, deployments, or platform-specific behavior | **Partial — retain the relevant remote/native jobs** |
+| a requirement for signed identity-bound attestations | **No — CCP is not that attestation system** |
+
 ## Quick start
 
 Adopting CCP in another repository? Start with the
@@ -87,92 +100,25 @@ cargo build --locked
 The first build can take longer when Rust dependencies are not cached. `plan`
 normalizes the contract, `doctor` performs a bounded runtime probe, and
 `dry-run` renders the exact container command and mounts. None of these three
-commands executes project code or emits an attestable receipt.
+commands executes project code or emits an attestable receipt. For admission,
+resource, cache, and guarded-workflow details, read the
+[coordination runbook](docs/COORDINATION_RUNBOOK.md),
+[local run contract](docs/LOCAL_RUN.md), and
+[resource observation history](docs/RESOURCE_OBSERVATION_HISTORY.md).
+
+The planned agent admission mode is an owner-approved safety exception for
+orphan prevention, not a second scheduler. `agent mode opt-in` must remain
+explicit: operators must never bypass unknown ownership, never revive a terminated chat,
+and never auto-execute a command. An official launcher is a shell-free wrapper around one explicit program argv.
+Official launchers must pass through `guard exec` to be covered. See the
+coordination runbook, local run contract, and adoption guide above for the
+complete safety contract.
 
 For a real PASS and receipt, use the [clean-room tutorial](docs/TUTORIAL.md).
 It first creates a separate Git repository for the fixture; running the example
 configuration against this source checkout would validate the wrong repository.
 
-### 2. Inspect a configuration without running checks
-
-```console
-./target/debug/commit-ci-preflight plan   --config examples/projects/rust/.commit-ci-preflight.toml
-./target/debug/commit-ci-preflight doctor   --config examples/projects/rust/.commit-ci-preflight.toml
-./target/debug/commit-ci-preflight dry-run   --config examples/projects/rust/.commit-ci-preflight.toml
-```
-
-`doctor` performs a bounded read-only runtime probe. `dry-run` prints the
-exact container argv and mounts but does not execute project code.
-
-`run` and `benchmark` are serialized through a default-on host-wide single-slot
-queue so independent local agents cannot start both heavy workloads at once.
-The planned agent admission mode is an owner-approved safety exception for
-orphan prevention, not a second scheduler.
-This agent mode opt-in must never bypass unknown ownership.
-This agent mode opt-in must never revive a terminated chat.
-This agent mode opt-in must never auto-execute a command.
-A live activity must make an explicit claim before it invokes its own guarded
-command.
-Use `--admission-timeout-seconds` to select the bounded wait. The
-`admission status --json` result distinguishes the transient `queue_lock` from
-the heavy-work `slot_lock`, and reports the slot's opaque owner/run identifier,
-acquisition time, heartbeat time, and lease state when available. A missing
-owner record, a malformed lease, or a contradiction between the OS lock and
-the lease is reported as `unknown` and is never treated as inactivity. The
-status also states explicitly that absence of a process in one local shell
-does not prove global inactivity across Codex activities or users. On macOS, the queue is followed by a strict `macos-v4`
-host-memory admission sample, and `run` has a two-second watchdog that cancels
-only on sustained compound or critical pressure. Admission requires at least 20% available memory and
-3 GiB reclaimable uncompressed memory, and caps swap at the smaller of 8 GiB
-and 30% of physical RAM. Compression alone is advisory both before and during
-the run; at pre-start it denies only when at least 70% compression accompanies
-another pressure signal. The in-run watchdog treats compression the same way:
-soft cancellation needs
-at least two converging signals for about 30 seconds, while critical available,
-reclaimable, swap, or compound-compression conditions remain immediate stops.
-`resource status --json` reports bounded metrics and
-capability; Linux and Windows report `unsupported_not_enforced`. Resource and
-admission evidence are not part of receipts yet.
-
-Wrap any other long local workflow with the same protection by passing one
-explicit argv after `--`:
-
-```console
-commit-ci-preflight guard exec \
-  --admission-timeout-seconds 21600 \
-  --timeout-seconds 21600 \
-  --resource-profile ready \
-  --resource-workload-family brain-linux-ci-v1 \
-  --resource-executor orbstack \
-  --resource-execution-mode emulated \
-  --resource-target-platform linux-amd64 \
-  -- make all
-```
-
-The wrapper never invokes a shell, runs the child from the caller's current
-working directory, never creates a receipt, and keeps the admission slot until
-the supervised process tree has stopped. Both waits
-default to six hours for `guard exec` and are capped at 24 hours. On macOS it
-retains at most 500 local, privacy-bounded v2 summaries with workload,
-executor, cache, execution-mode, target and optional requested-limit context.
-The history changes no policy decision and can be disabled
-with `--no-resource-history`; see the
-[resource observation history contract](docs/RESOURCE_OBSERVATION_HISTORY.md).
-Official launchers must pass through `guard exec` to be covered. CCP does not
-claim visibility into direct Docker or OrbStack processes that bypass it; see
-the [coverage and adoption inventory](docs/ORBSTACK_TELEMETRY_COVERAGE.md).
-When multiple agent activities or repositories share the Mac, follow the
-[cross-activity coordination runbook](docs/COORDINATION_RUNBOOK.md). It defines
-the owner/lease interpretation, reservation handoff, worktree isolation, and
-safe recovery rules; a process list from one terminal is not a host-wide
-ownership proof.
-Inspect the bounded local records without starting work:
-
-```console
-commit-ci-preflight resource history --json
-```
-
-### 3. Run the clean-room demo
+### 2. Run the clean-room demo
 
 Follow the [end-to-end tutorial](docs/TUTORIAL.md). It copies a tiny public Rust
 fixture into its own Git repository, runs its test through a pinned container,
@@ -182,6 +128,12 @@ repository policy.
 For installation, checksum verification, and local candidate archives, see
 [the installation guide](docs/INSTALLATION.md).
 
+## Dogfooding proof
+
+This repository uses CCP for its own bounded qualification workflow. See the
+[PR #71 case study](docs/CASE_STUDY_PR71.md) for the exact public anchors and
+the limits of what that evidence proves.
+
 ## What makes it different
 
 | Tool or approach | Primary model | Relationship to Commit CI Preflight |

SUPPORT.md

@@ -0,0 +1,13 @@
+# Support
+
+Please choose the smallest public route that matches your question:
+
+- Reproducible defects: use the [bug report form](https://github.com/MarcoPorcellato/commit-ci-preflight/issues/new?template=bug_report.yml).
+- Adoption questions: use the public [issue chooser](https://github.com/MarcoPorcellato/commit-ci-preflight/issues/new/choose) and select **Adoption help** when GitHub displays it. The form is for fit and setup questions, not evidence reports.
+- Completed trials: use the [adoption report form](https://github.com/MarcoPorcellato/commit-ci-preflight/issues/new?template=adoption_report.yml).
+- Security vulnerabilities: follow [SECURITY.md](SECURITY.md) and its private reporting instructions.
+- Design proposals: use the [feature request form](https://github.com/MarcoPorcellato/commit-ci-preflight/issues/new?template=feature_request.yml).
+
+Before opening a public issue, remove secrets, proprietary logs, receipts with
+private fields, customer data, machine identity, and local paths. A minimal
+reproduction and the relevant public commit are usually enough.

docs/CASE_STUDY_PR71.md

@@ -0,0 +1,39 @@
+# Case study: Commit CI Preflight PR #71
+
+## What problem this demonstrates
+
+CCP's `dry-run` output is a planning surface, not a replay bundle. A copied
+Docker command can reference lifecycle-managed cache sources that no longer
+exist; the diagnostic must therefore use its own writable, independently
+validated mounts.
+
+## Exact public anchors
+
+This case study concerns [PR #71](https://github.com/MarcoPorcellato/commit-ci-preflight/pull/71)
+at head `f3fb14a0329cf031d08f474115a8b56fe1cffcf6`, merged by commit
+`820a7fa6ce83a7ac8593c2800f8be4f44ab82ebc`.
+
+The append-only evidence ref resolves to commit
+`382ba81a6869777a92f987068e2814f542e7ec8b`. Its public receipt has SHA-256
+`624477439b1bdb7b397876a7e5f8434057f8805835162c5fccb21beac015000b` and
+receipt ID `sha256:3536dce784a646f6450f6a228230e09ffff8d4d5bd45f89dfd285223a9a235d1`.
+The associated [workflow run](https://github.com/MarcoPorcellato/commit-ci-preflight/actions/runs/33220815044)
+completed successfully.
+
+## What happened
+
+The workflow followed a bounded lifecycle: local qualification produced the
+receipt; evidence was published append-only; GitHub checked the receipt against
+the exact pull-request head; and the pull request was merged. The public
+[evidence ref](https://github.com/MarcoPorcellato/commit-ci-preflight/tree/ccp-evidence/f3fb14a0329cf031d08f474115a8b56fe1cffcf6)
+and [receipt specification](RECEIPT_SPEC.md) describe the inspectable artifacts.
+
+## What this proves — and does not prove
+
+The receipt integrity and policy checks, together with the exact-head gate,
+prove the recorded local evidence for this exact commit. They do not prove
+producer identity, a signature, cost savings, arbitrary hosted-CI parity, or
+qualification of other platforms. They also do not turn a receipt into an
+identity attestation.
+
+The [verification policy](VERIFICATION_POLICY.md) defines these boundaries.

docs/REPOSITORY_PRESENTATION.md

@@ -6,10 +6,11 @@ GitHub setting.
 
 ## Recommended repository metadata
 
-- Description: `Proof-carrying CI: run heavy checks locally, verify exact-commit receipts on GitHub.`
+- Description: `Run heavy CI locally. Verify exact-commit receipts on GitHub.`
 - Website: leave empty until a maintained project site exists.
-- Topics: `ci`, `continuous-integration`, `devtools`, `github-actions`,
-  `local-first`, `rust`, `supply-chain`, `developer-tools`.
+- Topics: `ci`, `continuous-integration`, `developer-tools`, `devtools`,
+  `github-actions`, `local-ci`, `local-first`, `reproducible-builds`, `rust`,
+  `supply-chain`.
 - Discussions: enable only when a maintainer is ready to moderate adoption and
   design questions.
 
@@ -39,6 +40,9 @@ Before uploading a preview through **Settings → General → Social preview**:
 The repository does not treat the source SVG as proof that GitHub is currently
 using that image.
 
+The rendered `docs/assets/social-preview.png` is an upload candidate only. It
+has not been uploaded or verified as the live GitHub preview.
+
 ## Public claim boundary
 
 Use `proof-carrying CI` and `CI receipts for exact Git commits`. Do not claim

docs/superpowers/goals/2026-08-29-open-source-growth-program.txt

@@ -0,0 +1,34 @@
+Complete the Commit CI Preflight open-source growth and truthful stable-release
+programme according to the canonical specification at
+`docs/superpowers/specs/2026-08-29-open-source-growth-program-design.md` and the
+master plan at
+`docs/superpowers/plans/2026-08-29-open-source-growth-program.md`.
+
+Start from the isolated branch `codex/open-source-growth-program-v1`, whose
+last verified base was `820a7fa6ce83a7ac8593c2800f8be4f44ab82ebc`, but reverify
+the live worktree, `origin/main`, GitHub state, active CCP operator contract,
+and completed milestone evidence before acting. Preserve the divergent primary
+checkout and do not redo work already proved in the specification ledger.
+
+Proceed autonomously through dependency-ordered milestones M0-M10. Create an
+exact live-source TDD plan before each milestone, deliver independently
+reviewable commits and pull requests, run deterministic validation before
+native, network, Docker, or CCP work, and keep the canonical specification and
+restart handoff current.
+
+Use deterministic tools first. Delegate bounded inventories, documentation,
+mechanical isolated edits, deterministic test runs, and independent reviews to
+GPT-5.6 Luna. Keep architecture, trust, security, cryptography, integration,
+qualification, release, publication, and merge decisions with the primary
+agent. Serialize overlapping writes and verify every delegated result.
+
+Keep all evidence and claim boundaries unchanged. Treat commit, push, PR,
+ready transition, CCP run, evidence publication, merge, repository settings,
+package upload, tag, release, signing, case-study consent, and public launch as
+separate gates requiring exact live authorization when not already explicit.
+Never silently replace the installed global producer or manipulate CCP
+admission, journal, receipt, lease, cache, lock, or resource state.
+
+Continue safe independent work until every applicable completion item is
+supported by authoritative current evidence. Ask only at a named authority
+boundary, an unavailable native/consent dependency, or a material scope change.