bootprint 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4d4c97b0a32461ce90a144849e6fb9c1416682f0b682039cd5e89cfb2d2ca171
+  data.tar.gz: d228014f4dca8d75d8aa03eab9b343e8ee0a9449e5cc8e50220c91549a305803
+SHA512:
+  metadata.gz: ae4e15f6cd2655c988c3f7b845d417240e433b8e1384c5145b984bc0c243fbb0ad10c5fd09fb93cd8c38570b0682538a459e98db931a77c43c16686bf2963d71
+  data.tar.gz: 7070a15b2d7a82018cb526c9b0fad201ea8259f87a6daa63641ad5be745fe9eee899348c33f41d1f80879e2a103cb6f3a89444eb65b839ec70660e587b76cc5c

data/.bootprint.yml.example

@@ -0,0 +1,37 @@
+version: 1
+
+mode: permissive
+minimum_severity: warning
+fail_on:
+  - error
+  - critical
+
+ignore:
+  - ruby-patch-level-drift
+
+expected_platforms:
+  - x86_64-linux
+
+allow:
+  environment_variables:
+    - OPTIONAL_ANALYTICS_KEY
+  paths:
+    - environment.operating_system.processors
+
+rules:
+  missing-environment-variable:
+    severity: critical
+  bundler-version-drift:
+    severity: warning
+
+redaction:
+  patterns:
+    - TOKEN
+    - SECRET
+    - PASSWORD
+    - PRIVATE_KEY
+  safe_list:
+    - PUBLIC_TOKEN_NAME
+
+plugins:
+  strict: false

data/ARCHITECTURE.md

@@ -0,0 +1,46 @@
+# Architecture
+
+Bootprint is a local-first Ruby gem with no runtime dependencies beyond Ruby standard libraries.
+
+## Data flow
+
+```text
+Collectors / plugins
+        ↓
+recursive sanitization
+        ↓
+schema-v2 snapshot ──→ deterministic JSON
+        ↓
+rules + project policy
+        ↓
+structured findings
+        ↓
+human / JSON / SARIF / Markdown / CI annotations
+```
+
+## Boundaries
+
+- `Bootprint::Snapshot` coordinates collectors, migration, validation, deterministic ordering, and persistence.
+- `Bootprint::Schema` owns the current version and migrates schema v1 in memory while preserving unknown top-level fields under `extensions`.
+- Collectors return JSON-safe hashes and do not perform network requests.
+- `Bootprint::Sanitizer` recursively strips credential-bearing URLs, token-like values, private keys, secret-named fields, and identifying paths.
+- `Bootprint::Rules::Rule` defines detection, explanation, metadata, severity, references, source location, and remediation contracts.
+- `Bootprint::Diagnosis` evaluates rules and produces a stable report independent of presentation.
+- `Bootprint::Policy` validates project control with safe YAML loading and line-aware errors.
+- Formatters contain no detection logic.
+- Docker and security-audit code are lazy-loaded by their CLI commands.
+- Rails hooks load only when `Rails::Railtie` already exists; expensive profiling requires `BOOTPRINT_PROFILE_BOOT=1`.
+
+## Plugin contract
+
+Plugin API version `1` accepts a collector class responding to `.capture` or `#capture`, and a rules module responding to `.install` or `.register`. Collector output crosses the same recursive-redaction boundary as core data. Exceptions are converted to snapshot warnings unless strict mode is active.
+
+Plugins cannot inject executable content into snapshots. Registering a plugin is equivalent to requiring trusted Ruby code and therefore remains an application-level trust decision.
+
+## Performance model
+
+The standard capture path uses in-process APIs, file metadata, and `PATH` presence checks. It performs no package-manager calls, remote resolution, or Docker inspection. Comparison is an in-memory traversal. Optional Rails and Docker work stays out of ordinary CLI startup.
+
+## Exit-code ownership
+
+CLI parsing/policy errors use `2`, snapshot/schema errors use `3`, and subsystem/internal failures use `4`. Diagnosis reports determine whether `1` applies from policy `fail_on`; presentation formats do not affect enforcement.

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to Bootprint are documented here. The project follows Semantic Versioning before and after 1.0 where practical.
+
+## 0.2.0 - 2026-08-02
+
+### Added
+
+- Stable snapshot schema v2 with deterministic output, v1 migration, inspection, validation, and safe migration commands.
+- Formal rule DSL and 39 built-in compatibility rules with cause, impact, evidence, severity, and remediation.
+- `diagnose`, `fix --dry-run`, policy, snapshot, Docker, CI, and security-audit commands.
+- Human, JSON report-schema v1, SARIF 2.1, and Markdown output.
+- Strict/permissive `.bootprint.yml` policies with rule controls, expected platforms, optional variables, and redaction patterns.
+- Expanded Rails configuration inspection, opt-in initializer profiling, and Rails tasks.
+- Read-only, network-disabled Docker image capture.
+- Plugin API v1 with isolated failures.
+- Recursive privacy hardening and strict privacy mode.
+- Cross-platform fixtures, subprocess integration tests, CI matrix, examples, and public contributor documentation.
+- Original Bootprint brand mark, packaged logo assets, README badges, and expanded product and workflow documentation.
+- Release package validation, installed-gem smoke tests, GitHub security automation, and OIDC-based RubyGems trusted publishing.
+- Focused four-job compatibility CI, grouped monthly dependency updates, and a weekly/manual security audit to reduce workflow noise.
+- Presence-only handling for secret-named environment variables across the sanitizer and snapshot schema boundary.
+
+## 0.1.0 - 2026-08-02
+
+- Added sanitized runtime capture, comparison, initial diagnostics, Rails collection, CI verification, reports, allowed differences, and the first rule DSL.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of Conduct
+
+We are committed to a respectful, harassment-free project for everyone. Be constructive, assume good intent while addressing concrete behavior, respect privacy, and avoid publishing another person's sensitive environment data.
+
+Unacceptable conduct includes harassment, threats, discriminatory language, deliberate disruption, or disclosure of private information. Maintainers may edit or remove contributions and restrict participation to protect the community.
+
+Report conduct concerns privately to `conduct@magnexis.com`. Reports will be reviewed confidentially and fairly.

