bootproof 0.3.0 → 0.4.0

package/docs/FAILURE_TAXONOMY.md

@@ -15,14 +15,39 @@ Unknown evidence remains `unknown_failure`. BootProof does not pick a more marke
 |---|---|---|
 | `not_an_application` | No trustworthy runnable entrypoint was found. | Select a runnable workspace or add an explicit start command. |
 | `orchestration_not_supported` | An application stack was detected, but no explicit supported entrypoint or source-built Compose web service was found. | Use the repository's documented runbook; treat the signed result as diagnosis, not boot proof. |
+| `go_service_orchestration_not_supported` | A Go service was detected, but no safe runnable service command and health contract could be established. | Use the documented service command or provide an explicit reviewed override; do not treat detection as boot proof. |
+| `host_execution_not_acknowledged` | Host execution, including execution of a cloned remote repository, was selected without the explicit `--unsafe-local` acknowledgement. | Review the inferred commands, then rerun with `--provider local --unsafe-local` only if you accept host execution. |
+| `auth_required` | An externally managed health endpoint returned HTTP 401 or 403. | Use a separate unauthenticated health endpoint or verify authentication manually without exposing credentials. |
+| `external_health_unreachable` | An externally managed health endpoint could not be reached or did not return HTTP 2xx/3xx. | Confirm the service and endpoint are reachable, then rerun external verification. |
 | `runtime_engine_mismatch` | Node.js does not satisfy the declared engine. | Switch to a compatible runtime and rerun. |
+| `missing_ruby_version` | The exact Ruby version selected by rbenv is not installed. | Run `rbenv install <version>`. |
 | `missing_package_manager` | The declared package manager executable is absent. | Enable Corepack or install the required manager. |
-| `missing_runtime_tool` | An explicit Go, Ruby, Bundler, or Make run path was selected, but the executable is absent. | Install the repository-supported runtime or tool and rerun. |
+| `missing_runtime_tool` | An explicit Ruby, Bundler, Make, Python, PHP, or Composer run path was selected, but the executable is absent. | Install the repository-supported runtime or tool and rerun. |
+| `go_runtime_missing` | A selected Go service command cannot run because the `go` executable is unavailable. | Install the repository-supported Go version and rerun. |
+| `go_build_failed` | Go module resolution or compilation failed for the selected service. | Inspect the preserved compiler/module evidence and resolve the specific source or dependency error. |
+| `missing_project_cli` | A selected package script references a repository CLI that is unavailable in the prepared development environment. | Complete the repository's documented bootstrap or development-environment setup, then rerun. |
+| `missing_php_runtime` | The repository requires PHP, but the `php` executable is unavailable. | Install a repository-supported PHP version; mention Homebrew only when its presence is evidenced. |
+| `missing_composer` | The repository requires Composer, but the `composer` executable is unavailable. | Install Composer through an evidenced or documented method. |
+| `unsupported_php_version_for_composer_lock` | The current PHP version does not satisfy package constraints recorded in `composer.lock`. | Select a compatible PHP version, then rerun `composer install`; do not edit the lockfile as the first step. |
+| `missing_php_vendor_autoload` | `vendor/autoload.php` is absent after PHP dependencies failed or were not installed. | Resolve PHP/Composer compatibility, then run `composer install`. |
+| `laravel_sqlite_database_missing` | Laravel's configured SQLite database file does not exist. | Review and approve creation of `database/database.sqlite`, then separately approve `php artisan migrate`. |
+| `laravel_migrations_required` | Laravel started, but one or more required database tables are missing. | Run `php artisan migrate` only with explicit approval because it mutates local database state. |
+| `missing_build_tool` | A named native build tool required by a dependency is absent. | Install the reported tool, such as `brew install cmake`. |
+| `native_extension_compile_failed` | A gem native extension failed to compile. | Install the affected gem's native dependencies and rerun installation. |
 | `package_manager_version_mismatch` | The available package-manager version differs from the exact/simple declared version. | Activate the declared version, then rerun. |
 | `dependency_install_skipped` | A dependency-backed application was not started because install was not requested. | Review the install command and opt in with `--install`. |
 | `python_flask_setup_required` | Python/Flask setup requires migrations, initialization, workers, frontend, or service orchestration not yet supported safely. | Complete the documented setup manually; do not treat detection as full support. |
