fix: make the documented install path real (Justfile recipes, quickst… (#34)

…arts, smoke CI)

PR 4 of 8 in the severity-ordered RCA chain (P0-docs): the primary
user-facing install docs drove `just` recipes that were template stubs,
so a new user following any quickstart could not install or run the
software. This makes the documented path real and adds CI so it cannot
silently rot.

- Justfile: implement setup (Pkg.instantiate), deps (alias of setup),
build/build-release (Pkg.precompile), run/run-verbose (main()); add a
julia check to doctor; fix an invalid `//` comment on line 2 that made
modern `just` fail to parse the file at all
- QUICKSTART-USER.adoc: replace template placeholders with a real
minimal quickstart; expected output now matches what main() actually
prints (banner + LM Studio fallback to offline examples); drop
references to nonexistent stapeln-run/install/uninstall recipes
- QUICKSTART-DEV.adoc: replace
{{LANG_STACK}}/{{BUILD_CMD}}/{{TEST_CMD}}/ {{MUST_INVARIANTS}} with real
Julia commands and invariants; fix setup-dev -> setup, tests/ -> test/,
Mustfile path; drop panic-scan/ llm-context/flake.nix references
- QUICKSTART-MAINTAINER.adoc: trim to flows that work (build-release,
doctor, load check, test); mark Containerfile/guix.scm as not yet
functional; document the real env-var configuration
- docs/QUICKSTART.md: was cloning a different repo (rsr-template-repo);
reduced to a pointer at the canonical quickstarts
- .tool-versions: pin julia 1.10.11 (same minor as e2e.yml CI)
- README.adoc: correct module count 17 -> 40 (src/stats/*.jl)
- .github/workflows/install-smoke.yml: NEW smoke job running `just setup
&& julia --project=. -e 'using Statistikles' && just --list` on
ubuntu-latest with SHA-pinned checkout/setup-julia/cache/setup-just;
step-level guards only (no job-level hashFiles/secrets conditionals)

Verified locally (WSL Debian, Julia 1.10.11, just 1.56.0): just --list
parses; every recipe referenced by any quickstart exists; just setup,
package load, just run (offline fallback), just doctor all pass.

<!--
SPDX-License-Identifier: CC-BY-SA-4.0
Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-->
## Summary

<!-- Briefly describe what this PR does and why. Link to related issues
with "Closes #N". -->

## Changes

<!-- List the key changes introduced by this PR. -->

-

## RSR Quality Checklist

<!-- Check all that apply. PRs that fail required checks will not be
merged. -->

### Required

- [ ] Tests pass (`just test` or equivalent)
- [ ] Code is formatted (`just fmt` or equivalent)
- [ ] Linter is clean (no new warnings or errors)
- [ ] No banned language patterns (no TypeScript, no npm/bun, no
Go/Python)
- [ ] No `unsafe` blocks without `// SAFETY:` comments
- [ ] No banned functions (`believe_me`, `unsafeCoerce`, `Obj.magic`,
`Admitted`, `sorry`)
- [ ] SPDX license headers present on all new/modified source files
- [ ] No secrets, credentials, or `.env` files included

### As Applicable

- [ ] `.machine_readable/STATE.a2ml` updated (if project state changed)
- [ ] `.machine_readable/ECOSYSTEM.a2ml` updated (if integrations
changed)
- [ ] `.machine_readable/META.a2ml` updated (if architectural decisions
changed)
- [ ] Documentation updated for user-facing changes
- [ ] `TOPOLOGY.md` updated (if architecture changed)
- [ ] `CHANGELOG` or release notes updated
- [ ] New dependencies reviewed for license compatibility (MPL-2.0 /
MPL-2.0)
- [ ] ABI/FFI changes validated (`src/abi/` and `ffi/zig/` consistent)

## Testing

<!-- Describe how you tested these changes. -->

## Screenshots

<!-- If applicable, add screenshots or terminal output demonstrating the
change. -->

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

Author: hyperpolymath

.github/workflows/install-smoke.yml

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# Statistikles — Install Smoke Test
+#
+# Exercises the documented install path (QUICKSTART-USER.adoc) so it cannot
+# silently rot: `just setup` must instantiate the environment, the package
+# must load, and the Justfile must parse.
+
+name: Install Smoke
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'Justfile'
+      - 'Project.toml'
+      - 'src/**'
+      - '.tool-versions'
+      - '.github/workflows/install-smoke.yml'
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: read-all
+
+concurrency:
+  group: install-smoke-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  install-smoke:
+    name: Smoke — Documented Install Path
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+
+      - name: Setup Julia
+        uses: julia-actions/setup-julia@fa02766e078afaaf09b14210362cee14137e6a32  # v2
+        with:
+          version: '1.10'
+
+      - name: Julia cache
+        uses: julia-actions/cache@a45e8fa8be21c18a06b7177052533149e61e9b38  # v3.1.0
+
+      - name: Setup just
+        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3  # v4.0.0
+
+      - name: Run documented install path
+        run: just setup && julia --project=. -e 'using Statistikles' && just --list

.tool-versions

@@ -1 +1,2 @@
 just 1.36.0
+julia 1.10.11

Justfile

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MPL-2.0
-// Owner: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+# Owner: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
 # RSR Standard Justfile Template
@@ -239,25 +239,14 @@ init:
 # BUILD & COMPILE
 # ═══════════════════════════════════════════════════════════════════════════════
 
-# Build the project (debug mode)
-build *args:
-    @echo "Building statistikles (debug)..."
-    # TODO: Replace with your build command
-    # Examples:
-    #   cargo build {{args}}                    # Rust
-    #   mix compile {{args}}                    # Elixir
-    #   zig build {{args}}                      # Zig
-    #   deno task build {{args}}                # Deno/ReScript
+# Build the project (precompile the Julia environment)
+build *args: setup
+    @echo "Precompiling statistikles..."
+    julia --project=. -e 'using Pkg; Pkg.precompile()'
     @echo "Build complete"
 
-# Build in release mode with optimizations
-build-release *args:
-    @echo "Building statistikles (release)..."
-    # TODO: Replace with your release build command
-    # Examples:
-    #   cargo build --release {{args}}
-    #   MIX_ENV=prod mix compile {{args}}
-    #   zig build -Doptimize=ReleaseFast {{args}}
+# Release build — same as `build` (Julia has no separate release mode)
+build-release *args: build
     @echo "Release build complete"
 
 # Build and watch for changes (requires entr or similar)
@@ -343,15 +332,13 @@ lint:
 # RUN & EXECUTE
 # ═══════════════════════════════════════════════════════════════════════════════
 
-# Run the application
+# Run the assistant (falls back to offline examples if LM Studio is absent)
 run *args: build
-    # TODO: Replace with your run command
-    echo "Run not configured yet"
+    julia --project=. -e 'using Statistikles; main()'
 
-# Run with verbose output
+# Run with verbose output (traces method precompilation)
 run-verbose *args: build
-    # TODO: Replace with verbose run command
-    echo "Run not configured yet"
+    julia --project=. --trace-compile=stderr -e 'using Statistikles; main()'
 
 # Install to user path
 install: build-release
@@ -362,14 +349,14 @@ install: build-release
 # DEPENDENCIES
 # ═══════════════════════════════════════════════════════════════════════════════
 
-# Install/check all dependencies
-deps:
-    @echo "Checking dependencies..."
-    # TODO: Replace with your dependency check
-    # Examples:
-    #   cargo check
-    #   mix deps.get
-    #   gleam deps download
+# One-time setup: resolve and install Julia package dependencies
+setup:
+    @command -v julia >/dev/null 2>&1 || { echo "Julia not found — install Julia 1.10+ from https://julialang.org/downloads/"; exit 1; }
+    julia --project=. -e 'using Pkg; Pkg.instantiate()'
+    @echo "Setup complete — try 'just run'"
+
+# Install/check all dependencies (alias of `setup`)
+deps: setup
     @echo "All dependencies satisfied"
 
 # Audit dependencies for vulnerabilities
@@ -729,6 +716,7 @@ doctor:
     @echo "Checking required tools..."
     @command -v just >/dev/null 2>&1 && echo "  [OK] just" || echo "  [FAIL] just not found"
     @command -v git >/dev/null 2>&1 && echo "  [OK] git" || echo "  [FAIL] git not found"
+    @command -v julia >/dev/null 2>&1 && echo "  [OK] julia ($(julia --version))" || echo "  [FAIL] julia not found — install Julia 1.10+"
     @echo "Checking for hardcoded paths..."
     @grep -rn '$HOME\|$ECLIPSE_DIR' --include='*.rs' --include='*.ex' --include='*.res' --include='*.gleam' --include='*.sh' . 2>/dev/null | head -5 || echo "  [OK] No hardcoded paths"
     @echo "Diagnostics complete."

QUICKSTART-DEV.adoc

@@ -1,80 +1,76 @@
 // SPDX-License-Identifier: CC-BY-SA-4.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-// Template: QUICKSTART-DEV.adoc — clone → build → test → PR
-// Replace statistikles, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals
 = statistikles — Quick Start for Developers
 :toc:
 :toclevels: 2
 
 == Tech Stack
 
-{{LANG_STACK}}
+* **Julia 1.10+** — all statistical computation and the CLI
+  (dependencies: CSV, DataFrames, Distributions, HTTP, JSON3, StatsBase)
+* **Agda** — formal proofs in `proofs/` (not required to build or test)
+* **Zig** — FFI bridge in `ffi/zig/` (not required to build or test)
+* Optional: an OpenAI-compatible LLM endpoint (LM Studio by default) for the
+  conversational interface
 
 == Set Up Development Environment
 
-=== Option A: Guix (preferred)
-
-[source,bash]
-----
-guix shell
-----
-
-=== Option B: Nix (fallback)
-
-[source,bash]
-----
-nix develop
-----
-
-=== Option C: Manual
-
 [source,bash]
 ----
 git clone https://github.com/hyperpolymath/statistikles.git
 cd statistikles
-just setup-dev
+just setup
 ----
 
+`just setup` runs `julia --project=. -e 'using Pkg; Pkg.instantiate()'` to
+resolve and install the Julia package dependencies.
+
 == Build
 
 [source,bash]
 ----
-{{BUILD_CMD}}
+just build
 ----
 
+This precompiles the Julia project environment
+(`julia --project=. -e 'using Pkg; Pkg.precompile()'`).
+
 == Test
 
 [source,bash]
 ----
-{{TEST_CMD}}
+just test
 ----
 
+This runs the full suite via `julia --project=. test/runtests.jl`.
+
 == Project Structure
 
 [source]
 ----
 statistikles/
-├── src/                  # Source code
-├── src/abi/              # Idris2 ABI definitions (if applicable)
-├── ffi/zig/              # Zig FFI bridge (if applicable)
-├── tests/                # Test suite
+├── src/                  # Julia source (module: Statistikles)
+├── src/stats/            # Statistical function modules
+├── src/tools/            # Executor, chat, LM Studio client
+├── proofs/               # Agda proofs
+├── ffi/zig/              # Zig FFI bridge
+├── test/                 # Test suite (runtests.jl)
 ├── docs/                 # Documentation
 ├── .machine_readable/    # Checkpoint files (STATE, META, ECOSYSTEM)
 ├── Justfile              # Task runner recipes
-├── guix.scm              # Guix environment
-├── flake.nix             # Nix environment (fallback)
 └── 0-AI-MANIFEST.a2ml    # AI agent entry point
 ----
 
 == Key Recipes
 
 [source,bash]
 ----
-just build          # Build the project
+just setup          # Install Julia package dependencies
+just build          # Precompile the project environment
 just test           # Run tests
+just run            # Run the assistant
 just doctor         # Self-diagnostic
 just lint           # Lint and format
-just panic-scan     # Security scan via panic-attacker
 just tour           # Guided tour of the codebase
 ----
 
@@ -84,26 +80,24 @@ just tour           # Guided tour of the codebase
 ----
 just lint           # Format and lint
 just test           # All tests pass
-just panic-scan     # No new security issues
 ----
 
 == Contractile Invariants
 
-Read `.machine_readable/MUST.contractile` before making changes.
+Read `.machine_readable/contractiles/Mustfile.a2ml` before making changes.
 Key invariants that must never be violated:
 
-{{MUST_INVARIANTS}}
+* **Neural-symbolic boundary**: no statistical value is ever produced by
+  neural inference. Every number crosses `src/tools/executor.jl:execute_tool()`
+  upward only after being computed by a verified Julia function.
+* No dangerous escape hatches in `src/` (`believe_me`, `assert_total`,
+  `sorry`, `Admitted`) — enforced by CI.
+* SPDX license headers on source files.
 
 == LLM/AI Agent Development
 
-If using an AI assistant, load the warmup context first:
-
-[source,bash]
-----
-just llm-context    # Outputs role-appropriate context
-----
-
-Or read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` directly.
+If using an AI assistant, read `0-AI-MANIFEST.a2ml` first — it is the AI
+agent entry point and links the machine-readable state files.
 
 == Get Help