readingbat · pambrose · Jul 3, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to this repository are documented here.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This repository has never used version tags or formal releases, so entries are
+grouped by date and milestone rather than semantic version. The content tracks
+the [readingbat-core](https://github.com/readingbat/readingbat-core) platform, so
+many entries reflect dependency and toolchain upgrades.
+
+## [Unreleased]
+
+### Changed
+- Bumped the Gradle JVM toolchain to **25**.
+- Upgraded dependencies: readingbat-core `3.1.8` → `3.2.1`, common-utils `2.9.0` → `2.9.3`,
+  Ktor `3.5.0` → `3.5.1`, Kotest `6.1.11` → `6.2.1`, detekt `2.0.0-alpha.3` → `2.0.0-alpha.5`,
+  and the Gradle wrapper `9.5.1` → `9.6.1`.
+
+## 2026-06 — Tooling polish
+
+### Changed
+- Reworked the Makefile: added a self-documenting `help` target and cleaned up the build targets (#14).
+
+## 2026-05 — CI, linting, and package conventions
+
+### Added
+- CI workflow that runs tests and lint on every push and pull request (#13).
+- Lint and format tooling: detekt static analysis and kotlinter formatting, wired into the build (#12).
+
+### Changed
+- Renamed packages to camelCase for idiomatic consistency (#12).
+- Centralized the Gradle and JVM versions in `gradle/libs.versions.toml` (#11).
+- Refreshed build configuration and documentation (#10).
+- Upgraded the Gradle wrapper to `9.5.0`.
+
+## 2026-04 — Namespace migration
+
+### Changed
+- Migrated packages off the `com.github` namespace to the project's own namespaces.
+- Bumped readingbat-core through `3.1.1` → `3.1.2` → `3.1.4`, plus Kotlin, Ktor, common-utils, and the versions plugin.
+- Cleaned up `.gitignore`.
+
+### Added
+- `readingbat-kotest` test dependency for challenge validation helpers.
+
+## 2026-03 — Major content expansion & pedagogy
+
+### Added
+- **126 new challenges across 15 new topics**, spanning both Java and Kotlin groups
+  (including Kotlin scope functions, fold/reduce, zip/partition, collection transformations,
+  ranges, null safety, when expressions, and string templates).
+- Pedagogical `@desc` hints on every challenge file so students see guidance in the UI.
+- Project guidance files: `CLAUDE.md` and `llms.txt`.
+
+### Changed
+- Reordered groups by difficulty — warmups first, then easiest to hardest.
+- Rewrote the test suite to Kotest `StringSpec` `init {}` style.
+- Bumped readingbat-core to `3.0.4`, then `3.0.5`.
+- Upgraded the Gradle wrapper to `9.4.0` / `9.4.1`; enabled the Gradle daemon,
+  configure-on-demand, and build caching.
+- Simplified `ContentServer`.
+
+### Fixed
+- Corrected challenge metadata and assorted bugs.
+- Normalized blank-line spacing above `@desc` in Kotlin challenge files.
+
+## 2025 — Build modernization
+
+### Changed
+- Converted the Groovy `build.gradle` to Kotlin DSL (`build.gradle.kts`) and adopted a
+  Gradle version catalog (`gradle/libs.versions.toml`).
+- Upgraded to Kotlin `2.2.x`, Ktor `3.x`, and Kotest `6.0.0`.
+- Upgraded the Gradle wrapper to `9.0.0`.
+- Changed the group ID to `com.github.pambrose.readingbat`.
+- Bumped readingbat-core into the `2.1.x` line.
+
+## 2024 — Kotlin 2.x and Ktor 3
+
+### Changed
+- Upgraded Kotlin `2.0.0` → `2.1.0`.
+- Adopted Ktor `3.0.1`.
+- Upgraded readingbat-core to `2.0.0`.
+
+## 2021–2023 — Ongoing maintenance
+
+### Added
+- `funcSum` exercises.
+
+### Changed
+- Upgraded Kotlin from `1.5.0` through the `1.9.x` line.
+- Upgraded readingbat-core to `1.11.1` and beyond.
+- Updated package names and cleaned up the build script.
+- Regular dependency ("jar") refreshes.
+
+### Fixed
+- Assorted typos and Java challenge corrections.
+
+## 2020-11 — Test suite
+
+### Added
+- `ContentTests.kt` — a Kotest suite that validates every challenge through a Ktor
+  test host (empty answers report `NOT_ANSWERED`, wrong answers `INCORRECT`, correct
+  answers `CORRECT`).
+- Dedicated test content.
+
+## 2020-04 — Initial release
+
+### Added
+- Initial content repository built on the `readingBatContent` DSL in `Content.kt`.
+- First Java challenge groups: warmups, boolean expressions, math operations, if/switch
+  statements, for/while/nested loops, string and character operations, arrays, and recursion.
+- Gitpod configuration and the Code Runner setup for local development.
+- Apache License 2.0.
diff --git a/README.md b/README.md
@@ -1,25 +1,48 @@
 # ReadingBat Java Content
 
-Java and Kotlin programming challenges for the [ReadingBat](https://github.com/readingbat/readingbat-core) platform. This repository defines challenge content that the ReadingBat server renders as interactive coding exercises.
+Java and Kotlin programming challenges for the [ReadingBat](https://github.com/readingbat/readingbat-core)
+platform. This repository defines the challenge content that the ReadingBat server
+renders as interactive coding exercises — it is not a standalone application.
+
+More than 200 challenges are organized into 25 groups (14 Java, 11 Kotlin), ordered
+by difficulty from warmups through recursion, lambdas, and collection transformations.
 
 ## Getting Started
 
-Requires JDK 17+.
+Requires a JDK compatible with the Gradle JVM toolchain. The toolchain version is
+centralized in `gradle/libs.versions.toml` (the `jvm` key); Gradle will provision it
+automatically.
 
 ```bash
-./gradlew build -x test         # Compile
+./gradlew build -x test         # Compile without running tests
 ./gradlew run                   # Start the content server on http://localhost:8080
 ./gradlew --rerun-tasks check   # Run all tests
 ./gradlew test --tests "ContentTests"           # Run a single test class
 ./gradlew test -Dkotest.filter.tests="<name>"   # Filter Kotest cases by name
-make uberjar                    # Build fat jar at build/libs/server.jar
 ```
 
-When running locally, challenge files are loaded directly from disk (via `FileSystemSource`), so edits are picked up on reload without a rebuild. Production builds load content from this GitHub repository.
+A `Makefile` wraps the common tasks — run `make` (or `make help`) to see them all:
+
+```bash
+make build          # Compile without tests
+make tests          # Run all tests
+make lint           # Run kotlinter + detekt
+make format         # Format Kotlin sources with kotlinter
+make cc             # Continuous compilation (watches for changes)
+make run            # Start the content server locally (port 8080)
+make uberjar        # Build fat jar at build/libs/server.jar
+make uber           # Build the uberjar and run it
+make versions       # Check for dependency updates
+```
+
+When running locally, challenge files are loaded directly from disk (via
+`FileSystemSource`), so edits are picked up on reload without a rebuild. Production
+builds load content from this GitHub repository instead.
 
 ## Challenge Structure
 
-Each challenge is a standalone source file with a `main()` that prints expected outputs. Those output lines become the answer key for the exercise.
+Each challenge is a standalone source file with a `main()` that prints expected
+outputs. Those output lines become the answer key for the exercise.
 
 **Java** (`src/main/java/<package>/`):
 ```java
@@ -45,4 +68,57 @@ fun main() {
 }
 ```
 
-All challenges are registered in `src/main/kotlin/Content.kt` using the `readingBatContent` DSL.
+The `@desc` comment (markdown-aware) provides the challenge description shown to
+students. Kotlin challenges require an explicit `returnType` (e.g. `IntType`,
+`StringType`, `IntListType`) when registered.
+
+All challenges are registered in `src/main/kotlin/Content.kt` using the
+`readingBatContent` DSL, either individually via `challenge("ClassName")` or in bulk
+via `includeFiles` / `includeFilesWithType` glob patterns.
+
+## Content Catalog
+
+**Java groups** — Warmup 1 & 2, Boolean Expressions, Math Operations, If Statements,
+Switch Statements, For Loops, While Loops, String Operations, Character Operations,
+Arrays, Nested Loops, Recursion, and 2D Arrays.
+
+**Kotlin groups** — String Templates, When Expressions, Ranges, Null Safety, Lambda
+Intro, Misc Lambdas, Strings, Collection Transformations, Fold and Reduce, Zip and
+Partition, and Scope Functions.
+
+## Project Layout
+
+```
+src/main/kotlin/Content.kt        # Central DSL declaring all challenges by language/group
+src/main/kotlin/ContentServer.kt  # Server entry point (delegates to readingbat-core)
+src/main/java/<package>/*.java     # Java challenge files
+src/main/kotlin/<package>/*.kt     # Kotlin challenge files
+src/main/resources/application.conf # HOCON server config (content, site, Ktor settings)
+src/test/kotlin/ContentTests.kt    # Kotest suite validating every challenge
+gradle/libs.versions.toml          # Centralized dependency & toolchain versions
+```
+
+## Tech Stack
+
+- Kotlin / JVM, Gradle (Kotlin DSL) with a version catalog
+- [readingbat-core](https://github.com/readingbat/readingbat-core) — the platform library (from JitPack)
+- Ktor test host + Kotest — challenge validation
+- detekt + kotlinter — static analysis and formatting
+
+## Testing
+
+`ContentTests.kt` uses Kotest `StringSpec` with Ktor's `testApplication` to validate
+every challenge: empty answers must report `NOT_ANSWERED`, wrong answers `INCORRECT`,
+and the expected outputs `CORRECT`. A CI workflow runs the tests and lint on every
+push and pull request.
+
+## Documentation
+
+- [CHANGELOG.md](CHANGELOG.md) — dated history of notable changes
+- [RELEASE_NOTES.md](RELEASE_NOTES.md) — narrative summary of major milestones
+- [CLAUDE.md](CLAUDE.md) — guidance for AI-assisted development
+- `llms.txt` — machine-readable project summary
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -0,0 +1,57 @@
+# Release Notes
+
+This repository provides the Java and Kotlin challenge content for the
+[ReadingBat](https://github.com/readingbat/readingbat-core) platform. It is not
+formally versioned or tagged; instead, it evolves continuously and tracks the
+readingbat-core releases it depends on. These notes summarize the notable
+milestones in narrative form. For the full, dated list of changes, see
+[CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## Current focus (2026)
+
+2026 has been the most active year for the project since its founding, shifting
+emphasis from pure maintenance to content and developer experience.
+
+- **A large content expansion** in March 2026 added 126 new challenges across 15
+  new topics. The Kotlin side in particular grew well beyond the basics to cover
+  scope functions (`let`/`run`/`also`/`with`), fold and reduce, zip and partition,
+  collection transformations, ranges, null safety, when expressions, and string
+  templates. Groups were reordered by difficulty so learners progress from warmups
+  outward, and every challenge gained a `@desc` hint that surfaces guidance in the UI.
+- **Developer experience** was overhauled: the test suite was rewritten in the
+  Kotest `StringSpec` style, `CLAUDE.md` and `llms.txt` were added for AI-assisted
+  workflows, detekt and kotlinter were wired in for static analysis and formatting,
+  and a CI workflow now runs tests and lint on every push and pull request.
+- **Housekeeping** included migrating packages off the `com.github` namespace,
+  renaming packages to idiomatic camelCase, centralizing all tool and dependency
+  versions in `gradle/libs.versions.toml`, and adding a self-documenting Makefile.
+
+## Build modernization (2024–2025)
+
+The build was brought fully up to date with the modern Kotlin and Ktor ecosystems.
+The project moved from a Groovy `build.gradle` to the Kotlin DSL with a Gradle
+version catalog, upgraded to Kotlin 2.x, Ktor 3.x, and Kotest 6, and adopted
+Gradle 9. readingbat-core advanced through its 2.x line during this period.
+
+## Steady maintenance (2021–2023)
+
+For several years the repository was kept current with the platform: Kotlin was
+upgraded from 1.5 through the 1.9 series, readingbat-core moved to 1.11.1 and
+beyond, `funcSum` exercises were added, and dependencies were refreshed regularly.
+
+## Test coverage (late 2020)
+
+`ContentTests.kt` established automated validation of the entire challenge catalog.
+Running against a Ktor test host, it verifies that empty submissions report as
+not answered, wrong submissions as incorrect, and the expected outputs as correct —
+turning every challenge's `main()` output into an enforced answer key.
+
+## Initial release (April 2020)
+
+The repository launched as a content definition built on the `readingBatContent`
+DSL. The first groups covered the Java fundamentals — warmups, boolean expressions,
+math, if/switch statements, loops, strings, arrays, and recursion — with Gitpod and
+Code Runner set up for a browser-based development experience. Released under the
+Apache License 2.0.