+| `laravel_vite_ci_hmr_blocked` | Laravel's Vite plugin refused to start the HMR asset server in CI. | Use a production asset build in CI, or run the Laravel application server for app verification. |
 | `missing_env_var` | Required environment configuration is missing. | Supply real values through the repository's documented path. BootProof will not edit `.env`. |
+| `missing_database_config` | `config/database.yml` could not be loaded or is absent. | Create it from the repository's documented example and review it. |
+| `missing_required_config` | Another explicitly named required configuration file is absent. | Restore the reported file from the repository's documented example. |
 | `database_unreachable` | A required database or cache could not be reached. | Start the real required service and verify its address. |
+| `postgres_unavailable` | PostgreSQL refused or could not accept the connection. | Start PostgreSQL and verify the configured host and port. |
+| `postgres_role_missing` | PostgreSQL is reachable, but the configured role does not exist. | Create the role or configure an existing one. |
+| `database_schema_missing` | PostgreSQL reports an undefined table or missing relation. | Run the repository's documented migrations or database setup. |
+| `unsupported_database_version` | The installed PostgreSQL version is outside the repository's supported range. | Install or select a supported version. |
+| `unsupported_database_config` | `config/database.yml` contains unsupported database names. | Use only the repository-supported names. |
+| `redis_unavailable` | Redis refused or could not accept the connection. | Start Redis and verify the configured host and port. |
 | `postgres_auth_env_missing` | Postgres was reached but authentication or env configuration did not match. | Correct the real database configuration; BootProof will not invent credentials. |
 | `migrations_missing` | The database schema is absent or behind. | Run the repository's documented migration flow. Repair is attempted only for one unambiguous recognized framework. |
 | `port_in_use` | The application port is occupied. | Stop the process or use a supported explicit port. |
@@ -33,8 +58,10 @@ Unknown evidence remains `unknown_failure`. BootProof does not pick a more marke
 | `docker_unavailable` | Docker is required by the plan but unavailable. | Start Docker or explicitly choose a safe local path. |
 | `install_failed` | Dependency installation failed for an otherwise unclassified reason. | Inspect preserved install evidence and fix the underlying cause. |
 | `app_exited_early` | The application exited before health was observed. | Inspect process evidence and fix startup. |
+| `health_preoccupied` | A health candidate was already responding successfully before BootProof started the application. | Stop the existing service and rerun, or explicitly verify it with `bootproof verify-url <url>`. |
 | `health_check_timeout` | No HTTP response was observed before timeout. | Check logs, port inference, and health candidates. |
 | `health_http_error` | A health candidate returned HTTP 5xx. | Fix the server error; a responding process is not yet healthy. |
+| `health_candidate_port_mismatch` | Process output advertised a different port from the inferred application health URL. | Confirm the primary app command and intended health port; do not mistake an asset server for the Laravel app. |
 | `workspace_ambiguous` | Multiple applications or health targets are plausible. | Choose one with `--workspace <dir>`. |
 | `unknown_failure` | Available evidence does not match a trustworthy detector. | Inspect the signed raw evidence and report a reproducible detector case. |
 

package/docs/HONESTY_CONTRACT.md

@@ -13,15 +13,18 @@ BootProof's promise is not that every repository boots. Its promise is that the
 7. Ambiguous workspaces are surfaced instead of guessed.
 8. Generated files are referenced as generated evidence only when they were actually written.
 9. Refusals and execution failures write signed failed attestations where a signer is available.
-10. Failed attestations preserve available raw local evidence; exported registry entries redact it.
+10. Failed attestations preserve available diagnostic evidence, redacted at capture before it is persisted. Registry export applies its own additional public-artifact redaction.
 11. A process starting is not enough. A health signal must be observed.
 12. Confidence describes evidence found, not predicted success.
 13. An image-only Compose service does not prove the checked-out source. Compose application proof requires a repository-local build context, a published HTTP port, and an observed HTTP response.
