feat(k9-svc): container deployment example, deprecation analysis, Chainguard fix

Add container-deploy.k9.ncl (Hunt-level multi-service deployment with
rolling deploy and rollback) and NOT-a-good-fit.adoc (honest comparison
of k9-svc/a2ml vs alternatives with 5 DEPRECATE and 10 KEEP verdicts).
Update GUIDE.adoc with container deployment section. Fix Containerfile
to use Chainguard wolfi-base instead of Debian.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: hyperpolymath

k9-svc/Containerfile

@@ -1,68 +1,104 @@
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-License-Identifier: PMPL-1.0-or-later
 # Containerfile - K9 SVC Runtime Container
 #
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
+#
+# Uses Chainguard base images for minimal attack surface:
+# - Builder stage: Rust toolchain on wolfi-base for compiling nickel and just
+# - Runtime stage: wolfi-base with only the binaries needed to run k9 components
+#
+# Chainguard images have no shell (in static variants), no package manager
+# bloat, and minimal CVE surface. We use wolfi-base (not static) because
+# k9-svc needs a shell for the must shim and Just recipes.
+#
 # Build:  podman build -t k9-svc:latest .
 # Run:    podman run --rm -it k9-svc:latest status
 # Mount:  podman run --rm -it -v ./components:/k9/components k9-svc:latest validate-all
 
-FROM docker.io/library/rust:slim-bookworm AS builder
+# ─────────────────────────────────────────────────────────────────────
+# Builder Stage
+#
+# Compiles nickel-lang-cli and just from source using Rust.
+# This stage is discarded after the binaries are copied out.
+# ─────────────────────────────────────────────────────────────────────
+FROM cgr.dev/chainguard/wolfi-base:latest AS builder
 
-# Install build dependencies
-RUN apt-get update && apt-get install -y --no-install-recommends \
+# Install build dependencies via apk (wolfi's package manager).
+# - rust and cargo for compiling nickel and just
+# - curl and ca-certificates for downloading crate dependencies
+# - gcc and musl-dev for linking native code
+RUN apk update && apk add --no-cache \
+    rust \
+    cargo \
     curl \
     ca-certificates \
