springdocker 1.0.3__tar.gz → 1.1.0__tar.gz

{springdocker-1.0.3/src/springdocker.egg-info → springdocker-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springdocker
-Version: 1.0.3
+Version: 1.1.0
 Summary: CLI for Spring Boot Dockerfile and benchmark workflows (Maven/Gradle).
 Author: springdocker contributors
 License:                                  Apache License
@@ -220,6 +220,7 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: ruff>=0.6.0; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-Jinja2; extra == "dev"
 Requires-Dist: requests>=2.32; extra == "dev"
 Dynamic: license-file
 
@@ -227,19 +228,20 @@ Dynamic: license-file
 
 CLI for Spring Boot Dockerfile and benchmark workflows across Maven and Gradle projects.
 
+Product scope and CI-evidenced guarantees: [`docs/POSITIONING.md`](../docs/POSITIONING.md).
+
 ## Install
 
-### Local editable
+**Primary path:** install from PyPI and run against your Spring Boot project. Clone the repository only for benchmarks on the sample app or for development ([ADR 0006](../docs/adr/0006-pypi-first-distribution.md)).
 
-```bash
-python3 -m pip install -e .
-```
-
-### pipx
+### pipx (recommended)
 
 ```bash
 pipx install springdocker
 springdocker --help
+
+# optional: benchmark run/analyze (requires Docker)
+pipx install 'springdocker[benchmark]'
 ```
 
 Upgrade:
@@ -254,20 +256,38 @@ pipx upgrade springdocker
 uv tool install springdocker
 uv tool upgrade springdocker
 
-# benchmark/evidence commands need optional extras
-python3 -m pip install -e '.[benchmark]'
+# benchmark extra
+uv tool install 'springdocker[benchmark]'
+```
+
+### pip
+
+```bash
+python3 -m pip install springdocker
+python3 -m pip install 'springdocker[benchmark]'
+```
+
+### From source (contributors)
+
+```bash
+git clone https://github.com/mnafshin/springdocker.git
+cd springdocker
+python3 -m pip install -e ".[dev]"
 ```
 
 ## Quick usage
 
 ```bash
 springdocker init --project-root samples/java-spring-docker --build-tool maven --profile quick
+springdocker configure --project-root samples/java-spring-docker --force   # interactive → writes [dockerfile] in config
+springdocker dockerfile generate --project-root samples/java-spring-docker  # non-interactive; reads .springdocker.toml
 springdocker doctor --project-root samples/java-spring-docker
 springdocker inspect --project-root samples/java-spring-docker --format json
 springdocker explain --project-root samples/java-spring-docker Dockerfile.generated --format json
 springdocker benchmark compare --project-root samples/java-spring-docker benchmarks/03-custom-jre-jlink/results/raw.csv --baseline-variant with-jlink-runtime --format json
 springdocker dockerfile generate --project-root samples/java-spring-docker --output Dockerfile.generated --recipe jvm-balanced
 springdocker dockerfile generate --project-root samples/java-spring-docker --recipe spring-aot
+# native-aot emits experimental scaffold output only (not a production workflow)
 springdocker dockerfile generate --project-root samples/java-spring-docker --recipe native-aot
 springdocker benchmark generate --project-root samples/java-spring-docker --java-version 25
 springdocker benchmark run --project-root samples/java-spring-docker --profile quick --runner-arg --skip-native
@@ -278,7 +298,89 @@ springdocker benchmark analyze --project-root samples/java-spring-docker benchma
 ```
 
 Benchmark commands are optional evidence workflows and require benchmark extras.
-Use `samples/java-spring-docker/benchmarks/reference/v1/summary.json` as a versioned baseline example.
+Use `samples/java-spring-docker/benchmarks/06-base-image-choice/results/baseline.json` as the versioned CI regression baseline example (paired with committed `raw.csv`).
+Scenario index: [README.md](../README.md#benchmark-scenario-index).
+
+## Dockerfile recipes
+
+| Recipe | Status | Default runtime | Notes |
+|---|---|---|---|
+| `jvm-balanced` | Supported | **distroless** + jlink | Default production-oriented JVM Dockerfile. |
+| `spring-aot` | Supported | **distroless** + jlink | Spring Boot AOT processing on a JVM runtime. |
+| `native-aot` | Scaffold only | **distroless** base (static binary) | Experimental GraalVM native-image Dockerfile output. Not a production-ready workflow; see `docs/native-image-roadmap.md`. |
+
+The generator sets `runtime_image = "distroless"` internally for JVM recipes. That means `distroless/base-debian*` plus a copied jlink runtime — not the prebuilt `distroless/java*` image and not a full OS layer unless you change generator options (benchmark scenario **06** compares OS bases).
+
+### Runtime bases and HEALTHCHECK
+
+| Runtime | Generator behavior |
+|---|---|
+| `distroless` (default) | Non-root, minimal base + jlink; **no `HEALTHCHECK`** (no shell/`wget` in the image). Probe readiness from the orchestrator (e.g. Kubernetes `readinessProbe` on `/actuator/health/readiness`). |
+| `debian-slim`, `alpine`, `ubuntu`, `temurin` | Full OS or vendor JRE paths; **`HEALTHCHECK` is emitted** when Spring Boot Actuator is on the classpath. |
+
+Supported runtime names: `distroless`, `debian-slim`, `alpine`, `ubuntu`, `temurin` (plus aliases such as `debian-bookworm-slim`, `eclipse-temurin-jre`). Set via `[dockerfile].runtime_image` in `.springdocker.toml` or `--runtime-image` on `dockerfile generate`.
+
+## Config-first workflow
+
+`.springdocker.toml` is the **single source of truth** for Dockerfile generation (see [ADR 0005](../docs/adr/0005-config-first-dockerfile-generation.md)). Team rollout guide: [docs/team-adoption.md](../docs/team-adoption.md).
+
+### Command matrix
+
+| Command | Interactive? | Writes config? | Writes Dockerfile? | Typical user |
+|---|---|---|---|---|
+| `springdocker init` | No | Yes (skeleton) | No | Platform / first checkout |
+| `springdocker init --interactive` | Yes (via configure) | Yes | No | New service bootstrap |
+| `springdocker configure` | Yes | Yes (`[dockerfile]`) | Optional (`--generate`) | Strategy changes |
+| `springdocker dockerfile generate` | No | No | Yes | Daily dev + CI |
+| `springdocker explain --config-aware` | No | No | No | Audit / review (advisory — not a CI gate) |
+| `springdocker verify --check-config-drift` | No | No | No | CI SSOT gate (pass/fail) |
+
+### Precedence
+
+| Priority | Source |
+|---:|---|
+| 1 | CLI flags on `dockerfile generate` |
+| 2 | Project `.springdocker.toml` |
+| 3 | Built-in defaults |
+
+Org policy (`SPRINGDOCKER_POLICY`) is planned ([#123](https://github.com/mnafshin/springdocker/issues/123)); not required today.
+
+| Command | Purpose |
+|---|---|
+| `springdocker configure` | Interactive wizard that writes/updates `[dockerfile]` in config |
+| `springdocker init --interactive` | Create config skeleton, then run configure |
+| `springdocker dockerfile generate` | Deterministic generate from config (CI-safe, no prompts) |
+
+Profiles (`production-balanced`, `smallest-image`, `fast-cold-start`, `build-speed`, `simplest`, `compliance`, `custom`) are selected in `configure` and expanded to explicit options in config.
+
+### `dockerfile generate` CLI overrides
+
+Every `[dockerfile]` key is overridable from the CLI except file-backed keys (`must_have_modules_file`, `jlink_baseline_modules`), which stay in config only.
+
+| Section | CLI flags | Config key(s) |
+|---|---|---|
+| General | `--output`, `--java-version`, `--recipe`, `--profile` | `output`, `java_version`, `recipe`, `profile` |
+| Runtime | `--runtime-image`, `--non-root` / `--no-non-root`, `--platform-aware` / `--no-platform-aware`, `--healthcheck-path` | `runtime_image`, `non_root`, `platform_aware`, `healthcheck_path` |
+| Build | `--use-buildkit-cache` / `--no-use-buildkit-cache`, `--use-jlink` / `--no-use-jlink`, `--use-layered-jar` / `--no-use-layered-jar` | `use_buildkit_cache`, `use_jlink`, `use_layered_jar` |
+| Supply chain | `--include-oci-labels`, `--include-stopsignal`, `--include-embedded-sbom`, `--include-reproducible-controls`, `--pin-digests` (each with `--no-*` form) | matching `include_*` keys and `pin_digests` |
+| JVM | `--enable-appcds`, `--enable-jep483-aot-cache`, `--tuned-jvm-flags`, `--jvm-flag` (repeatable) | `enable_appcds`, `enable_jep483_aot_cache`, `tuned_jvm_flags`, `jvm_flags` |
+
+Example one-off CI override:
+
+```bash
+springdocker dockerfile generate \
+  --project-root samples/java-spring-docker \
+  --runtime-image alpine \
+  --no-use-jlink \
+  --enable-jep483-aot-cache \
+  --no-include-embedded-sbom \
+  --pin-digests \
+  --jvm-flag "-XX:+UseZGC"    # or --jvm-flag=-XX:+UseZGC when the flag starts with '-'
+```
+
+The `dockerfile generate` `--help` output groups flags under **runtime**, **build**, **supply chain**, and **JVM** sections.
+
+The `07-native-benchmark` scenario is generated with the `native-aot` scaffold recipe. The internal benchmark runner skips native scenarios by default (`--skip-native`).
 
 ## Config file (`.springdocker.toml`)
 
@@ -301,9 +403,16 @@ build_tool = "maven"
 output = "Dockerfile.generated"
 java_version = 25
 recipe = "jvm-balanced"
+# profile = "production-balanced"  # set by `springdocker configure`
+# runtime_image = "distroless"
+# use_jlink = true
+# enable_jep483_aot_cache = false
+# include_embedded_sbom = true
+# pin_digests = true
+# tuned_jvm_flags = true
+# jvm_flags = ["-XX:MaxRAMPercentage=75", "-XX:+ExitOnOutOfMemoryError", "-Djava.io.tmpdir=/tmp"]
+# Generator default runtime: distroless (gcr.io/distroless/base-* + jlink + layered JAR).
 must_have_modules_file = "must-have.txt"
-legacy_scripts = false
-wizard_args = []
 
 [benchmark.generate]
 java_version = 25
@@ -324,6 +433,28 @@ When `dockerfile.must_have_modules_file` is set, springdocker reads modules from
 (`must-have.txt` style, one module per line, `#` comments allowed) and injects them into
 the jlink module list for reflection/dynamic-loading edge cases.
 
+When jlink is enabled, springdocker auto-merges **jlink baseline modules** when Spring Web starters
+are detected (`spring-boot-starter-web`, `spring-boot-starter-webflux`, `spring-boot-starter-websocket`):
+
+- `java.desktop` — JavaBeans and desktop-related APIs used by parts of the Spring Web stack
+- `java.logging` — `java.util.logging` used by framework and library code
+- `java.naming` — JNDI lookups that jdeps often misses on web apps
+
+Non-web Spring Boot workloads get **no** auto baseline — use jdeps plus `must_have_modules_file` for
+extra modules. Override or disable in `.springdocker.toml`:
+
+```toml
+[dockerfile]
+# Omit jlink_baseline_modules to auto-detect from Spring Web starters at generate time.
+# Override defaults or set [] to disable baseline injection.
+jlink_baseline_modules = ["java.desktop", "java.logging", "java.naming"]
+```
+
+See [ADR 0007](../docs/adr/0007-jlink-baseline-modules-web-detection.md).
+
+`springdocker explain` reports baseline and curated modules separately in JSON/table output.
+Baseline modules are generator defaults; curated modules come from `must_have_modules_file`.
+
 Create template config:
 
 ```bash
@@ -331,24 +462,32 @@ springdocker init --project-root samples/java-spring-docker --build-tool gradle
 springdocker init --project-root samples/java-spring-docker --build-tool gradle --profile full --print
 ```
 
-## Legacy compatibility mode
+### `init --interactive`
 
-Main command paths are internal and do not require project script files.
-
-To force script wrappers for compatibility:
+Creates `.springdocker.toml` if missing, then runs the same wizard as `configure` (no Dockerfile write unless you chain commands yourself):
 
 ```bash
-springdocker dockerfile generate --use-legacy-scripts ...
-springdocker benchmark generate --use-legacy-scripts ...
-springdocker benchmark run --use-legacy-scripts ...
+springdocker init --project-root . --build-tool maven --interactive
+# equivalent to:
+# springdocker init --project-root . --build-tool maven
+# springdocker configure --project-root . --force
 ```
 
-or set:
+Use `--force` on `init` to overwrite an existing skeleton; use `configure --force` to replace only the `[dockerfile]` section in an existing file.
+
+See [docs/team-adoption.md](../docs/team-adoption.md) for first-time setup, CI examples, and migration from the retired `tools/dockerfile_wizard.py`.
+
+## Legacy benchmark scripts
+
+Benchmark commands still support `--use-legacy-scripts` (or `SPRINGDOCKER_LEGACY_SCRIPTS=1`) to delegate to project scripts under `benchmarks/` when needed:
 
 ```bash
-export SPRINGDOCKER_LEGACY_SCRIPTS=1
+springdocker benchmark generate --use-legacy-scripts ...
+springdocker benchmark run --use-legacy-scripts ...
 ```
 
+Dockerfile generation always uses the internal config-driven generator. Use `springdocker configure` for interactive setup instead of the retired `tools/dockerfile_wizard.py` script.
+
 ## Inspect command
 
 `springdocker inspect` prints static metadata about the target project:
@@ -364,16 +503,76 @@ Use `--format json` for machine-readable output.
 
 ## Explain command
 
-`springdocker explain` reads a springdocker-generated Dockerfile and describes the optimizations it contains:
+`springdocker explain` reads a Dockerfile and **describes** optimizations it recognizes using static text heuristics (regex and keyword matching).
+
+**Advisory only — not a CI gate.** Explain output helps humans review and document a Dockerfile. It does **not** perform a security audit, lint the file, scan images, or prove runtime correctness. Hand-written Dockerfiles may be misread; a missing feature in explain output does not mean that optimization is absent at runtime.
+
+**Use `springdocker verify` for CI gates** — hadolint, trivy, SBOM checks, optional dive/cosign/smoke, and `--check-config-drift` for config SSOT compliance. Only `verify` uses pass/fail semantics suitable for blocking merges.
+
+Recognized signals include:
 
 - multi-stage layout
 - BuildKit cache usage
 - jlink runtime stage
 - non-root runtime
 - tuned JVM flags
-- curated must-have modules
+- jlink baseline modules (built-in defaults)
+- curated must-have modules (from `must-have.txt`)
+
+Use `--format json` when you want stable structured output. The JSON `notes` field repeats the advisory scope and points to `verify`.
+
+Add `--config-aware` to include resolved `[dockerfile]` options from `.springdocker.toml`, per-option sources (`default` or `project`), and drift detection against `dockerfile generate`. Config drift in explain is informational; enforce SSOT in CI with `verify --check-config-drift`:
+
+```bash
+springdocker explain --project-root . Dockerfile.generated --format json --config-aware
+springdocker verify --project-root . --dockerfile Dockerfile.generated --check-config-drift
+```
+
+## Verify command
+
+`springdocker verify` runs a battery of checks against a generated Dockerfile and optional runtime context. It is designed to work in CI without installing every external tool.
+
+```bash
+springdocker verify --project-root tests/fixtures/maven-only Dockerfile.generated
+springdocker verify --project-root tests/fixtures/maven-only Dockerfile.generated \
+  --image demo:latest \
+  --smoke-url http://127.0.0.1:8081/actuator/health \
+  --format junit \
+  --output reports/verify.junit.xml
+springdocker verify --project-root . --dockerfile Dockerfile.generated --check-config-drift
+```
+
+`--check-config-drift` adds config SSOT checks when `.springdocker.toml` is present:
+
+| Check | Validates |
+|---|---|
+| `config-drift` | Dockerfile matches `dockerfile generate` output for current config |
+| `config-embedded-sbom` | `/usr/share/sbom/spdx.json` present when `include_embedded_sbom = true` |
+| `config-non-root` | unprivileged `USER` when `non_root = true` |
+| `config-jvm-flags` | configured JVM flags appear in `ENTRYPOINT` |
+
+### Built-in checks
+
+| Check | Requires | Missing prerequisite | Check failure |
+|---|---|---|---|
+| `hadolint` | `hadolint` on `PATH` | **skipped** (`hadolint not installed`) | non-zero exit |
+| `trivy` | `trivy` on `PATH` | **skipped** (`trivy not installed`) | HIGH/CRITICAL findings |
+| `dive` | `--image` and `dive` on `PATH` | **skipped** (`no image provided` or `dive not installed`) | non-zero exit |
+| `cosign` | `--image` and `cosign` on `PATH` | **skipped** (`no image provided` or `cosign not installed`) | non-zero exit |
+| `sbom` | `sbom.spdx.json` in project root | n/a (always runs) | **failed** if file missing, invalid JSON, or missing `spdxVersion` |
+| `smoke` | `--smoke-url` | **skipped** (`no smoke URL provided`) | HTTP/network error or status ≥ 400 |
+
+Verifier plugins registered under `springdocker.verifiers` run after the built-in checks. See `docs/extensions.md`.
+
+### Skip vs fail semantics
+
+- **skipped** checks do not fail the command. They appear in table/JSON/JUnit/SARIF output for visibility.
+- **failed** checks set the overall result to `failed` and make `springdocker verify` exit with code `1`.
+- Only **failed** checks affect the exit code. A run where every external tool is missing but `sbom.spdx.json` is valid still exits `0`.
+
+Optional tools are intentionally optional: install `hadolint`, `trivy`, `dive`, and `cosign` locally or in CI when you want those gates enforced.
 
-Use `--format json` when you want stable structured output.
+Supported `--format` values: `table` (default), `json`, `junit`, `sarif`, plus plugin-provided formats.
 
 ## Security hardening
 

springdocker-1.1.0/README.md

@@ -0,0 +1,305 @@
+# springdocker
+
+[![CI](https://github.com/mnafshin/springdocker/actions/workflows/ci.yml/badge.svg)](https://github.com/mnafshin/springdocker/actions/workflows/ci.yml)
+[![Release](https://github.com/mnafshin/springdocker/actions/workflows/release.yml/badge.svg)](https://github.com/mnafshin/springdocker/actions/workflows/release.yml)
+[![Lint](https://img.shields.io/badge/lint-ruff-blue)](https://github.com/astral-sh/ruff)
+[![Coverage](https://img.shields.io/badge/coverage-%3E%3D80%25-brightgreen)](./CONTRIBUTING.md#coverage-policy)
+[![Benchmark](https://img.shields.io/badge/benchmark-regression--gated-orange)](./docs/benchmark-methodology.md)
+
+Developer toolkit for **production teams** containerizing Spring Boot — with optional benchmark evidence for tuning and conference demos.
+
+`springdocker` is a Python CLI that helps teams inspect a Spring Boot project, commit Dockerfile strategy in `.springdocker.toml`, generate and verify Dockerfiles in CI, and (optionally) run benchmark suites for evidence-backed tuning.
+
+See [`docs/POSITIONING.md`](docs/POSITIONING.md) for **who it is for**, CI-evidenced guarantees, and how the sample projects relate to shipped behavior.
+
+## Who it's for
+
+Resolved in [#87](https://github.com/mnafshin/springdocker/issues/87) — see [`docs/adr/0008-target-audience.md`](docs/adr/0008-target-audience.md).
+
+| Audience | Fit |
+|---|---|
+| **Production teams** (primary) | Adopt via PyPI on **your** Maven/Gradle service — config-first Dockerfile workflow, explain/verify in CI, Java **17+** on your project |
+| **Conference / storytelling** (secondary) | Clone for presentations and benchmark evidence under `samples/java-spring-docker/` — numbers are sample-specific, not universal guarantees |
+| **Personal lab only** (not primary) | Bleeding-edge sample (Boot 4 / Java 25) stress-tests the generator inside the repo; you do not need to match those versions to use the CLI |
+
+**Not** a black-box image builder like Jib or Buildpacks — you own the Dockerfile. **Not** a research-only toy — CI gates the installable CLI; benchmarks and decks are optional depth.
+
+## Install
+
+**Primary path: PyPI** — install the CLI and run it on your Spring Boot project. You do not need to clone this repository for Dockerfile generation, explain, or verify.
+
+```bash
+# Recommended: isolated user install (Dockerfile workflow)
+pipx install springdocker
+# or
+uv tool install springdocker
+
+# Include benchmark run/analyze (optional; requires Docker on the host)
+pipx install 'springdocker[benchmark]'
+# or: python3 -m pip install 'springdocker[benchmark]' inside your project venv
+```
+
+See [`cli/README.md`](cli/README.md#install) for pip/editable options and upgrade commands.
+
+### When to clone this repository
+
+| Goal | What to do |
+|---|---|
+| Generate/explain/verify Dockerfiles for **your** service | Install from PyPI only |
+| Reproduce benchmark evidence, presentations, or pinned CI baselines | Clone; work under `samples/java-spring-docker/` — see [`docs/presentation/README.md`](docs/presentation/README.md) for deck ownership and update policy |
+| Contribute to the CLI | Clone; editable install — see [Contributing](#contributing) |
+
+Resolved in [#97](https://github.com/mnafshin/springdocker/issues/97) — see [`docs/adr/0006-pypi-first-distribution.md`](docs/adr/0006-pypi-first-distribution.md).
+
+## Project naming
+
+**springdocker** is the canonical name for this project — use it when searching GitHub or PyPI, installing the package, or running the CLI.
+
+| Surface | Name |
+|---|---|
+| GitHub repository | [`mnafshin/springdocker`](https://github.com/mnafshin/springdocker) |
+| PyPI package / `pip install` | `springdocker` |
+| CLI command | `springdocker` |
+| Config file | `.springdocker.toml` |
+
+The string **`java-spring-docker`** appears only in the benchmark sample app, not in the CLI package:
+
+| Surface | Path or coordinates | Role |
+|---|---|---|
+| Sample app directory | `samples/java-spring-docker/` | Full Spring Boot app for benchmark scenarios and evidence |
+| Sample Maven/Gradle artifact | `io.github.mnafshin:java-spring-docker` | Demo application identity inside that sample |
+
+Those sample names predate the **springdocker** product name. They do not affect installation (`pip install springdocker`) or CLI usage. Your local clone directory can be named anything.
+
+## Why springdocker instead of Jib or Buildpacks?
+
+- **Jib** and **Buildpacks** optimize for build convenience and opaque image assembly.
+- **springdocker** optimizes for teams that want a **real Dockerfile they can own, read, and edit**.
+- It combines explicit Dockerfile generation with explainability and verification workflows.
+- **`explain`** is advisory static analysis for human review; **`verify`** is the pass/fail command for CI gates.
+
+See [`docs/POSITIONING.md`](docs/POSITIONING.md) for the detailed comparison and tradeoffs.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  dev[Developer] --> cli[springdocker CLI]
+  cli --> cfg[.springdocker.toml]
+  cli --> proj[Spring Boot project]
+  cli --> df[Generated Dockerfile]
+  cli --> bench[Benchmark variants + raw CSV]
+  bench --> report[Table / JSON analysis]
+```
+
+See `docs/architecture.md` for the detailed module map and command lifecycle.
+
+The repo is split into these main surfaces:
+
+- `src/springdocker/` - installable CLI package and core implementation.
+- `cli/README.md` - command reference and configuration details.
+
+See [Sample project map](#sample-project-map) for which Spring Boot path to use.
+
+## What it does
+
+**Shipped and CI-validated:** project detection, config, Dockerfile generation, explain/verify commands, and benchmark asset/analyzer plumbing (see [`docs/POSITIONING.md`](docs/POSITIONING.md#shipped-guarantees-ci-evidenced)).
+
+**Optional / sample-anchored:** full benchmark runs, performance comparison tables, and reference evidence under `samples/java-spring-docker/`.
+
+- Detects Maven or Gradle projects.
+- Writes a starter `.springdocker.toml` config.
+- Generates Dockerfiles with opinionated Spring Boot defaults (`jvm-balanced`: **distroless** runtime + custom **jlink** runtime + layered JAR).
+- Pins generated base images by digest when known.
+- Creates benchmark variants and runs benchmark suites (requires Docker and `[benchmark]` extra).
+- Summarizes benchmark CSV output as a table or JSON.
+
+Digest pins are centralized in `src/springdocker/digest_pins.py` and verified in CI.
+Runbook: [`docs/digest-pin-runbook.md`](docs/digest-pin-runbook.md) · Renovate template: [`.github/renovate.json`](.github/renovate.json)
+
+## Sample project map
+
+| Path | Role | Use when |
+|---|---|---|
+| `tests/fixtures/{maven-only,gradle-only}/` | Minimal Spring Boot apps for CLI walkthroughs and CI | Learning the CLI, trying Dockerfile generation, or extending tests ([`docs/golden-samples.md`](docs/golden-samples.md)) |
+| `samples/java-spring-docker/` | Benchmark harness + evidence | Running benchmark scenarios and comparing `raw.csv` results |
+
+Gradle walkthroughs use `tests/fixtures/gradle-only/` with the same commands below (Maven: `tests/fixtures/maven-only/`).
+
+See [`docs/adr/0004-sample-project-strategy.md`](docs/adr/0004-sample-project-strategy.md) for why the former `examples/` walkthrough tree was removed.
+
+## Quick start
+
+Install from PyPI first (see [Install](#install)). Then run against **your** Spring Boot project:
+
+```bash
+cd /path/to/your-spring-boot-app
+springdocker doctor --project-root .
+springdocker init --project-root . --build-tool maven
+springdocker configure --project-root . --force
+springdocker dockerfile generate --project-root .
+springdocker explain --project-root . Dockerfile.generated --config-aware   # advisory review
+springdocker verify --project-root . Dockerfile.generated --check-config-drift   # CI gate
+```
+
+To try the CLI without your own app, clone this repo and use the minimal fixtures (see [Sample project map](#sample-project-map)):
+
+```bash
+git clone https://github.com/mnafshin/springdocker.git
+cd springdocker
+pipx install 'springdocker[benchmark]'   # or: pip install -e '.[dev]' for contributing
+
+springdocker doctor --project-root tests/fixtures/maven-only
+springdocker init --project-root tests/fixtures/maven-only --build-tool maven
+springdocker configure --project-root tests/fixtures/maven-only --force
+springdocker dockerfile generate --project-root tests/fixtures/maven-only
+```
+
+**Benchmark workflow** (optional; requires clone + Docker + `[benchmark]` extra) — use the full sample app under `samples/`:
+
+```bash
+cd springdocker   # repository root after clone
+springdocker benchmark generate --project-root samples/java-spring-docker --java-version 25
+springdocker benchmark run --project-root samples/java-spring-docker --profile quick
+springdocker benchmark analyze --project-root samples/java-spring-docker samples/java-spring-docker/benchmarks/03-custom-jre-jlink/results/raw.csv --format table
+springdocker benchmark compare --project-root samples/java-spring-docker samples/java-spring-docker/benchmarks/03-custom-jre-jlink/results/raw.csv --baseline-variant with-jlink-runtime
+springdocker benchmark analyze --project-root samples/java-spring-docker samples/java-spring-docker/benchmarks/06-base-image-choice/results/raw.csv --baseline samples/java-spring-docker/benchmarks/06-base-image-choice/results/baseline.json
+```
+
+**Default runtime:** `dockerfile generate` with `--recipe jvm-balanced` (the default) uses **`runtime_image = distroless`**: a digest-pinned `gcr.io/distroless/base-*:nonroot` stage plus a jlink-built JVM and layered Spring Boot JAR — not a full OS image. Distroless images have no shell, so generated Dockerfiles **omit `HEALTHCHECK`**; configure readiness probes in Kubernetes or your orchestrator. OS runtime bases are compared in benchmark scenario **06** — see [`cli/README.md`](cli/README.md#dockerfile-recipes).
+
+## CLI workflow
+
+1. `doctor` checks the project root and build tool.
+2. `init` writes a starter config file.
+3. `dockerfile generate` writes a Dockerfile to the requested path (default recipe: distroless + jlink layered JAR).
+4. `benchmark generate` creates benchmark scenarios.
+5. `benchmark run` executes the benchmark runner.
+6. `benchmark analyze` turns `raw.csv` into a table or JSON summary.
+
+See `cli/README.md` for the command reference and config precedence rules.
+
+## Benchmark methodology
+
+See `docs/benchmark-methodology.md` for the benchmark model, run profiles, and summary calculations.
+
+Benchmarks are an optional evidence subsystem and require benchmark extras (`springdocker[benchmark]`).
+
+The sample project keeps benchmark scenarios under `samples/java-spring-docker/benchmarks/`.
+Generated variant Dockerfiles and most run output are **gitignored** — regenerate with `springdocker benchmark generate` and `springdocker benchmark run`.
+The scenario 06 CI regression baseline lives under `samples/java-spring-docker/benchmarks/06-base-image-choice/results/`.
+See `samples/java-spring-docker/benchmarks/README.md` for the full artifact policy.
+
+### Benchmark scenario index
+
+Authoritative list of generated scenarios under `samples/java-spring-docker/benchmarks/`.
+Regenerate directories with `springdocker benchmark generate`. Scenario **07** is listed after **06** and before **08** by id, even though the generator emits **08** before the native scaffold.
+
+| ID | Directory | Purpose | Variants | Further reading |
+|---|---|---|---|---|
+| 01 | `01-multi-stage-build-structure` | Multi-stage Dockerfile layout vs a simpler two-stage build | `specialized-multi-stage`, `simple-two-stage` | [`benchmark-methodology.md`](docs/benchmark-methodology.md#current-sample-comparison-snapshot) |
+| 02 | `02-buildkit-gradle-cache` | BuildKit cache mount on dependency rebuilds | `with-buildkit-cache`, `without-buildkit-cache` | [`benchmark-methodology.md`](docs/benchmark-methodology.md#current-sample-comparison-snapshot) |
+| 03 | `03-custom-jre-jlink` | jlink vs vendor JRE on debian-slim vs stock Temurin image | `with-jlink-runtime`, `without-jlink-runtime`, `temurin-jre-image` | [`jvm-optimization.md`](docs/jvm-optimization.md), [`golden-samples.md`](docs/golden-samples.md) |
+| 04 | `04-jep483-aot-cache` | JEP 483 ahead-of-time class-loading cache (Java 24+) | `with-aot-cache`, `without-aot-cache` | [`jvm-optimization.md`](docs/jvm-optimization.md) · extra runs: 8 (`quick`) / 15 (`full`) |
+| 05 | `05-jvm-container-flags` | Tuned vs baseline JVM container flags | `tuned-flags`, `defaults-like` | [`jvm-optimization.md`](docs/jvm-optimization.md) |
+| 06 | `06-base-image-choice` | Runtime base image tradeoffs (jlink on every base) | `alpine`, `debian-slim`, `ubuntu`, `distroless` (configurable) | [`benchmark-methodology.md`](docs/benchmark-methodology.md#configuring-base-image-variants-scenario-06) · CI regression baseline |
+| 07 | `07-native-benchmark` | Native-image scaffold (`native-aot` recipe); skipped by default | _(single Dockerfile at scenario root — no variant dirs)_ | [`native-image-roadmap.md`](docs/native-image-roadmap.md) |
+| 08 | `08-appcds` | AppCDS shared archive at build time | `with-appcds`, `without-appcds` | [`jvm-optimization.md`](docs/jvm-optimization.md) |
+
+Example analyze commands (after `benchmark run`):
+
+```bash
+springdocker benchmark analyze --project-root samples/java-spring-docker \
+  benchmarks/03-custom-jre-jlink/results/raw.csv --format table
+springdocker benchmark analyze --project-root samples/java-spring-docker \
+  benchmarks/04-jep483-aot-cache/results/raw.csv --format json
+springdocker benchmark compare --project-root samples/java-spring-docker \
+  benchmarks/03-custom-jre-jlink/results/raw.csv --baseline-variant with-jlink-runtime
+```
+
+Current reports focus on:
+
+- image size
+- build duration
+- startup latency
+- success rate
+
+Benchmark summaries can be rendered as:
+
+- terminal tables
+- JSON
+
+## Supported stack
+
+| Layer | CI / fixtures | Reference sample (`samples/java-spring-docker/`) |
+|---|---|---|
+| Python CLI | 3.10–3.12 tested in CI | — |
+| Build tools | Maven and Gradle (minimal fixtures + examples) | Maven and Gradle |
+| Spring Boot | Projects with Spring Boot markers | 4.0.1 |
+| Java in generated Dockerfiles | ≥17 (generator validation) | 25 default in sample config |
+
+The reference sample uses bleeding-edge versions to stress-test generator output and benchmark scenarios. Your project does not need to match those versions to use the CLI.
+
+## Project docs
+
+Documentation uses three status labels:
+
+| Status | Meaning |
+|---|---|
+| **Implemented** | Shipped CLI behavior, runbooks, ADRs, or committed reference artifacts |
+| **Experimental** | Scaffold or opt-in capability — documented with explicit limits; not production-ready |
+| **Roadmap** | Planned capability or doc product not shipped yet |
+
+### Implemented
+
+- `docs/project-detection.md` — Maven/Gradle detection boundaries and monorepo workflows
+- `docs/POSITIONING.md` — product scope, CI guarantees, sample-tree strategy
+- `docs/digest-pin-runbook.md`
+- `docs/architecture.md`
+- `docs/benchmark-methodology.md`
+- `docs/golden-samples.md`
+- `docs/extensions.md`
+- `docs/security-hardening.md`
+- `docs/observability.md`
+- `docs/kubernetes.md`
+- `docs/adr/README.md`
+- `docs/multiarch.md`
+- `docs/onboarding.md`
+- `docs/team-adoption.md`
+- `docs/troubleshooting.md`
+- `docs/typing-roadmap.md` — gradual mypy strictness and module rollout plan
+- `docs/jvm-optimization.md`
+- `docs/distribution.md`
+- `docs/presentation/README.md` — Reveal.js decks: ownership, update cadence, commit/publish policy
+- `docs/example-gallery.md` — index of committed Dockerfile and benchmark JSON examples under `docs/examples/`
+- `docs/compatibility-matrix.md` — descriptive support ranges (Java 17+, Python 3.10+, etc.)
+- `SECURITY.md`
+- `CONTRIBUTING.md`
+
+### Experimental
+
+- `docs/native-image-roadmap.md` — `native-aot` recipe and scenario 07 scaffold; runner skips native by default; production native-image workflow remains roadmap
+
+### Roadmap
+
+- `docs/benchmark-dashboard.md` — standalone trend dashboard (presentation decks and `benchmark analyze` JSON are substitutes today)
+
+## Comparison with adjacent tools
+
+| Tool | Focus | What springdocker adds |
+|---|---|---|
+| Jib | Dockerless image build | benchmark-aware Dockerfile and runtime tuning workflows |
+| Buildpacks | Opinionated platform build | explicit Dockerfile generation and benchmark artifacts |
+| Manual Dockerfiles | Full control | project detection, config, and repeatable benchmark analysis |
+
+## Sample project docs
+
+- `docs/golden-samples.md` - fixture walkthroughs, CI coverage, and variant coverage
+- `samples/java-spring-docker/README.md` - full benchmark sample app
+- `samples/java-spring-docker/HELP.md`
+- `samples/java-spring-docker/k8s/kustomization.yaml`
+- `samples/java-spring-docker/tools/README.md`
+
+## Contributing
+
+Clone the repository and use an editable install — see [CONTRIBUTING.md](CONTRIBUTING.md). The main package is under `src/springdocker/`. Run `pytest` (≥80% line coverage gate), `ruff check src tests`, and `mypy src` before pushing changes.