-14. A repair is only ever proposed with a verified before and after attestation.
-15. Repair generation never touches the user's working tree; applying a diff requires the separate explicit `apply-repair` command. This separation is intentional and is not bypassed by `fix`.
-16. Repair diffs are restricted to boot-plumbing scope; application logic is never edited.
-17. An unverified or failed remediation is reported as such and is never proposed on hope.
-18. Explicit repair application requires a valid signed receipt and exact file preimages; stale or tampered receipts write nothing.
+14. A deterministic repair suggestion requires a signature-valid classified failed attestation.
+15. A valid signature proves the attestation was not altered after signing. It does not, by itself, prove WHO produced it. BootProof distinguishes self-signed, known-signer, and unknown-foreign signatures, and binds directory verification to the repository's current commit.
+16. Commands run only after the exact command, mutation scope, and risk are shown and the user types uppercase `Y`. JSON and CI modes never approve commands.
+17. Repair generation never patches the user's working tree; applying a diff requires the separate explicit `apply-repair` command.
+18. Repair diffs are restricted to boot-plumbing scope; application logic is never edited.
+19. Declined, failed, progressed, and verified repair attempts remain distinct signed receipt states.
+20. Explicit repair application requires a valid signed receipt and exact file preimages; stale or tampered receipts write nothing.
+21. A health response may only be recorded as a verified boot if it could have come from the process BootProof started. Pre-existing responders are refused (`health_preoccupied`); a response observed after the supervised process has exited is not a boot.
 
 These behaviors are enforced by tests.
 
@@ -71,16 +74,22 @@ A repository Compose receipt is equally narrow. `docker compose up -d` exit 0 pr
 
 ## Verified Repairs
 
-`bootproof fix` copies the repository to a temporary sandbox, applies one registered deterministic remediation, and reruns the full BootProof verification engine. It reuses an existing failed attestation only when its signature is valid and it names the exact current clean Git commit; otherwise the failure is reproduced in the sandbox first.
+`bootproof fix` reads the latest signature-valid classified failure. The first interactive
+command playbooks cover missing CMake and unavailable Redis; `RAILS_ENV` receives a safe
+instruction only. Commands are structured argv, pass the safety validator, and require the
+literal response `Y`. After an approved command, BootProof copies the repository to a temporary
+sandbox and reruns the normal proof engine.
 
 The original working tree is never used as the repair target. BootProof writes only its evidence under `.bootproof/`:
 
 - the signed failed before attestation
 - a human-reviewable patch when files changed
-- the signed healthy after attestation
-- the signed repair receipt linking both hashes
+- the signed after attestation when a command was rerun
+- the signed repair receipt recording suggestion, approval, application, progress, and verification
 
-If the sandbox does not reach observed HTTP health, no repair receipt or patch is emitted. The failed attempt is appended to signed failure evidence.
+Declined, failed, and unverified attempts still produce receipts because failed attestations and
+repair attempts are valuable. `verified` remains false unless the rerun observes healthy HTTP.
+`progressed` is true only for verified health or a changed failure class.
 
 `bootproof fix` never auto-applies a patch. `bootproof apply-repair` is a separate, explicit mutation command. It verifies the receipt signature, scope whitelist, signed content hashes, and current preimages before writing. A mismatch writes nothing.
 
