setup: full scaffold post-green-light (chapters, apps, specs, ADRs, CI)

Phase 0.5 complete. Ready to open Chapter 1.

Chapter notes (docs/chapters/01-*.md through 18-*.md):
- 18 chapters, teaching-ladder structure (intuition → formal → tiny
  example → Python → Kotlin via cpsat-kt → MiniZinc where it helps →
  exercises → self-check → what-unlocks).
- Dual-language parity maintained. Ch. 2 is the only chapter that
  uses raw com.google.ortools.sat.* in Kotlin (to motivate cpsat-kt).

Python (apps/py-cp-sat/ + apps/py-api/):
- uv workspace, Python 3.12+, OR-Tools 9.15.
- Chapter 2 fully runs (solves 3x+2y=12, x+y≤5, maximize x+y).
- Chapters 4–13 have runnable stubs raising NotImplementedError.
- FastAPI skeleton with /health, /version, stub /solve; 4/4 tests pass.

Kotlin (apps/kt-cp-sat/ + apps/kt-api/):
- Gradle composite build, includes cpsat-kt via includeBuild.
- Chapter 2 raw-Java demo runs (x=2, y=3, OPTIMAL).
- Chapters 4–13 compile as stubs.
- Ktor 3 skeleton with /health, /version.

Web (apps/web/):
- Vite 8 + React 19 + React Router v7 framework mode + TypeScript 5
  + Tailwind 4 + shadcn/ui + TanStack Query 5.
- Backend toggle (Python / Kotlin) with localStorage.
- Build, typecheck, lint, test all green.

Shared contract (apps/shared/):
- openapi.yaml (OpenAPI 3.1) — /health, /version, /solve,
  /solution/{id}, /solutions/{id}/stream (SSE).
- JSON schemas validated against 2020-12.

Specs (specs/nsp-app/):
- 10-file skeleton + README + lock procedure.
- Fills in Chapter 14; unlocked until then.

ADRs (docs/adr/):
- 0000 template (Michael Nygard).
- 0001 cpsat-kt as first-class artifact.
- 0002 stack lock-in v0.2 (JDK 25 / Kotlin 2.1+ / Gradle 9 / Vite+RR7).
- 0003 spec-driven NSP app.
- 0004 dual-language parity.

Data (data/nsp/):
- schema.json (JSON Schema 2020-12).
- toy-01 (3×7×2) and toy-02 (5×14×3) feasible instances.

Tools (tools/):
- validate-schedule.py (exits 0 valid / 1 violations / 2 missing deps).
- setup-all.sh (auto-runs every setup-*.sh in order).

CI (.github/workflows/):
- ci.yml — Python (macOS-14), Kotlin (macOS-14, JDK 25 temurin),
  Web (Ubuntu-24.04, Node 22) parallel jobs.
- release.yml — stub for future Maven Central publish on cpsat-kt-v* tags.

Benchmarks (benchmarks/):
- README with methodology placeholder; results/ + plots/ scaffolded.

Alt solvers (apps/alt-solver/):
- Timefold and Choco stubs for Phase 8 port.

Status docs updated:
- README.md, docs/overview.md, docs/plan.md reflect scaffold-complete
  state. Chapter 1 is open.

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

Author: vpetreski

