feat: make the Containerfile and devcontainer runnable (wave-2 3/8) (#44)

## What changed & why

Finalizes wave-2 work order
`.claude/tasks/prod-readiness/w2-3-containers.md`.
The implementation commit (`3d43043`) was already on
`feat/containers-runnable`
and pushed to origin, but no PR had been opened, so the new
`.github/workflows/container-build.yml` had never actually executed in
CI
(`gh run list --branch feat/containers-runnable` showed only an
unrelated,
skipped "Push email notification" run — the workflow only triggers on
`push`-to-`main` or `pull_request`-to-`main`, neither of which had
happened).
This PR's only change vs. the prior state of the branch is opening it,
which
is required for the acceptance criterion "CI build job green on the PR"
to be
checkable at all.

- `Containerfile` — rebased off `docker.io/library/julia:1.10` pinned by
  digest (matches the `julia_version` pinned in the committed
  `Manifest.toml`/`.tool-versions`), instantiates + precompiles the
  committed Manifest, runs as a non-root `statistikles` user, and sets
`ENTRYPOINT ["julia", "--project=/app", "-e", "using Statistikles;
main()"]`
— the real entry point in `src/tools/chat.jl`. No commented-out template
  blocks remain.
- `.dockerignore` — new, trims the build context (`.git/`, `.github/`,
  `docs/`, `proofs/`, `ffi/`, etc.).
- `.devcontainer/devcontainer.json` — adds the
`ghcr.io/julialang/devcontainer-features/julia:1` feature pinned to the
`1.10` channel, and switches `postCreateCommand` from the wave-1-era
no-op
`just deps` to the real `just setup` (wave-1 PR #34 made `just setup` a
  real `Pkg.instantiate()`). `.devcontainer/Containerfile` (Wolfi-based,
  `remoteUser: nonroot`) and its existing git/just/nickel features are
  untouched — they're real and out of scope.
- `.github/workflows/container-build.yml` — new. Builds the root
  `Containerfile` with `docker build` on `pull_request`/`push` to `main`
  (path-filtered to `Containerfile`, `.dockerignore`, `Project.toml`,
  `Manifest.toml`, `src/**`, and the workflow file itself) plus
  `workflow_dispatch`. Build only, no push/registry login.
  `actions/checkout` is SHA-pinned with a version comment; no job-level
  `hashFiles()`/`secrets` conditionals. A smoke step then runs the built
image and greps its stdout for the documented offline-demo banner lines.
- `QUICKSTART-USER.adoc` / `QUICKSTART-MAINTAINER.adoc` — reconciled
with the
now-real image: exact `podman build`/`podman run` commands (docker works
  identically), plus a documented caveat (verified by testing both the
container and a native WSL Julia run) that `STATISTIKLES_LM_URL` set at
  `run` time has no effect on a precompiled image/install, because
  `Pkg.precompile()` bakes the `ENV`-derived `BASE_URL` constant
  (`src/tools/lmstudio.jl`) into the precompile cache — a pre-existing
`lmstudio.jl` behavior, out of scope for this task, documented rather
than
  silently left broken.

## Process note (raised by review, not a code defect)

The existing commit's trailer reads `Co-Authored-By: Claude Opus 4.8 (1M
context)`, while the wave-2 routing table in
`.claude/tasks/prod-readiness/README.md` assigns
`impl=sonnet`/`verify=sonnet`
to this task. Checked and worth recording: the fleet's execution
contract
fixes that exact trailer string across all tasks regardless of which
model
actually executes (it is not a literal per-task model attestation) —
this
finalize pass itself runs under the same fixed-trailer convention. No
code
change was needed or made for this.

## Verification run & result

- No new code changes were required — the branch was already fully
pushed
  and matched the work order. Confirmed via `git fetch origin
feat/containers-runnable` + `git diff origin/main..HEAD --stat` (7 files
  changed, matches the commit's own description) and `git status`
  (clean, nothing to commit).
- Confirmed via `gh pr list --repo hyperpolymath/statistikles --head
  feat/containers-runnable --state all` (empty) that no PR previously
existed, and via `gh run list --repo hyperpolymath/statistikles --branch
feat/containers-runnable` that no `Container Build` run had ever
executed
  on this branch — consistent with the reviewer's finding.
- Re-read `Containerfile`, `.github/workflows/container-build.yml`,
  `.devcontainer/devcontainer.json`, and the `.adoc` diffs in full: no
commented-out template blocks remain, the workflow is path-filtered and
  SHA-pinned, and the devcontainer's separate Wolfi-based
`.devcontainer/Containerfile` (`remoteUser: nonroot`) is unrelated to
and
unaffected by the root `Containerfile`'s new `statistikles` non-root
user.
- Did not re-run `docker build`/`docker run` myself in this pass — the
  reviewer's own note states their local WSL `docker build`/`docker run`
reproduction already succeeded and matched the PR's claims exactly. This
PR now lets `.github/workflows/container-build.yml` run for real in CI
as
  the authoritative, checkable confirmation of the acceptance criterion.
- Opening this PR is expected to trigger the `Container Build` workflow
via
  its `pull_request`-to-`main` trigger (paths touched: `Containerfile`,
`.dockerignore`, `.github/workflows/container-build.yml`). Not merging,
  per the execution contract.

## Skipped / out of scope

Publishing images to a registry, multi-arch builds, and Guix packaging
(separate task `w2-2-guix-package.md`, already merged as #39) — all
explicitly out of scope per the work order.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.devcontainer/README.adoc

@@ -5,7 +5,7 @@
 
 == Overview
 
-This dev container uses `cgr.dev/chainguard/wolfi-base` with git, curl, bash, and just pre-installed. Dev container features add git, just, and nickel automatically.
+This dev container uses `cgr.dev/chainguard/wolfi-base` with git, curl, bash, and just pre-installed. Dev container features add git, just, nickel, and Julia 1.10 (via Juliaup) automatically.
 
 == VS Code (Local)
 
@@ -25,4 +25,4 @@ This dev container uses `cgr.dev/chainguard/wolfi-base` with git, curl, bash, an
 
 == Customization
 
-Replace `Statistikles` placeholders in both `devcontainer.json` and `Containerfile` with your actual project name. Run `just deps` to verify the environment after first launch.
+Run `just setup` to verify the environment after first launch (already run automatically by `postCreateCommand`).

.devcontainer/devcontainer.json

@@ -18,10 +18,13 @@
       "version": "latest"
     },
     "ghcr.io/jdx/devcontainer-features/just:1": {},
-    "ghcr.io/nickel-lang/devcontainer-feature:0": {}
+    "ghcr.io/nickel-lang/devcontainer-feature:0": {},
+    "ghcr.io/julialang/devcontainer-features/julia:1": {
+      "channel": "1.10"
+    }
   },
 
-  "postCreateCommand": "just deps",
+  "postCreateCommand": "just setup",
 
   "remoteUser": "nonroot",
 
@@ -34,6 +37,7 @@
     "vscode": {
       "extensions": [
         "EditorConfig.EditorConfig",
+        "julialang.language-julia",
         "eamodio.gitlens",
         "streetsidesoftware.code-spell-checker",
         "timonwong.shellcheck",

.dockerignore

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: MPL-2.0
+# Build-context excludes for `docker build`/`podman build` (Containerfile,
+# .devcontainer/Containerfile). Podman falls back to this file when no
+# .containerignore is present.
+
+.git/
+.github/
+.devcontainer/
+docs/
+proofs/
+ffi/
+benches/
+examples/
+generated/
+.claude/
+node_modules/
+*.log
+/tmp/

.github/workflows/container-build.yml

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# Statistikles — Container Build
+#
+# Builds the root Containerfile so it cannot silently rot back into a
+# template stub. Build only — no push, no registry login.
+
+name: Container Build
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'Containerfile'
+      - '.dockerignore'
+      - 'Project.toml'
+      - 'Manifest.toml'
+      - 'src/**'
+      - '.github/workflows/container-build.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'Containerfile'
+      - '.dockerignore'
+      - 'Project.toml'
+      - 'Manifest.toml'
+      - 'src/**'
+      - '.github/workflows/container-build.yml'
+  workflow_dispatch:
+
+permissions: read-all
+
+concurrency:
+  group: container-build-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: docker build .
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+
+      - name: Build Containerfile
+        run: docker build -f Containerfile -t statistikles:ci .
+
+      - name: Smoke — run the entrypoint
+        run: |
+          # No LM Studio endpoint is reachable from the runner, so main()
+          # (src/tools/chat.jl) takes its documented offline-demo fallback
+          # and exits 0 — see the Containerfile's ENTRYPOINT comment and
+          # QUICKSTART-USER.adoc "First Run".
+          docker run --rm statistikles:ci | tee /tmp/container-run.log
+          grep -q "Statistikles v0.1.0" /tmp/container-run.log
+          grep -q "Cannot connect to LM Studio" /tmp/container-run.log
+          grep -q "All numbers above were computed by Julia, not an LLM." /tmp/container-run.log

Containerfile

@@ -5,37 +5,39 @@
 # Build: podman build -t statistikles:latest -f Containerfile .
 # Run:   podman run --rm -it statistikles:latest
 # Seal:  selur seal statistikles:latest
-
-# --- Build stage ---
-FROM cgr.dev/chainguard/wolfi-base:latest AS build
-
-# TODO: Install build dependencies for your stack
-# Examples:
-#   RUN apk add --no-cache rust cargo       # Rust
-#   RUN apk add --no-cache elixir erlang    # Elixir
-#   RUN apk add --no-cache zig              # Zig
-
-WORKDIR /build
-COPY . .
-
-# TODO: Replace with your build command
-# Examples:
-#   RUN cargo build --release
-#   RUN mix deps.get && MIX_ENV=prod mix release
-#   RUN zig build -Doptimize=ReleaseSafe
-
-# --- Runtime stage ---
-FROM cgr.dev/chainguard/static:latest
-
-# Copy built artifact from build stage
-# TODO: Replace with your binary/artifact path
-# Examples:
-#   COPY --from=build /build/target/release/statistikles /usr/local/bin/
-#   COPY --from=build /build/_build/prod/rel/statistikles /app/
-#   COPY --from=build /build/zig-out/bin/statistikles /usr/local/bin/
-
-# Non-root user (chainguard images default to nonroot)
-USER nonroot
-
-# TODO: Replace with your entrypoint
-# ENTRYPOINT ["/usr/local/bin/statistikles"]
+#
+# Statistikles is a pure Julia package with no compiled binary artifact (see
+# "Build from Source" in QUICKSTART-MAINTAINER.adoc) — the `julia` executable
+# itself is the runtime, so there is nothing a separate build stage could
+# hand off that the runtime doesn't also need. A single stage on the official
+# Julia image is therefore correct here, not a shortcut. Chainguard ships no
+# Julia package, so the org-default Wolfi/static base (docs/AI-CONVENTIONS.md)
+# does not apply to this stack.
+
+# docker.io/library/julia:1.10 == Julia 1.10.11 (Debian trixie), matching the
+# `julia_version` pinned in the committed Manifest.toml and .tool-versions.
+FROM docker.io/library/julia:1.10@sha256:12477d07306333f0c59c04274196432a3834f8c44a0a10585de659fbf8ab0e54
+
+# Non-root runtime user
+RUN useradd --create-home --uid 1000 --shell /bin/bash statistikles
+WORKDIR /app
+COPY --chown=statistikles:statistikles . .
+USER statistikles
+ENV JULIA_DEPOT_PATH=/home/statistikles/.julia
+
+# Resolve the committed Manifest.toml exactly (no re-resolution) and
+# precompile so the entrypoint starts promptly.
+RUN julia --project=. -e 'using Pkg; Pkg.instantiate(); Pkg.precompile()'
+
+# `main()` (src/tools/chat.jl) prints the startup banner, then tries to reach
+# an LM Studio-compatible endpoint (STATISTIKLES_LM_URL, default
+# http://localhost:1234/v1). With no LLM endpoint reachable from the
+# container it prints "Cannot connect..." and runs the offline
+# `run_examples()` demo instead, then exits 0 — it does not hang waiting for
+# input. Run with `--network=host` to reach a host-side LM Studio at the
+# default address for the interactive chat session instead. NOTE: setting
+# STATISTIKLES_LM_URL at `docker/podman run` time has no effect — Julia's
+# Pkg.precompile() above already baked the default URL into the package's
+# precompile cache; to change it, set STATISTIKLES_LM_URL as an image build
+# ENV before the RUN Pkg.precompile() line and rebuild.
+ENTRYPOINT ["julia", "--project=/app", "-e", "using Statistikles; main()"]

QUICKSTART-MAINTAINER.adoc

@@ -45,9 +45,38 @@ the full Julia dependency closure from source — the closure is instantiated on
 from the pinned `Manifest.toml` into a writable depot on first use (see the
 header comment in `guix.scm` for the rationale and the exact command).
 
-The container (`Containerfile`) packaging surface exists in the repository but is
-not yet functional — do not base a container distribution on it until it is
-completed.
+The `Containerfile` also builds a runnable image (see "Container" below).
+
+== Container
+
+[source,bash]
+----
+podman build -t statistikles:latest -f Containerfile .
+podman run --rm -it statistikles:latest
+----
+
+(`docker` works identically in place of `podman`.) The image is built from
+the official `docker.io/library/julia:1.10` base (pinned by digest in the
+Containerfile), runs as a non-root user, and its `ENTRYPOINT` is the same
+`main()` entry point as `just run`. With no LLM endpoint reachable from the
+container it falls back to the offline `run_examples()` demo and exits 0 —
+see "First Run" in QUICKSTART-USER.adoc for the exact expected output. To
+reach a host-side LM Studio instance at the default address instead:
+
+[source,bash]
+----
+podman run --rm -it --network=host statistikles:latest
+----
+
+NOTE: `STATISTIKLES_LM_URL` set at `podman run` time has **no effect** on a
+precompiled image or a precompiled native install — verified by testing both.
+`Pkg.precompile()` evaluates and caches `BASE_URL` (`src/tools/lmstudio.jl`)
+into the package's precompile image at the time it runs; loading the package
+afterwards deserializes that cache rather than re-reading `ENV`. This is not
+container-specific — the same applies to `just build && just run` natively.
+To point a built image at a non-default endpoint, set `STATISTIKLES_LM_URL`
+as a build-time `ENV` *before* the `Pkg.precompile()` step in the
+Containerfile and rebuild.
 
 == Configuration
 

QUICKSTART-USER.adoc

@@ -37,6 +37,8 @@ Before you begin, ensure you have:
 
 == Install
 
+=== Option 1: Native Julia
+
 [source,bash]
 ----
 # Clone and set up
@@ -56,6 +58,23 @@ If you prefer not to use just, the equivalent raw command is:
 julia --project=. -e 'using Pkg; Pkg.instantiate()'
 ----
 
+=== Option 2: Container
+
+No local Julia install required — just Podman or Docker:
+
+[source,bash]
+----
+git clone https://github.com/hyperpolymath/statistikles.git
+cd statistikles
+podman build -t statistikles:latest -f Containerfile .
+podman run --rm -it statistikles:latest
+----
+
+(`docker` works identically in place of `podman`.) This builds the official
+`docker.io/library/julia:1.10` base image with the project instantiated and
+precompiled, then runs it as a non-root user. Expected output matches
+"First Run" below.
+
 == First Run
 
 [source,bash]