@@ -94,9 +103,22 @@ Current local runs use:
 local_developer_signed
 ```
 
-Local attestations are useful evidence. CI/OIDC attestations are stronger supply-chain proof. BootProof does not pretend local laptop proof is enterprise CI proof.
+The embedded public key proves integrity only. Local verification reports whether that key is
+this machine's signer, an explicitly pinned signer in `~/.bootproof/known_signers.json`, or an
+unknown foreign signer. Pinning uses `bootproof verify <proof> --trust-signer` and never happens
+automatically on first use.
 
-`ci_oidc_signed` is reserved for future workload-identity-backed signing. BootProof does not emit it today.
+`--require-known-signer` fails on unknown foreign signers. Directory verification compares the
+attested commit with live Git `HEAD`, and `--strict` fails if they differ.
+
+Local attestations are useful evidence. CI/OIDC attestations are stronger supply-chain proof.
+BootProof does not pretend local laptop proof is enterprise CI proof.
+
+`ci_oidc_signed` is emitted when `--ci-oidc` is passed to `bootproof up` inside a GitHub Actions
+workflow with `permissions: id-token: write`. The composite Action exposes this as the `ci-oidc`
+input (default: `false`). When enabled, BootProof fetches the runner's OIDC token and embeds the
+claims (iss, sub, repository, run_id, workflow, etc.) in the attestation trust block. The
+ed25519 signature still provides integrity; the OIDC evidence provides CI provenance.
 
 ## Network And Sharing
 

package/docs/LAUNCH_PLAYBOOK.md

@@ -0,0 +1,232 @@
+# The First 1,000 Receipts — Launch Playbook
+
+> Distribution is the engine; the moat is its exhaust.
+
+This is the concrete, week-by-week plan for getting BootProof from zero to the first 1,000 Living Receipts in the wild. Every phase has a single success metric. If the metric doesn't hit, the phase isn't done — don't move on, fix why.
+
+---
+
+## The thesis (read this first)
+
+The Living Receipt is not the moat. It is the **distribution weapon** — a viral, self-proving object that floods the gates with users. The moat (workflow lock-in as the merge gate, plus a compounding boot-inference flywheel) is **earned at scale**, not owned on day one.
+
+The slop crisis is real and cresting: curl shut down its bug bounty (January 2026), Jazzband shut down entirely, tldraw auto-closes all external PRs, Ghostty's Mitchell Hashimoto named the exact mechanism BootProof attacks ("running it was the filter"). The demand is assembled and screaming. The audience is not cold — they are posting in GitHub community discussion #185387, literally spec'ing the feature.
+
+The only thing standing between BootProof and 1,000 receipts is the single thing every prior project skipped: **shipping and distributing**. This playbook exists to make that skip impossible.
+
+---
+
+## Phase 0 — Ship the alpha (TODAY, before anything else)
+
+**Goal:** a stranger can `npx bootproof up <repo>` and get a Living Receipt.
+
+**Checklist:**
+- [x] Fix the npm package metadata (homepage/repository fields point to the wrong URL — `rossbuckley1990-hash/bootproof` instead of `bootproof/bootproof`). This is a 5-minute fix that has been leaking every visitor. **Fixed in commit on `main` — `repository`, `bugs.url`, and `homepage` now all point to `github.com/bootproof/bootproof`. The published npm package at `0.1.0` still has the old URL until 0.3.0 is published (next item).**
+- [ ] Publish `0.3.0` to npm. The published version is `0.1.0`; the repo is three minor versions ahead. The publishing muscle exists — the release cadence is broken. **Requires `npm publish` with npm credentials — run locally, not from a CI/sandbox. The `release:check` script (`npm test && npm run build && npm run pack:check && npm publish --dry-run`) is the pre-flight.**
+- [x] The Living Receipt HTML (`assets/living-receipt.html`) is on `main` and reachable via raw.githubusercontent.com.
+- [x] The badge template (`assets/bootproof-badge-template.md`) is on `main`.
+- [x] The README links to the Living Receipt with a clickable badge.
+
+**Success metric:** `npx bootproof up https://github.com/any-public-repo` works on a fresh machine with Node 20+. No errors. Writes a receipt.
+
+**If this doesn't work, nothing else in this playbook matters.** Do not proceed to Phase 1 until a stranger can run the command and get a receipt.
+
+---
+
+## Phase 1 — Maintainer #1 (Week 1)
+
+**Goal:** one prominent open-source maintainer adopts BootProof as a PR gate.
+
+**Why this first:** the slop-crisis maintainers are the exact audience, they're already gathered, and one public adoption is the equivalent of Slack's "8,000 signups in 24 hours" — but slower, over weeks, because maintainer-to-maintainer viral spread is real but skeptical.
+
+**The target list (in priority order):**
+
+1. **The GitHub community discussion #185387 participants.** This is the single highest-signal list. People who posted in "Exploring Solutions to Tackle Low-Quality Contributions on GitHub" are literally asking for this. Read the thread, identify the most active commenters, DM them with the receipt attached.
+
+2. **The curl orbit.** Daniel Stenberg shut down curl's bug bounty in January 2026 because AI slop reports collapsed the valid-rate from 1-in-6 to 1-in-20. BootProof is the automated version of "did you actually run it?" — exactly the filter he lost. He is reachable on GitHub and Mastodon.
+
+3. **The Ghostty orbit.** Mitchell Hashimoto named the exact mechanism ("running it was the filter") that BootProof re-imposes. He is reachable on GitHub.
+
+4. **The tldraw orbit.** They auto-close all external PRs — the most extreme response to slop. A BootProof gate is the less drastic alternative they haven't tried yet.
+
+5. **The six stargazers.** `serious-angel`, `jon91`, `highway900`, `mkkzkk`, `DoddiC`, `tkersey`. They already raised their hands. They're the warmest leads you have.
+
+**The DM template (3 lines, attach the Living Receipt HTML):**
+
+```
+Hi [name] — I saw your [post/comment about AI slop in PRs]. I built
+something that might help: a tool that actually boots a repo and signs
+proof of what happened. I attached a Living Receipt — double-click it,
+it verifies itself in your browser. If it's useful, I'd value your
+honest reaction. If not, tell me why. — Ross
+```
+
+**Rules:**
+- Do NOT lead with the architecture, the trust ladder, or the moat thesis. Lead with the artifact.
+- Do NOT pitch the hosted runner, the enterprise tier, or the roadmap. Pitch the free thing.
+- Do NOT send a form letter. Reference something specific they said about slop.
+- Attach the Living Receipt HTML. The artifact does the convincing — your words just get them to open it.
+
+**Success metric:** one maintainer runs `npx bootproof up` on a repo they care about and replies with a reaction that isn't "cool, thanks." The reaction you're looking for is "wait, how does this work?" or "can I use this as a PR gate?" — those are buying signals.
+
+**If you don't get a reply from any of the six stargazers in 72 hours:** the problem isn't the message, it's that the artifact doesn't land. Go back and watch someone open it in person. The "what the hell" moment has to be visible on their face. If it isn't, the receipt isn't good enough yet.
+
+---
+
+## Phase 2 — The public launch (Week 2)
+
+**Goal:** 100 receipts in the wild, traced to a single public launch.
+
+**The launch surfaces, in order:**
+
+### 2a. Hacker News (Tuesday or Wednesday, 7–9am Pacific)
+
+**Title (use exactly this — it's been pressure-tested against the HN aesthetic):**
+
+> Show HN: BootProof — the run button that can't lie (boots any repo, signs proof)
+
+**First comment (yours, posted immediately):**
+
+```
+I built this because AI-generated PRs that merge clean but don't actually
+boot are drowning maintainers. curl shut down its bug bounty over this.
+tldraw auto-closes all external PRs. The filter that used to exist —
+"you had to actually run the code to contribute" — is gone.
+
+BootProof re-imposes it. Point it at any repo, it infers how to run,
+boots it, observes whether localhost actually responds, and signs a
+receipt. The receipt is a single HTML file that re-verifies its own
+signature in your browser. Tamper with one byte and the verdict collapses.
+
+Two real captures in the repo: one that boots to HTTP 200, one that
+builds clean and segfaults at runtime. Both are real, not mock.
+
+Free, open source, Apache 2.0. I'm looking for maintainers who want
+to try it as a PR gate. — Ross
+```
+
+**Rules:**
+- Do NOT post on Monday (low traffic) or Friday (weekend death).
+- Do NOT post on the hour — post at :07 or :12 to avoid the submission queue.
+- Do NOT use a link shortener. HN penalizes them.
+- Respond to every comment within 15 minutes for the first 4 hours. The first hour determines whether it hits the front page.
+- When someone says "why not just use CI?" — answer: "CI tells you the script exited 0. BootProof tells you localhost responded. Green CI, dead app is the entire slop archetype. Here's a receipt: [link]."
+
+### 2b. r/programming (same day, 2 hours after HN)
+
+Cross-post the HN link. Title: "BootProof — a run button that actually verifies your repo boots (signed proof, not green CI)".
+
+### 2c. r/devops, r/node, r/rust, r/python (staggered over Week 2)
+
+One post per subreddit, tailored to the language. For r/rust, lead with the segfault receipt. For r/node, lead with the HTTP 200 receipt. For r/devops, lead with the CI-gate angle.
+
+### 2d. The agent-integration communities
+
+Post in the Cursor Discord, the Claude Code community, the Devin Slack. The pitch: "your agent emits a Living Receipt when it finishes — the human verifies it actually booted before merging." This is the "App Store moment" distribution surface.
+
+**Success metric:** 100 Living Receipts downloaded from the repo (track via GitHub raw file download analytics), 50 npm installs, 10 badges appearing in public READMEs (search GitHub for `bootproof` in README files).
+
+**If HN doesn't hit the front page:** the title or the first comment didn't land. The most common failure mode is leading with the technology instead of the pain. Rewrite the first comment to lead with curl/tldraw, not with ed25519.
+
+---
+
+## Phase 3 — The agent integrations (Week 3)
+
+**Goal:** BootProof is the default "does-it-boot" check in at least one agent ecosystem.
+
+**The targets:**
+
+1. **A Claude Code skill** — `bootproof-verify` — that an agent can invoke after writing code. The skill runs `bootproof up` on the changed workspace and attaches the Living Receipt to the PR. This is the highest-leverage integration because Claude Code users are the exact audience generating slop.
+
+2. **A Cursor rule** — `.cursorrules` snippet that tells Cursor to run BootProof before declaring a task complete. Distribute as a copy-paste snippet in the README.
+
+3. **A GitHub Action** — `bootproof/bootproof-action@v1` — that runs on every PR, boots the repo, and posts the Living Receipt as a comment. This is the merge-gate moat in its earliest form. Get it into the GitHub Actions marketplace. Be the top result for "boot" and "verify" and "run".
+
+4. **A Devin integration** — reach out to the Devin team. Their agents produce code; BootProof proves it runs. Co-marketing opportunity.
+
+**The pitch to agent builders:**
+
+```
+Your agent writes code and says "done." The human has to trust it.
+BootProof makes the agent prove it — runs the repo, observes health,
+signs a receipt. The human clicks the receipt, it verifies itself,
+they see the actual boot. No more "the agent said it worked" — now
+it's "the agent proved it boots."
+```
+
+**Success metric:** one agent integration shipped and used by at least 10 developers. The Claude Code skill is the most reachable — it's a single file.
+
+---
+
+## Phase 4 — The "Green CI, Dead App" gallery (Week 4+)
+
+**Goal:** a public, indexed gallery of real slop PRs that pass CI but don't boot, each with its Living Receipt.
+
+**This is the content engine.** Every entry is simultaneously:
+- Proof (a real receipt)
+- Propaganda (the contrast with GitHub's green check)
+- Distribution (every receipt links home)
+
+**How to build it:**
+
+1. Find public PRs that pass CI but are reported as "doesn't work" in comments. Search GitHub for `"doesn't work"`, `"won't run"`, `"broken"` in PR comments on popular repos.
+2. Run `bootproof up` on the PR's branch.
+3. Generate a Living Receipt.
+4. Post it to `gallery/` in the repo, with a one-line description: "PR #1234 on repo X — green CI, dead app, BootProof says NOT BOOTED with classified failure Y."
+5. Each gallery entry has its own badge that links to its receipt.
+
+**The viral loop:**
+
+```
+gallery entry → HN/Reddit/Twitter → click → Living Receipt →
+  "Get your own receipt" → npx bootproof up → new receipt →
+  new badge in a new README → new gallery entry → repeat
+```
+
+**Success metric:** 50 gallery entries, each one a real public slop PR with a real receipt. The gallery itself becomes a destination — "the slop museum."
+
+---
+
+## The loop that ties it all together
+
+```
+Phase 1: maintainer #1 (credibility)
+   ↓
+Phase 2: public launch (100 receipts in the wild)
+   ↓
+Phase 3: agent integrations (default-status in one ecosystem)
+   ↓
+Phase 4: gallery (compounding content engine)
+   ↓
+Each receipt → badge in a README → click → new user → new receipt → repeat
+   ↓
+Workflow lock-in (the merge gate) + boot-inference flywheel (each run makes the next inference better)
+   ↓
+The moat. Earned, not built.
+```
+
+---
+
+## What NOT to do (the trap list)
+
+1. **Do not build the hosted runner before Phase 4.** The `neutral_runner_signed` trust level is the cash-cow path, but it's premature. The free local-signed receipt is the distribution weapon. Build the hosted runner when you have 1,000 receipts and someone offers to pay for it.
+
+2. **Do not build the failure-taxonomy dashboard before Phase 4.** The corpus becomes a moat only if each run feeds back into measurably better inference that users feel. Ship the inference improvement first; dashboard it later.
+
+3. **Do not write a blog post about the architecture.** Write a blog post about curl shutting down its bug bounty. The architecture is not the story — the pain is.
+
+4. **Do not rename anything.** "BootProof" is fine. "Living Receipt" is fine. The urge to rename is the cathedral instinct sneaking back in.
+
+5. **Do not wait for the engine to be perfect before launching.** The engine in `scripts/bootproof_up.mjs` is MVP — it handles Node, Rust, Go, Python. That's enough for the first 1,000 receipts. Ship it. Add more stacks based on what users actually ask for.
+
+6. **Do not skip the DM step.** The temptation is to go straight to HN and skip the maintainer-by-maintainer grind. That's the exact skip that has cost every prior launch. The DMs are where you learn whether the artifact lands. HN is where you scale what already works.
+
+---
+
+## The honest gate
+
+None of this is real until **maintainer #1** runs it on a repo they care about and reacts. The Living Receipt in `assets/living-receipt.html` is the artifact. The DM template in Phase 1 is the message. The six stargazers are the warmest leads.
+
+Open the receipt yourself first. Feel the "what the hell" moment. Then attach it to the first DM.
+
+That's the move. Everything else in this playbook is downstream of it.

package/docs/REAL_WORLD_FIXTURES.md

@@ -0,0 +1,105 @@
+# Real-World Fixture Guide
+
+BootProof uses small, synthetic fixtures to preserve lessons from real repository
+testing without copying entire third-party repositories. A fixture captures only
+the structural markers and minimal evidence needed to exercise an inference,
+classification, safety decision, or verification path.
+
+Predictions and examples are not proof. A fixture may show what BootProof should
+infer or classify, but verified boot still requires observed health evidence from
+the application or an explicitly external health endpoint.
+
+## Why Fixtures Stay Small
+
+Whole external repositories are unsuitable test fixtures because they:
+
+- add large, unstable dependency trees;
+- can contain copyrighted implementation details or vendor configuration;
+- may expose secrets, usernames, local paths, or private operational data;
+- change independently of BootProof and make tests nondeterministic; and
+- can tempt tests to execute untrusted setup or orchestration commands.
+
+BootProof fixtures instead use placeholder package names, empty marker files,
+minimal manifests, and short synthetic evidence strings. They should reproduce
+the shape of a failure, not the source repository.
+
+## Coverage Map
+
+The documentation seeds under
+[`examples/registry-seeds/`](examples/registry-seeds/) summarize the current
+real-world coverage:
+
+| Seed | Representative repository class |
+|---|---|
+| `laravel-vite-sqlite` | Laravel backend with Vite assets and local SQLite setup |
+| `rails-bundler` | Rails application with Ruby/Bundler runtime and native extension blockers |
+| `php-composer` | Composer lockfile and vendor bootstrap failures |
+| `go-ollama-service` | Go service with an evidenced command, port, and health contract |
+| `airbyte-abctl-external-orchestrator` | Heavy external orchestration through abctl, kind, Helm, and Kubernetes |
+| `sentry-devenv-direnv` | Large Python/Node hybrid with devenv and direnv setup |
+| `monorepo-ambiguous-health` | Multiple plausible workspaces or health targets |
+| `advertised-port-mismatch` | Process output advertises a different port from the inferred health candidate |
+
+These JSON files use `bootproof/registry-seed-example/v1`. They are
+documentation examples, not signed attestations, importable deterministic
+playbooks, public corpus submissions, or production registry entries.
+
+## Seed Fields
+
+Each seed records:
+
+- structural markers that may be represented by a minimal fixture;
+- expected classifications or inference labels;
+- a conservative safe next step;
+- whether repair is approval-required or refused;
+- whether the application is externally orchestrated;
+- whether the described path can eventually support verified boot or only a
+  failed/diagnostic receipt; and
+- the observed evidence still required before any verified claim.
+
+`repairDisposition: automatic` is reserved for non-mutating behavior. It must
+never be used to authorize silent command execution, host mutation, database
+mutation, or repository patches. Commands and patches remain approval-gated.
+
+## Adding A Fixture Safely
+
+1. Identify the smallest structural markers required for the behavior.
+2. Write synthetic manifests and evidence instead of copying vendor files.
+3. Remove real repository names when they are not necessary to the detector.
+4. Use placeholders for hosts, package names, paths, and versions.
+5. Never include `.env` contents, tokens, credentials, private keys, user data,
+   private hostnames, or username-bearing local paths.
+6. Add a focused test for the intended inference or classifier and at least one
+   nearby case that must not be overclassified.
+7. Keep commands inert in fixtures. Tests must not install tools, start external
+   orchestrators, run migrations, or execute repository setup scripts.
+8. Document whether the safe next step is approval-required or refused.
+9. Require a real health observation before a test or example can represent a
+   verified boot.
+
+Public documentation may name a real repository family when that context is
+useful, but it must not reproduce vendor config blobs, source files, private
+incident data, or proprietary runbooks. Evidence strings should be the minimum
+short patterns needed to explain classifier behavior.
+
+## Evidence And Honesty
+
+Classifiers must remain evidence-based and conservative. A marker can justify an
+inference, and an exact failure string can justify a failure class, but neither
+proves that the application booted.
+
+BootProof may record a failed or diagnostic receipt when setup is incomplete,
+orchestrator ownership is external, a workspace is ambiguous, or a health
+candidate is wrong. It may report verified boot only after observed health
+evidence satisfies the health contract.
+
+For external orchestration, BootProof must state that it verified an
+already-running service and must not claim that it started the application.
+
+## Registry Boundary
+
+Seed examples are local documentation only. Reading or testing them performs no
+network calls, telemetry, upload, registry submission, Cloud API request, or
+automatic file mutation. To produce a real redacted registry entry, use the
+explicit local export workflow described in [REGISTRY.md](REGISTRY.md).
+

package/docs/REGISTRY.md

@@ -1,49 +1,69 @@
-# Git-Native Registry Design
+# Registry Export Formats
 
-BootProof does not operate a public registry service today.
+BootProof supports local, redacted registry artifacts. It does not operate a public index from
+this repository, upload evidence automatically, or call a registry service.
 
-The current primitive is portable signed evidence:
+Create a local entry explicitly:
 
-```text
-.bootproof/attestation.json
+```bash
+bootproof registry export .
 ```
 
-Projects may deliberately commit that file or export a redacted entry:
+This writes `.bootproof/registry-entry.json` using
+`bootproof/registry-entry/v1`. `bootproof attest export .` remains a compatibility alias.
 
-```bash
-bootproof attest export .
-```
+## Public/Federated Registry
 
-This writes:
+Public repositories may explicitly create a public-candidate wrapper:
 
-```text
-.bootproof/registry-entry.json
+```bash
+bootproof registry export . --federated
 ```
 
-Nothing is uploaded automatically.
+This writes a redacted, signed `bootproof/federated-receipt/v1` artifact under
+`.bootproof/registry/`. A repository owner may review and deliberately commit that receipt to
+the repository's own Git history.
+
+A future BootProof indexer could crawl public receipts, verify signatures, and build an open
+commons of verified boot, failure, and repair knowledge. The crawler and public index do not
+exist in this repository and are not implemented by this command.
 
-## Intended Design
+`bootproof attest check` distinguishes this machine's signer, explicitly pinned known signers,
+and unknown foreign signers. Signature integrity alone does not establish authorship.
 
-The proposed registry model is federated:
+## Private Cloud Registry
 
-- write path: repositories deliberately publish signed proof through Git
-- read path: a future index discovers public attestations, verifies signatures, and links claims to source commits
-- failure corpus: classified failures improve detectors without converting failures into success claims
+Organisations may later explicitly upload redacted attestations and repair receipts to
+BootProof Cloud. Private repository data would remain governed, tenant-isolated, and paid.
 
-The index, badge service, freshness tracking, and signer trust graph are roadmap items. They are not deployed capabilities.
+This repository only supports producing a `cloud_upload_candidate` local export. BootProof
+Cloud, upload transport, billing, governance, and hosted registry storage are intentionally
+not implemented here.
 
 ## Consent And Privacy
 
-1. BootProof sends no telemetry or hidden evidence upload.
-2. Sharing requires a visible local artifact and an explicit user action.
-3. Full local attestations may contain raw failure evidence.
-4. Registry export applies redaction and records which redactions were used.
-5. A future index should trust only valid signatures and public evidence.
+1. Every registry entry has `optInRequired: true`; federated wrappers contain that entry.
+2. Export builders perform no network calls and do not upload telemetry or evidence.
+3. Files are written only after an explicit export command.
+4. Raw environment values, tokens, private keys, protected `.env` contents, and local username
+   paths are excluded or redacted.
+5. Repository owner and name identifiers are hashed; a public repository URL is included only
+   when it is a credential-free URL on a supported public Git host.
+6. Full local attestations may contain raw evidence and should not be treated as public exports.
+
+The strict schemas are:
 
-Repository commands executed by BootProof may access the network independently. The no-upload promise applies to BootProof's own telemetry and evidence handling, not arbitrary install or application commands.
+- [`schemas/registry-entry-v1.schema.json`](schemas/registry-entry-v1.schema.json)
+- [`schemas/federated-receipt-v1.schema.json`](schemas/federated-receipt-v1.schema.json)
 
-## Trust
+## Documentation Seeds
 
-Current attestations are `local_developer_signed`.
+Small synthetic examples of the real-world classifier and inference coverage live
+under [`examples/registry-seeds/`](examples/registry-seeds/). They use the
+documentation-only
+[`registry-seed-example-v1` schema](schemas/registry-seed-example-v1.schema.json)
+and are explained in [REAL_WORLD_FIXTURES.md](REAL_WORLD_FIXTURES.md).
 
-CI/OIDC-backed proof will be stronger because a verifier can bind the signature to a repository workflow identity. BootProof does not claim that trust level yet.
+These examples are not attestations, proof, upload requests, or production
+registry entries. They contain no network behavior and are never submitted
+automatically.