data/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Thank you for improving Bootprint. Open an issue before large architectural work. Keep the project focused on Ruby runtime reproducibility and local-first diagnosis. By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Setup
+
+The repository pins the maintainer runtime in `.ruby-version`; the gem itself supports Ruby 3.1 and newer.
+
+```console
+bundle install
+bundle exec rake check
+```
+
+Use a focused branch created from `main`. Keep commits reviewable and do not mix generated snapshots, local package artifacts, or unrelated formatting with a behavior change.
+
+## Pull requests
+
+Describe the failing environment scenario, the compatibility decision being encoded, and the sanitized evidence used to verify it. Complete the pull-request checklist and call out platform behavior you could not test.
+
+Changes to rules require success, no-match, suppression, evidence, and remediation tests. Schema changes require migration and future-schema tests. Security changes require both redaction and false-positive coverage. Docker tests must never inspect unrelated containers or require network access.
+
+Do not include real production snapshots, credentials, customer names, or proprietary paths in fixtures. Use the existing synthetic platform fixtures.
+
+Pull requests should update documentation and `CHANGELOG.md`, remain compatible with Ruby 3.1+, and avoid new runtime dependencies unless clearly justified.
+
+## Releases
+
+Maintainers should follow [RELEASE.md](RELEASE.md). Pull requests must not publish gems, create tags, or add long-lived package credentials.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 theworker02
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,422 @@
+<p align="center">
+  <img src="assets/branding/bootprint-logo-512.png" alt="Bootprint fingerprint and environment-drift logo" width="180">
+</p>
+
+<h1 align="center">Bootprint</h1>
+
+<p align="center"><strong>Reproduce the environment, not just the dependencies.</strong></p>
+
+<p align="center">
+  <a href="https://github.com/theworker02/bootprint/actions/workflows/test.yml"><img alt="Test status" src="https://github.com/theworker02/bootprint/actions/workflows/test.yml/badge.svg"></a>
+  <img alt="Bootprint 0.2.0" src="https://img.shields.io/badge/version-0.2.0-CC342D">
+  <img alt="Ruby 3.1 or newer" src="https://img.shields.io/badge/Ruby-%E2%89%A5%203.1-CC342D?logo=ruby&logoColor=white">
+  <img alt="Snapshot schema version 2" src="https://img.shields.io/badge/snapshot_schema-v2-3977F6">
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-171A21"></a>
+</p>
+
+Bootprint is a local-first Ruby runtime fingerprint and compatibility diagnostic. It captures a sanitized description of an application environment, compares that description with CI, Docker, staging, or production, and turns raw drift into explanations, severity, evidence, remediation, and enforceable policy.
+
+```console
+gem install bootprint
+bootprint capture local
+bootprint docker capture myapp:latest
+bootprint diagnose local myapp-latest
+```
+
+Bootprint 0.2 combines a dependency compatibility analyzer, Rails boot inspector, environment-drift detector, and CI policy engine. Ordinary capture performs no network requests, suggested commands never execute automatically, and environment-variable values are never recorded.
+
+## Contents
+
+- [Why Bootprint](#why-bootprint)
+- [What it inspects](#what-it-inspects)
+- [Five-minute start](#five-minute-start)
+- [From capture to diagnosis](#from-capture-to-diagnosis)
+- [Command reference](#command-reference)
+- [Policy enforcement](#policy-enforcement)
+- [Rails inspection](#rails-inspection)
+- [Docker comparison](#docker-comparison)
+- [CI integration](#ci-integration)
+- [Reports and remediation](#reports-and-remediation)
+- [Rules and plugins](#rules-and-plugins)
+- [Privacy and security](#privacy-and-security)
+- [Platform support and performance](#platform-support-and-performance)
+- [Documentation](#documentation)
+- [Development](#development)
+
+## Why Bootprint
+
+`Gemfile.lock` captures dependency resolution, but not the complete runtime contract. Ruby engine and patch level, native clients, libc, CPU architecture, Rails adapters, required configuration, filesystem behavior, and initializer ordering can all change application behavior.
+
+Bootprint records those facts as deterministic schema-v2 JSON and evaluates them with 39 independently testable built-in rules. A finding answers four questions that a plain diff cannot:
+
+1. What changed?
+2. How dangerous is it?
+3. What is the likely impact?
+4. What should the developer do next?
+
+```text
+CRITICAL   Native extension platform mismatch
+           nokogiri targets arm64-darwin but production uses x86_64-linux.
+
+           Recommended fix:
+           $ bundle lock --add-platform x86_64-linux
+           $ bundle install
+
+ERROR      Required environment variable is missing
+           REDIS_URL is available locally but absent in production.
+```
+
+### At a glance
+
+| Capability | Bootprint 0.2 |
+|---|---|
+| Diagnostic knowledge | 39 built-in rules across runtime, dependencies, native libraries, configuration, filesystem, and Rails boot |
+| Severity model | `info`, `warning`, `error`, `critical` |
+| Report formats | Human terminal output, JSON, SARIF 2.1, Markdown |
+| Snapshot contract | Deterministic schema v2 with in-memory v1 migration |
+| Policy | Ignore, enable, disable, override severity, declare optional variables, require platforms |
+| Integrations | Rails, Docker, GitHub Actions, GitLab CI, CircleCI, generic POSIX CI |
+| Runtime dependencies | None |
+| Data flow | Local only; no upload service or telemetry |
+
+## What it inspects
+
+| Area | Captured metadata |
+|---|---|
+| Ruby runtime | Version, engine, patch level, platform, architecture, build description |
+| Dependency system | Bundler and RubyGems versions, lockfile platforms, resolved gems, sources, checksums, native extensions |
+| Native libraries | OpenSSL, libyaml, SQLite, PostgreSQL, MySQL, libc, compiler and header availability when detectable |
+| Configuration | Environment-variable names and presence, Rails environment, adapters, framework settings |
+| Filesystem | Temporary/log path availability, writability, path separators, case sensitivity, symlink behavior |
+| Rails boot | Framework configuration, autoload/eager-load paths, initializers, and opt-in initializer timings |
+| Docker | Image runtime, platforms, installed package metadata when available, workdir, entrypoint, command, permissions |
+
+Bootprint deliberately does **not** collect credential values, database passwords, API tokens, cookies, session contents, full connection URLs, user data, or application source. Strict privacy mode additionally omits or normalizes hostnames, usernames, home paths, and process identifiers.
+
+## Five-minute start
+
+Add Bootprint to a project:
+
+```ruby
+group :development, :test do
+  gem "bootprint", require: false
+end
+```
+
+Install and capture a named local baseline:
+
+```console
+bundle install
+bundle exec bootprint capture local
+```
+
+Capture another environment and diagnose the difference:
+
+```console
+bundle exec bootprint capture production
+bundle exec bootprint diagnose local production
+```
+
+Named captures live at `.bootprint/NAME.json`. An unnamed capture writes `bootprint.lock`:
+
+```console
+bundle exec bootprint capture
+bundle exec bootprint verify --against bootprint.lock
+```
+
+Use strict privacy when a snapshot may be attached to an issue or shared outside the team:
+
+```console
+bundle exec bootprint capture support-case --privacy strict
+bundle exec bootprint security audit .bootprint/support-case.json
+```
+
+## From capture to diagnosis
+
+```text
+Ruby process / Rails app / Docker image
+                  |
+                  v
+        sanitized collectors
+                  |
+                  v
+      deterministic schema-v2 snapshot
+                  |
+            source + target
+                  |
+                  v
+       rules + .bootprint.yml policy
+                  |
+                  v
+ human | JSON | SARIF | Markdown + stable exit code
+```
+
+For example, compare a local macOS Rails environment with a Linux production image:
+
+```console
+# macOS development machine
+bundle exec bootprint capture macos-development
+
+# Local Docker image; no port or running container is required
+bundle exec bootprint docker capture ghcr.io/example/storefront:latest
+
+# Explain only warning-or-higher runtime and dependency findings
+bundle exec bootprint diagnose macos-development storefront-latest \
+  --only runtime,dependencies \
+  --minimum-severity warning
+```
+
+Raw `diff` remains available when every changed value matters. `diagnose` is the normal workflow because it applies compatibility knowledge and policy.
+
+## Command reference
+
+| Command | Purpose |
+|---|---|
+| `bootprint capture [NAME]` | Capture a deterministic, sanitized schema-v2 snapshot |
+| `bootprint diff SOURCE TARGET` | Show every raw environment difference |
+| `bootprint diagnose SOURCE TARGET` | Explain compatibility findings and remediation |
+| `bootprint diagnose --against PATH` | Compare the current process with a reference snapshot |
+| `bootprint doctor` | Diagnose the health of the current environment |
+| `bootprint verify --against PATH` | Enforce policy and return CI-safe exit codes |
+| `bootprint fix --dry-run` | Preview remediation without changing files or running commands |
+| `bootprint docker capture IMAGE` | Inspect a local image in an isolated temporary container |
+| `bootprint docker compare IMAGE` | Show raw drift between the current environment and an image |
+| `bootprint docker diagnose IMAGE` | Diagnose current-environment versus image compatibility |
+| `bootprint ci verify` | Detect CI, emit native annotations, and enforce policy |
+| `bootprint snapshot inspect PATH` | Inspect snapshot metadata safely |
+| `bootprint snapshot validate PATH` | Validate schema and snapshot structure |
+| `bootprint snapshot migrate PATH` | Migrate a legacy snapshot into a new file |
+| `bootprint policy validate` | Validate policy with path and line-aware errors |
+| `bootprint policy explain` | Display the effective merged policy |
+| `bootprint security audit PATH` | Check an existing snapshot for likely sensitive values |
+
+Diagnosis supports `--format human|json|sarif|markdown`, `--only CATEGORY,...`, and `--minimum-severity LEVEL`. Color is disabled when output is redirected or `NO_COLOR` is set.
+
+## Policy enforcement
+
+Copy `.bootprint.yml.example` to `.bootprint.yml` and tailor it:
+
+```yaml
+version: 1
+mode: permissive
+minimum_severity: warning
+fail_on: [error, critical]
+
+expected_platforms: [x86_64-linux]
+ignore: [ruby-patch-level-drift]
+
+allow:
+  environment_variables: [OPTIONAL_ANALYTICS_KEY]
+
+rules:
+  missing-environment-variable:
+    severity: critical
+
+redaction:
+  patterns: [TOKEN, SECRET, PASSWORD, PRIVATE_KEY]
+```
+
+Policies can disable rules, override severity, acknowledge known differences, declare optional environment variables, define deployment platforms and redaction patterns, and select strict or permissive behavior. Validate before CI enforcement:
+
+```console
+bundle exec bootprint policy validate
+bundle exec bootprint policy explain
+bundle exec bootprint verify --against bootprint.lock
+```
+
+Exit codes are stable:
+
+| Code | Meaning |
+|---:|---|
+| 0 | No blocking findings |
+| 1 | Policy violation |
+| 2 | Invalid command or policy |
+| 3 | Invalid or unsupported snapshot |
+| 4 | Docker, plugin, filesystem, or internal failure |
+
+## Rails inspection
+
+Bootprint lazily loads Rails integration only after Rails is present. Normal application startup is not profiled unless inspection is explicitly enabled.
+
+```console
+BOOTPRINT_INSPECT=1 bin/rails bootprint:capture
+bin/rails bootprint:doctor
+BOOTPRINT_PROFILE_BOOT=1 bundle exec rails runner "Bootprint.capture.write('bootprint.lock')"
+```
+
+Rails capture includes the version and environment, framework defaults, eager loading, cache classes, paths, database/queue/cache/session adapters, Active Storage, Action Cable, mail delivery, time zone, logging, public-file serving, assets, and initializer order.
+
+Opt-in profiling records initializer start and completion order, duration, exception metadata, newly loaded constant names, and a conservative network-operation heuristic. It never captures credentials, connection URLs, cookie contents, session contents, or user data.
+
+## Docker comparison
+
+Docker inspection requires a local image containing Ruby. Bootprint checks that the image already exists, then runs a read-only, network-disabled `--rm` container with a fixed inspection script.
+
+```console
+bootprint docker capture myapp:latest
+bootprint docker diagnose myapp:latest --against local
+```
+
+Bootprint does not pull images, expose ports, persist temporary containers, inspect unrelated running containers, or upload captured data. If Docker is missing or unavailable, the CLI reports that condition with exit code 4.
+
+## CI integration
+
+Commit a trusted `bootprint.lock` and enforce it in pull requests:
+
+```yaml
+name: Bootprint
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  environment-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - run: bundle exec bootprint ci verify --against bootprint.lock
+```
+
+`bootprint ci verify` detects GitHub Actions, GitLab CI, CircleCI, and generic POSIX CI environments. GitHub output includes workflow annotations and a Markdown job summary; SARIF output can be consumed by GitHub code scanning without inventing file locations.
+
+## Reports and remediation
+
+Machine-readable JSON contains report schema version, source and target metadata, findings, evidence, remediation, suppression state, and execution metadata:
+
+```console
+bootprint diagnose local production --format json > bootprint-report.json
+bootprint diagnose local production --format sarif > bootprint.sarif
+bootprint diagnose local production --format markdown > bootprint-report.md
+```
+
+Every actionable finding can include safe, structured repair guidance:
+
+```json
+{
+  "rule_id": "missing-lockfile-platform",
+  "severity": "error",
+  "evidence": {
+    "current_platforms": ["arm64-darwin"],
+    "required_platforms": ["x86_64-linux"]
+  },
+  "remediation": {
+    "summary": "Add the deployment platform to the lockfile and rebuild the bundle.",
+    "commands": [
+      "bundle lock --add-platform <required-platform>",
+      "bundle install"
+    ],
+    "files": ["Gemfile.lock"]
+  }
+}
+```
+
+`bootprint fix --dry-run` renders those changes as a preview. Diagnosis and preview never execute remediation commands or modify application files.
+
+## Rules and plugins
+
+Rules use a structured DSL and load without Rails:
+
+```ruby
+Bootprint::Rules.define "redis-client-drift" do
+  name "Redis client mismatch"
+  category :dependencies
+  severity :warning
+
+  detect do |source, target|
+    source.dig("plugins", "redis") != target.dig("plugins", "redis")
+  end
+
+  explain do |_source, _target, evidence|
+    { summary: "Redis clients differ.", evidence: evidence }
+  end
+
+  remediate "Pin the same redis-client release in Gemfile.lock.",
+            files: ["Gemfile.lock"]
+end
+```
+
+Third-party gems can package collectors and rules behind plugin API version 1:
+
+```ruby
+Bootprint::Plugin.api_version "1"
+
+Bootprint::Plugins.register "sidekiq" do
+  collector SidekiqBootprint::Collector
+  rules SidekiqBootprint::Rules
+end
+```
+
+A broken plugin becomes a warning and does not prevent core capture unless strict policy mode is enabled. See [Writing custom rules](docs/custom-rules.md) and [Creating plugins](docs/plugins.md) for the compatibility contract.
+
+## Privacy and security
+
+Environment inspection is sensitive, so Bootprint applies defensive handling at collection and serialization boundaries:
+
+- Environment variables are represented by name and presence only.
+- Recursive redaction detects secret-like names, credentials in URLs, authorization headers, private keys, JWT-like tokens, database connection strings, and high-entropy values.
+- Home paths are normalized; strict mode removes further host and process identity.
+- Unknown snapshot fields are preserved where practical during migration, then audited like known fields.
+- Standard capture performs no network requests and enables no telemetry.
+- Suggested shell commands remain inert data.
+
+Before sharing any snapshot, run:
+
+```console
+bootprint security audit bootprint.lock
+```
+
+Security issues should follow the private reporting process in [SECURITY.md](SECURITY.md), not a public issue containing a snapshot.
+
+## Platform support and performance
+
+The focused automated matrix covers the oldest supported MRI release on Linux and Ruby 3.4 on Linux, macOS, and Windows. Fixture coverage includes macOS development, Linux CI, Docker production, Windows development, ARM64 development, x86-64 deployment, Rails, and plain Ruby projects.
+
+Bootprint is designed around these practical limits:
+
+| Operation | Target |
+|---|---:|
+| Core CLI startup | Under 250 ms where practical |
+| Standard Ruby snapshot | Under 1 second |
+| Rails inspection | Under 3 seconds, excluding application boot |
+| Ordinary snapshot comparison | Under 500 ms |
+
+Rails, Docker, SARIF, and plugin code are lazy-loaded so basic CLI use does not pay for integrations it does not invoke. Performance varies with Ruby, filesystem, dependency count, and host load.
+
+## Documentation
+
+- [Installation](docs/installation.md)
+- [Five-minute quick start](docs/quick-start.md)
+- [Capturing environments](docs/capturing.md)
+- [Comparing environments](docs/comparing.md)
+- [Understanding findings](docs/findings.md)
+- [Policy configuration](docs/policy.md)
+- [Rails integration](docs/rails.md)
+- [Docker support](docs/docker.md)
+- [CI integration](docs/ci.md)
+- [Writing custom rules](docs/custom-rules.md)
+- [Creating plugins](docs/plugins.md)
+- [Privacy and redaction](docs/privacy.md)
+- [Snapshot schema](docs/snapshot-schema.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Maintainer setup](docs/maintainer-setup.md)
+
+## Development
+
+```console
+bundle install
+bundle exec rake test
+bundle exec rubocop lib test exe Rakefile bootprint.gemspec
+gem build bootprint.gemspec
+```
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, [ARCHITECTURE.md](ARCHITECTURE.md) for system boundaries, and [RELEASE.md](RELEASE.md) for packaging and signed-release instructions.
+
+## Status and limitations
+
+Bootprint 0.2 is local-first and pre-1.0. It diagnoses captured facts; it does not guarantee perfect binary compatibility, query remote gem indexes during capture, execute suggested repairs, or provide malware isolation. Yanked-gem detection uses metadata supplied by snapshots or trusted plugins because standard capture deliberately avoids network access.
+
+Bootprint is released under the [MIT License](LICENSE).

data/RELEASE.md

@@ -0,0 +1,78 @@
+# Release process
+
+Bootprint releases are built from an immutable `vVERSION` Git tag and published through RubyGems Trusted Publishing. The workflow uses GitHub OIDC to obtain a short-lived, gem-scoped credential; no long-lived RubyGems API key belongs in GitHub secrets.
+
+## One-time maintainer setup
+
+1. Create the public GitHub repository at `theworker02/bootprint` with `main` as its default branch.
+2. Apply the repository controls in [docs/maintainer-setup.md](docs/maintainer-setup.md).
+3. Create a RubyGems.org account, enable MFA for UI and API operations, and verify the account email.
+4. On RubyGems.org, create a pending trusted publisher for the new `bootprint` gem with:
+   - GitHub owner: `theworker02`
+   - repository: `bootprint`
+   - workflow: `release.yml`
+   - environment: `release`
+5. In GitHub, create a protected environment named `release`, restrict it to tags matching `v*`, and require a maintainer review before deployment.
+
+RubyGems supports pending trusted publishers for a gem's first release. Recheck that the `bootprint` name is still available immediately before the initial tag is pushed.
+
+## Prepare a release
+
+1. Update `Bootprint::VERSION` in `lib/bootprint/version.rb`.
+2. Add a dated entry to `CHANGELOG.md` using the exact version.
+3. Update version-specific README text and badges when necessary.
+4. Run the full local gate:
+
+   ```console
+   bundle install
+   bundle exec rake release_check
+   ```
+
+5. Inspect and smoke-test the generated package:
+
+   ```console
+   gem specification pkg/bootprint-VERSION.gem
+   gem install pkg/bootprint-VERSION.gem --install-dir tmp/gem-home --bindir tmp/gem-bin --no-document
+   GEM_HOME="$PWD/tmp/gem-home" GEM_PATH="$PWD/tmp/gem-home" tmp/gem-bin/bootprint --version
+   ```
+
+6. Audit the staged Git diff for credentials, private snapshots, generated packages, absolute user paths, and unrelated files.
+7. Commit the release changes. Do not tag a dirty or unreviewed tree.
+
+## Publish
+
+Create and push a signed tag only after the `main` branch checks pass:
+
+```console
+git tag -s vVERSION -m "Bootprint VERSION"
+git push origin vVERSION
+```
+
+The tag starts `.github/workflows/release.yml`, which:
+
+1. verifies the tag matches `Bootprint::VERSION` and `CHANGELOG.md`;
+2. runs tests and RuboCop;
+3. builds, installs, and smoke-tests a preflight `.gem` from the tagged source;
+4. pauses at the protected `release` environment;
+5. rebuilds and publishes through the official RubyGems OIDC action;
+6. prints the published package's SHA-256 digest; and
+7. creates a GitHub release with that same package attached.
+
+For 0.2.0, use the release title `Bootprint 0.2 — From Environment Differences to Actionable Diagnoses` when editing the generated GitHub release notes.
+
+## Verify after publication
+
+```console
+gem install bootprint -v VERSION
+bootprint --version
+bootprint help
+gem owner bootprint
+```
+
+Confirm the RubyGems page shows the correct links, MIT license, Ruby requirement, MFA requirement, checksum, owners, and trusted publisher. Confirm the GitHub release attachment has the same SHA-256 digest as the workflow output.
+
+## Emergency and manual release policy
+
+Prefer rerunning a failed trusted-publishing job. A manual `gem push` is an emergency fallback only and must use an MFA-protected, least-privilege RubyGems API key from an approved maintainer workstation. Never store that key, an OTP, or a signing private key in the repository, workflow variables, shell history, or issue attachments.
+
+RubyGems certificate signing is optional and separate from signed Git tags and OIDC publishing. If enabled later, keep the private key offline, commit only the public certificate, configure `spec.cert_chain`, and document how consumers verify it before making signed packages mandatory.