.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  python:
+    name: Python (py-cp-sat + py-api)
+    runs-on: macos-14
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: py-cp-sat — sync + lint + test
+        working-directory: apps/py-cp-sat
+        run: |
+          uv sync
+          uv run ruff check .
+          uv run pytest
+
+      - name: py-api — sync + test
+        working-directory: apps/py-api
+        run: |
+          uv sync
+          uv run pytest
+
+  kotlin:
+    name: Kotlin (cpsat-kt + kt-cp-sat + kt-api)
+    runs-on: macos-14
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "25"
+          # NOTE: if temurin JDK 25 is not yet published on setup-java at the
+          # time this workflow runs, bump distribution to "zulu" (Azul ships
+          # JDK 25 early) or temporarily fall back to java-version "21" and
+          # add a TODO to revisit.
+
+      - name: Set up Gradle
+        uses: gradle/gradle-build-action@v3
+
+      - name: cpsat-kt — build + test
+        working-directory: libs/cpsat-kt
+        run: ./gradlew build test
+
+      - name: kt-cp-sat — build
+        working-directory: apps/kt-cp-sat
+        run: ./gradlew build
+
+      - name: kt-api — build
+        working-directory: apps/kt-api
+        run: ./gradlew build
+
+  web:
+    name: Web (apps/web + apps/shared)
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: |
+            apps/web/package-lock.json
+            apps/shared/package-lock.json
+
+      - name: apps/web — install + typecheck + build
+        working-directory: apps/web
+        run: |
+          npm ci
+          npm run typecheck
+          npm run build
+
+      - name: apps/shared — install + validate OpenAPI
+        working-directory: apps/shared
+        run: |
+          npm ci
+          npm run validate:openapi

.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release cpsat-kt
+
+# STUB — wired up later when we publish cpsat-kt to Maven Central.
+# Triggers only on tags like `cpsat-kt-v0.1.0`.
+
+on:
+  push:
+    tags:
+      - "cpsat-kt-v*"
+
+jobs:
+  publish:
+    name: Publish cpsat-kt to Maven Central
+    runs-on: macos-14
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "25"
+
+      - name: Set up Gradle
+        uses: gradle/gradle-build-action@v3
+
+      # TODO(cpsat-kt publish): wire up the signing + Maven Central flow when
+      # we actually cut v0.1.0. Needs:
+      #   - GPG key + passphrase in GH Secrets
+      #     (SIGNING_KEY, SIGNING_PASSWORD)
+      #   - Sonatype / Central Portal credentials in GH Secrets
+      #     (OSSRH_USERNAME, OSSRH_PASSWORD)
+      #   - `./gradlew :libs:cpsat-kt:publishToMavenCentral --no-configuration-cache`
+      #     (or the equivalent under the Gradle Nexus Publish plugin)
+      #   - Release notes auto-generated from the tag message.
+      - name: Placeholder publish step
+        working-directory: libs/cpsat-kt
+        run: |
+          echo "TODO: run ./gradlew publishToMavenCentral once credentials are wired up"
+          echo "Tag: ${GITHUB_REF_NAME}"

README.md

@@ -30,8 +30,8 @@ Follow these links **in order** on your first pass:
 
 Then, **chapter by chapter from Chapter 1**:
 
-- Open `docs/chapters/01-what-is-cp.md` *(created post-green-light)*
-- Read the chapter, do the exercises in `apps/py-cp-sat/ch01-*/` and `apps/kt-cp-sat/ch01-*/`
+- Open [`docs/chapters/01-what-is-cp.md`](docs/chapters/01-what-is-cp.md)
+- Read the chapter, do the exercises in `apps/py-cp-sat/chNN-*/` and `apps/kt-cp-sat/chNN-*/`
 - Ask Claude when stuck; Claude updates docs/plan as you progress
 - Mark complete in `docs/plan.md`; move to Chapter 2
 
@@ -168,12 +168,19 @@ Full working agreement: [CLAUDE.md](CLAUDE.md).
 - GitHub repo private under `vpetreski/cp-deep-dive`.
 - Memory system primed with user/feedback/project context.
 
-**Phase 0.5 — Plan lock-in: ⏳ In progress**
+**Phase 0.5 — Full scaffold: ✅ Complete**
 