-    && rm -rf /var/lib/apt/lists/*
+    gcc \
+    musl-dev
 
-# Install Nickel
+# Install Nickel (the typed configuration language that powers k9 validation)
 RUN cargo install nickel-lang-cli --locked
 
-# Install Just
+# Install Just (the task runner that powers k9 recipes)
 RUN cargo install just --locked
 
-# ─────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────────────────────────────
 # Runtime Stage
-# ─────────────────────────────────────────────────────────────
-FROM docker.io/library/debian:bookworm-slim
+#
+# Minimal Chainguard image with only the binaries and files needed
+# to run k9 components. No build tools, no package manager bloat.
+# ─────────────────────────────────────────────────────────────────────
+FROM cgr.dev/chainguard/wolfi-base:latest
 
 LABEL org.opencontainers.image.title="K9 SVC Runtime"
 LABEL org.opencontainers.image.description="Self-Validating Component runtime environment"
 LABEL org.opencontainers.image.version="1.0.0-alpha"
 LABEL org.opencontainers.image.vendor="hyperpolymath"
-LABEL org.opencontainers.image.licenses="AGPL-3.0-or-later"
+LABEL org.opencontainers.image.licenses="PMPL-1.0-or-later"
 LABEL org.opencontainers.image.source="https://github.com/hyperpolymath/k9-svc"
 
-# Install runtime dependencies
-RUN apt-get update && apt-get install -y --no-install-recommends \
+# Install minimal runtime dependencies via apk.
+# - ca-certificates: for TLS verification when Hunt components access network
+# - file: for MIME type detection (used by `file --mime-type` in k9 validation)
+# - libgcc: runtime library needed by compiled Rust binaries
+RUN apk update && apk add --no-cache \
     ca-certificates \
     file \
-    && rm -rf /var/lib/apt/lists/*
-
-# Copy binaries from builder
-COPY --from=builder /usr/local/cargo/bin/nickel /usr/local/bin/nickel
-COPY --from=builder /usr/local/cargo/bin/just /usr/local/bin/just
+    libgcc
 
-# Create non-root user for security
-RUN useradd -m -s /bin/sh k9user
+# Create non-root user for security.
+# k9 components should never run as root unless explicitly required
+# by a Hunt-level component (and even then, avoid it).
+RUN adduser -D -s /bin/sh k9user
 USER k9user
 WORKDIR /home/k9user/k9
 
-# Copy K9 SVC files
+# Copy binaries from builder stage.
+# Only nickel and just are needed at runtime — no Rust toolchain.
+COPY --from=builder /root/.cargo/bin/nickel /usr/local/bin/nickel
+COPY --from=builder /root/.cargo/bin/just /usr/local/bin/just
+
+# Copy K9 SVC files into the container.
+# These are the core schemas, the must shim, and the examples.
 COPY --chown=k9user:k9user must justfile pedigree.ncl register.ncl leash.ncl ./
 COPY --chown=k9user:k9user mime/ ./mime/
 COPY --chown=k9user:k9user examples/ ./examples/
 
-# Verify the triad is functional
+# Verify the triad is functional.
+# This is the dogfooding step: the container validates itself during build.
+# If any of these fail, the build fails — no broken images ship.
 RUN ./must status && \
     nickel typecheck pedigree.ncl && \
     nickel typecheck register.ncl && \
     nickel typecheck leash.ncl
 
-# Default: show status
+# Default entrypoint: the must shim, which detects the environment
+# and delegates to just/nickel as appropriate.
 ENTRYPOINT ["./must"]
 CMD ["status"]
 
-# Volume for mounting external components
+# Volume for mounting external components.
+# Users mount their .k9 and .k9.ncl files here for validation/deployment.
 VOLUME ["/home/k9user/k9/components"]
 
-# Expose nothing by default (K9 is not a server)
-# Components can override if they need ports
+# Expose nothing by default (K9 is not a server).
+# Hunt-level components that need ports can override this.

k9-svc/GUIDE.adoc

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
 = K9 SVC User Guide
 :toc: left
 :toclevels: 3
@@ -551,6 +552,170 @@ See `pedigree.ncl` for the full schema with contracts.
 │       └── bob.pub
 ----
 
+== Container Deployment with k9-svc
+
+This section covers how k9-svc wraps container deployments using the Leash
+security model, selur-compose, and Nickel typed configuration.
+
+=== When to Use k9-svc for Containers
+
+k9-svc is designed for **operational deployment components** — things that
+orchestrate, validate, and deploy container stacks. It is NOT a replacement
+for `Cargo.toml`, `mix.exs`, or other build-time manifests.
+
+Use k9-svc when you need:
+
+* **Typed deployment configs** — Nickel contracts catch invalid port numbers,
+  missing environment variables, and impossible resource limits at eval time,
+  before any container starts.
+* **Security-level enforcement** — The Leash system prevents accidental
+  execution of destructive deployment recipes.
+* **Signed deployment artifacts** — Ed25519 signatures ensure only authorized
+  operators can run deployment scripts.
+* **Self-validating components** — The dogfooding principle means each
+  deployment component can validate its own configuration.
+
+=== Security Level Selection Guide
+
+Choosing the correct security level is the most important decision when
+creating a k9 container deployment component.
+
+[cols="1,2,3"]
+|===
+| Level | Use When | Container Example
+
+| `'Kennel`
+| The component is pure data with no execution.
+| A static list of container image tags and their SHA256 digests. No commands, no evaluation. Just data.
+
+| `'Yard`
+| The component needs Nickel evaluation but performs no I/O.
+| A typed configuration that validates port ranges, memory limits, and environment variable shapes. It produces validated JSON output but does not start any containers.
+
+| `'Hunt`
+| The component executes commands, accesses the network, or writes files.
+| A deployment component that generates selur-compose files, pulls images, starts services, runs health checks, and performs rollback on failure.
+|===
+
+[IMPORTANT]
+====
+**Rule of thumb:** If your component runs `selur-compose`, `podman`, or any
+shell command, it MUST be `'Hunt` level. If it only evaluates Nickel
+expressions and produces output, use `'Yard`. If it is pure data (a list of
+images, a set of environment variables), use `'Kennel`.
+
+**Never use `'Hunt` for read-only operations.** If your component only reads
+and displays data, `'Kennel` or `'Yard` is correct. Hunt requires
+cryptographic signatures and should be reserved for components with real
+side effects.
+====
+
+=== Example: Container Deployment as a Hunt Component
+
+The `container-deploy.k9.ncl` example demonstrates a realistic multi-service
+deployment component. It deploys an app + database + cache stack across
+dev/staging/production environments.
+
+[source,nickel]
+----
+# Security: Hunt level because this component:
+# - Runs selur-compose commands (subprocess)
+# - Pulls container images (network)
+# - Writes deployment state files (filesystem)
+security = {
+  trust_level = 'Hunt,
+  allow_network = true,
+  allow_filesystem_write = true,
+  allow_subprocess = true,
+  signature = "REAL-ED25519-SIGNATURE-HERE",
+},
+----
+
+Key features of this component:
+
+* **Environment-specific overrides** — Dev (1 replica, debug logging),
+  staging (2 replicas, info logging), production (3 replicas, warn logging).
+  All validated by Nickel contracts.
+* **Rolling deployment** — Replaces one replica at a time, waits for health
+  checks, and automatically rolls back on failure.
+* **Image signature verification** — Before deploying to staging or
+  production, verifies that container images are signed with cerro-torre.
+* **Self-validation** — The component typechecks itself before deployment.
+
+See: `examples/container-deploy.k9.ncl` for the complete implementation.
+
+=== Example: Config Validator as a Yard Component
+
+Not every container-related component needs Hunt level. A configuration
+validator that checks deployment configs without executing anything is a
+perfect Yard-level component.
+
+[source,nickel]
+----
+# Security: Yard level because this component:
+# - Evaluates Nickel contracts (typed validation)
+# - Produces validated JSON output
+# - Does NOT execute commands, access network, or write files
+security = {
+  trust_level = 'Yard,
+  allow_network = false,
+  allow_filesystem_write = false,
+  allow_subprocess = false,
+},
+----
+
+This component can:
+
+* Validate that container port mappings do not conflict
+* Check that resource limits are within acceptable ranges
+* Verify that environment variables match expected patterns
+* Export validated config as JSON for consumption by other tools
+
+See: `examples/config.k9.ncl` for a Yard-level configuration example.
+
+=== How k9-svc Wraps selur-compose
+
+The typical workflow for a k9-svc container deployment:
+
+[source]
+----
+1. Author writes .k9.ncl with Nickel-typed service definitions
+2. nickel typecheck validates the configuration (Yard-level eval)
+3. nickel export generates selur-compose.toml from the typed config
+4. The Hunt-level deploy script:
+   a. Verifies component signature (Ed25519)
+   b. Verifies container image signatures (cerro-torre)
+   c. Runs selur-compose up with the generated config
+   d. Monitors health checks
+   e. Rolls back on failure
+----
+
+The key insight is that steps 1-3 are **Yard-level** operations — they only
+evaluate Nickel expressions and produce data. Step 4 is a **Hunt-level**
+operation that requires the cryptographic handshake. This separation means
+you can validate configs without any security ceremony, but execution always
+requires authorization.
+
+=== Anti-Pattern Warnings
+
+Before wrapping something in k9-svc, read link:examples/NOT-a-good-fit.adoc[NOT-a-good-fit.adoc].
+
+Common mistakes:
+
+* **Do NOT** wrap plain config files in k9 pedigree. A `config.toml` is
+  already Kennel-level by nature. Adding pedigree overhead provides zero
+  security benefit.
+* **Do NOT** use k9-svc to manage library dependencies. Libraries are
+  build-time artifacts, not deployment components. Use `Cargo.toml` or
+  `mix.exs`.
+* **Do NOT** use Hunt level for read-only operations. If your component
+  only reads data, use Kennel or Yard.
+* **Do NOT** wrap every directory in a2ml manifests. One at the repo root
+  is sufficient for most projects.
+
+See: link:examples/NOT-a-good-fit.adoc[Comparison, Deprecation Analysis, and Anti-Patterns]
+for the full analysis.
+
 == License
 
-K9 SVC is licensed under AGPL-3.0-or-later. See LICENSE for details.
+K9 SVC is licensed under PMPL-1.0-or-later. See LICENSE for details.