-- [plan.md](docs/plan.md) v0.2 drafted with Vanja's stack choices folded in.
-- Awaiting Vanja's green-light to scaffold the repo (create `libs/cpsat-kt/` skeleton, `specs/nsp-app/`, per-chapter starter apps, CI, etc.).
+- `libs/cpsat-kt/` v0.1.0 library with 41/41 tests passing (`./gradlew test` green).
+- All 18 chapter MDs drafted in `docs/chapters/` with intuition → formal → Python → Kotlin → MiniZinc → exercises structure.
+- Python uv workspace at `apps/py-cp-sat/` (ch02 fully working, ch04–ch13 stubs) + FastAPI skeleton at `apps/py-api/`.
+- Kotlin composite build at `apps/kt-cp-sat/` (ch02 raw-Java demo runs) + Ktor 3 skeleton at `apps/kt-api/`.
+- Web frontend at `apps/web/` (Vite 8 + React 19 + RR7 framework mode + Tailwind 4 + shadcn/ui) — build/test/lint green.
+- `apps/shared/openapi.yaml` (OpenAPI 3.1) + 4 JSON schemas validated against 2020-12.
+- `specs/nsp-app/` 10-file skeleton (unlocked, filled in Chapter 14).
+- 4 ADRs (`docs/adr/`), GitHub Actions CI (Python + Kotlin + Web parallel jobs), `benchmarks/` + `data/nsp/` (toy-01, toy-02 instances + schema).
+- `alt-solver/` Timefold + Choco stubs for Phase 8.
 
-**Phase 1+ — Learning chapters: 🔒 Locked until green-light**
+**Phase 1 — Chapter 1 ready to open:** [`docs/chapters/01-what-is-cp.md`](docs/chapters/01-what-is-cp.md)
 
 ---
 

apps/alt-solver/choco/README.md

@@ -0,0 +1,27 @@
+# Choco Solver — NSP stub
+
+Placeholder for a future port of the Nurse Scheduling Problem to
+[Choco Solver](https://choco-solver.org/), an academic / research-oriented
+Java CP solver with excellent global constraint coverage.
+
+## Status
+
+Not implemented. Tracked in `docs/plan.md`; will be scheduled after the
+CP-SAT NSP chapters (11-13) are complete.
+
+## What to expect here
+
+- Kotlin module using `org.choco-solver:choco-solver`
+- Same instance format as `apps/py-cp-sat/` and `apps/kt-cp-sat/ch11..13`
+- Side-by-side DSL comparison with `cpsat-kt`
+
+## Why Choco?
+
+- Different internals: classical AC-5 / domain-store propagation (as
+  opposed to CP-SAT's lazy clause generation + learning).
+- Rich library of global constraints (especially scheduling: `diffn`,
+  `cumulative`, `geost`).
+- Good for "explain why this is infeasible" workflows via its tracer.
+
+See `docs/knowledge/ecosystem/` in the parent repo for the full
+comparative notes (to be written).

apps/alt-solver/timefold/README.md

@@ -0,0 +1,27 @@
+# Timefold Solver — NSP stub
+
+Placeholder for a future port of the Nurse Scheduling Problem to
+[Timefold Solver](https://timefold.ai/) (the OptaPlanner fork), to compare
+the constraint-streams / local-search approach against CP-SAT's
+constraint-propagation approach.
+
+## Status
+
+Not implemented. Tracked in `docs/plan.md`; will be scheduled after the
+CP-SAT NSP chapters (11-13) are complete.
+
+## What to expect here
+
+- Kotlin module using `timefold-solver-core` + `timefold-solver-constreams`
+- Same instance format as `apps/py-cp-sat/` and `apps/kt-cp-sat/ch11..13`
+- Benchmark harness comparing wall-clock + solution quality vs. CP-SAT
+
+## Why Timefold?
+
+- Different paradigm: local search with construction heuristics, not
+  complete search. Good for huge instances where CP-SAT runs out of time.
+- Java/Kotlin-first API, generates explainable "constraint violation" output.
+- Widely used in enterprise scheduling.
+
+See `docs/knowledge/ecosystem/` in the parent repo for the full
+comparative notes (to be written).

apps/kt-api/Dockerfile

@@ -0,0 +1,14 @@
+# Multi-stage build for the Ktor NSP backend.
+# Stage 1: compile to a distribution tar.
+FROM eclipse-temurin:25-jdk AS build
+WORKDIR /app
+COPY . .
+RUN ./gradlew --no-daemon installDist
+
+# Stage 2: minimal runtime.
+FROM eclipse-temurin:25-jre
+WORKDIR /opt/kt-api
+COPY --from=build /app/build/install/kt-api /opt/kt-api
+EXPOSE 8080
+ENV JAVA_OPTS="-XX:MaxRAMPercentage=75.0 --enable-native-access=ALL-UNNAMED"
+ENTRYPOINT ["/opt/kt-api/bin/kt-api"]

apps/kt-api/README.md

@@ -0,0 +1,45 @@
+# kt-api — Ktor 3 backend for the NSP explorer
+
+Skeleton Ktor 3 app that will eventually host the Nurse Scheduling Problem
+(NSP) endpoints, backed by the `cpsat-kt` library.
+
+## Endpoints today
+
+| Method | Path      | Response |
+|--------|-----------|----------|
+| GET    | /health   | `{"status":"ok"}` |
+| GET    | /version  | `{"name":"kt-api","version":"0.1.0","ortools":"9.15.6755"}` |
+
+## Running locally
+
+```bash
+./gradlew run
+```
+
+The server binds to `0.0.0.0:8080` by default. Override with the `PORT`
+environment variable.
+
+```bash
+curl http://localhost:8080/health
+# {"status":"ok"}
+```
+
+## Building a Docker image
+
+```bash
+docker build -t kt-api:dev -f Dockerfile ..
+```
+
+(The build context is the repo root because the Dockerfile copies the whole
+app directory; adjust to your CI.)
+
+## Configuration
+
+Ktor reads `src/main/resources/application.conf` (HOCON). Environment
+variables override individual fields — e.g. `PORT=9090 ./gradlew run`.
+
+## Requirements
+
+- JDK 25+
+- Gradle 9.x (use bundled wrapper)
+- `libs/cpsat-kt` — included via composite build from `../../libs/cpsat-kt`.

apps/kt-api/build.gradle.kts

@@ -0,0 +1,36 @@
+plugins {
+    alias(libs.plugins.kotlin.jvm)
+    alias(libs.plugins.kotlin.serialization)
+    application
+}
+
+group = "io.vanja"
+version = "0.1.0"
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(25)
+    }
+}
+
+kotlin {
+    jvmToolchain(25)
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_25)
+    }
+}
+
+dependencies {
+    implementation(libs.ktor.server.core)
+    implementation(libs.ktor.server.netty)
+    implementation(libs.ktor.server.content.negotiation)
+    implementation(libs.ktor.serialization.kotlinx.json)
+    implementation(libs.ktor.server.status.pages)
+    implementation(libs.ktor.server.call.logging)
+    implementation(libs.logback.classic)
+    implementation(libs.cpsat.kt)
+}
+
+application {
+    mainClass.set("io.vanja.nspapi.AppKt")
+}

apps/kt-api/gradle.properties

@@ -0,0 +1,4 @@
+kotlin.code.style=official
+org.gradle.jvmargs=-Xmx2g -Dfile.encoding=UTF-8
+org.gradle.parallel=true
+org.gradle.caching=true

apps/kt-api/gradle/libs.versions.toml

@@ -0,0 +1,19 @@
+[versions]
+kotlin = "2.3.20"
+ktor = "3.0.3"
+logback = "1.5.12"
+cpsat-kt = "0.1.0"
+
+[libraries]
+ktor-server-core = { module = "io.ktor:ktor-server-core", version.ref = "ktor" }
+ktor-server-netty = { module = "io.ktor:ktor-server-netty", version.ref = "ktor" }
+ktor-server-content-negotiation = { module = "io.ktor:ktor-server-content-negotiation", version.ref = "ktor" }
+ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }
+ktor-server-status-pages = { module = "io.ktor:ktor-server-status-pages", version.ref = "ktor" }
+ktor-server-call-logging = { module = "io.ktor:ktor-server-call-logging", version.ref = "ktor" }
+logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" }
+cpsat-kt = { module = "io.vanja:cpsat-kt", version.ref = "cpsat-kt" }
+
+[plugins]
+kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
+kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }