JNK234 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -20,15 +20,22 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup Java 17
+      # NetLogo 7.0.4 is compiled for Java 21
+      - name: Setup Java 21
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: "17"
+          java-version: "21"
           cache: sbt
 
       - name: Setup sbt
         uses: sbt/setup-sbt@v1
 
       - name: Run tests
         run: sbt test
+
+      - name: Build release zip
+        run: sbt packageZip
+
+      - name: Check release zip contents
+        run: scripts/check-zip.sh
diff --git a/.gitignore b/.gitignore
@@ -54,6 +54,19 @@ config-*.txt
 !demos/provider-sensitivity/config-multi-provider.txt
 !demos/provider-sensitivity/config.txt
 !demos/social-deduction-game/config.txt
+!demos/config-reference.txt
+!demos/config-placeholder.txt
+
+# Flattened demo copies staged into demos/ by `packageZip` (build artifacts;
+# the canonical sources live in demos/<demo-name>/ subfolders)
+/demos/color-sharing.nlogox
+/demos/social-deduction-game.nlogox
+/demos/topology-tournament.nlogox
+/demos/provider-sensitivity.nlogox
+/demos/el-farol-decisions.nlogox
+/demos/description-template.yaml
+/demos/vote-template.yaml
+/llm-*.zip
 
 # Live e2e harness run artifact
 demos/e2e-tests/e2e-results.txt

diff --git a/BUILD.md b/BUILD.md
@@ -2,8 +2,8 @@
 
 ## Prerequisites
 
-- **Java 17** (required for building)
-- **SBT 1.10.6+** (Scala Build Tool)
+- **Java 21** (required for building; NetLogo 7.0.4 is compiled for Java 21)
+- **SBT 1.10.1** (Scala Build Tool)
 
 ## Run Tests
 
@@ -24,8 +24,8 @@ What this does not validate:
 ### For Development (Fat JAR)
 
 ```bash
-# Set Java 17
-export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+# Set Java 21 (NetLogo 7.0.4 is compiled for Java 21)
+export JAVA_HOME=$(/usr/libexec/java_home -v 21)
 
 # Build single JAR with all dependencies
 sbt clean assembly
@@ -36,8 +36,8 @@ sbt clean assembly
 ### For Distribution (ZIP Package)
 
 ```bash
-# Set Java 17
-export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+# Set Java 21 (NetLogo 7.0.4 is compiled for Java 21)
+export JAVA_HOME=$(/usr/libexec/java_home -v 21)
 
 # Build distribution package
 sbt clean packageZip
@@ -73,15 +73,15 @@ sbt clean packageZip
 ## Common Issues
 
 **Problem**: Build fails with SBT parser errors
-**Solution**: Upgrade SBT to 1.10.6+ in `project/build.properties`:
+**Solution**: Use the SBT version pinned in `project/build.properties`:
 ```
-sbt.version=1.10.6
+sbt.version=1.10.1
 ```
 
 **Problem**: Build fails with Java version errors
-**Solution**: Make sure you're using Java 17:
+**Solution**: Make sure you're using Java 21:
 ```bash
-java -version  # Should show 17.x.x
+java -version  # Should show 21.x.x or newer
 ```
 
 **Problem**: Old JAR still being used

diff --git a/INSTALL.md b/INSTALL.md
@@ -5,22 +5,22 @@
 ### 1. Build the Extension
 
 ```bash
-export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+export JAVA_HOME=$(/usr/libexec/java_home -v 21)
 sbt clean assembly
 ```
 
 ### 2. Install to NetLogo
 
 **macOS:**
 ```bash
-mkdir -p "/Applications/NetLogo 7.0.0/extensions/llm"
-cp target/scala-3.7.0/llm.jar "/Applications/NetLogo 7.0.0/extensions/llm/"
+mkdir -p "/Applications/NetLogo 7.0.4/extensions/llm"
+cp target/scala-3.7.0/llm.jar "/Applications/NetLogo 7.0.4/extensions/llm/"
 ```
 
 **Windows:**
 ```bash
-mkdir "C:\Program Files\NetLogo 7.0.0\extensions\llm"
-copy target\scala-3.7.0\llm.jar "C:\Program Files\NetLogo 7.0.0\extensions\llm\"
+mkdir "C:\Program Files\NetLogo 7.0.4\extensions\llm"
+copy target\scala-3.7.0\llm.jar "C:\Program Files\NetLogo 7.0.4\extensions\llm\"
 ```
 
 **Linux:**
@@ -31,36 +31,36 @@ cp target/scala-3.7.0/llm.jar "/usr/local/NetLogo-7.0.0/extensions/llm/"
 
 ## Install from ZIP Package (Alternative)
 
-If you have a pre-built `llm-0.1.0.zip`:
+If you have a pre-built `llm-1.1.0.zip`:
 
 ### 1. Extract the ZIP
 
 ```bash
-unzip llm-0.1.0.zip
+unzip llm-1.1.0.zip
 ```
 
 ### 2. Copy to NetLogo
 
 **macOS:**
 ```bash
-cp -r llm-0.1.0 "/Applications/NetLogo 7.0.0/extensions/llm"
+cp -r llm-1.1.0 "/Applications/NetLogo 7.0.4/extensions/llm"
 ```
 
 **Windows:**
 ```bash
-xcopy llm-0.1.0 "C:\Program Files\NetLogo 7.0.0\extensions\llm" /E /I
+xcopy llm-1.1.0 "C:\Program Files\NetLogo 7.0.4\extensions\llm" /E /I
 ```
 
 **Linux:**
 ```bash
-cp -r llm-0.1.0 "/usr/local/NetLogo-7.0.0/extensions/llm"
+cp -r llm-1.1.0 "/usr/local/NetLogo-7.0.0/extensions/llm"
 ```
 
 ## Verify Installation
 
 ### 1. Open NetLogo
 
-Launch NetLogo 7.0.0 (or newer)
+Launch NetLogo 7.0.4 (or newer)
 
 ### 2. Test the Extension
 
@@ -114,24 +114,24 @@ Click Setup, then run `test-llm` from the Command Center.
 The extension must be in NetLogo's `extensions/llm/` folder:
 
 **macOS:**
-- `/Applications/NetLogo 7.0.0/extensions/llm/`
+- `/Applications/NetLogo 7.0.4/extensions/llm/`
 
 **Windows:**
-- `C:\Program Files\NetLogo 7.0.0\extensions\llm\`
+- `C:\Program Files\NetLogo 7.0.4\extensions\llm\`
 
 **Linux:**
 - `/usr/local/NetLogo-7.0.0/extensions/llm/`
 
 **Expected structure:**
 ```
-NetLogo 7.0.0/
+NetLogo 7.0.4/
 └── extensions/
     └── llm/
         └── llm.jar          (for Fat JAR install)
 
 OR
 
-NetLogo 7.0.0/
+NetLogo 7.0.4/
 └── extensions/
     └── llm/
         ├── llm.jar

diff --git a/RELEASE.md b/RELEASE.md
@@ -1,133 +1,98 @@
 # Release Process
 
-## Creating a New Release
+Releases ship to users through the NetLogo Extension Manager, which reads
+`libraries.conf` in [NetLogo/NetLogo-Libraries](https://github.com/NetLogo/NetLogo-Libraries).
+A release is: a tagged commit here, a GitHub release with the zip, and a PR
+to NetLogo-Libraries that adds the zip and bumps the version.
 
-### 1. Update Version
+## Requirements
 
-Edit `build.sbt`:
-```scala
-version := "0.2.0"  // Update version number
-```
-
-### 2. Build Release Package
+- **JDK 21 or newer.** NetLogo 7.0.4 is compiled for Java 21; JDK 17 fails with
+  `UnsupportedClassVersionError` on `org.nlogo.api.APIVersion`.
+- **sbt 1.10.1** (pinned in `project/build.properties`; NetLogo notes 1.10.2+ can
+  hit a ZipException).
 
 ```bash
-# Set Java 17
-export JAVA_HOME=$(/usr/libexec/java_home -v 17)
-
-# Build distribution ZIP
-sbt clean packageZip
+export JAVA_HOME=$(/usr/libexec/java_home -v 21+)
 ```
 
-**Output:** `llm-0.2.0.zip` (11MB)
+## 1. Set the version
 
-### 3. Test the Release
+In `build.sbt`:
 
-```bash
-# Automated deterministic tests (no API/network required)
-sbt test
+```scala
+version    := "1.1.0"
+isSnapshot := false   // only for the release build; keep true while developing
+```
 
-# Extract and install release package
-unzip llm-0.2.0.zip
-cp -r llm-0.2.0 "/Applications/NetLogo 7.0.0/extensions/llm"
+With `isSnapshot := false` the plugin refuses to stage the extension from a
+dirty working tree, so commit everything first.
 
-# Optional manual integration checks (real providers)
-# Open NetLogo and run demos/tests/tests.nlogox
-```
+Versioning is semantic: MAJOR for changes that break existing models, MINOR for
+new primitives or providers, PATCH for fixes.
 
-### 4. Create Git Tag
+## 2. Build and check the zip
 
 ```bash
-git add build.sbt llm-0.2.0.zip
-git commit -m "Release v0.2.0"
-git tag v0.2.0
-git push origin main
-git push origin v0.2.0
+sbt clean test packageZip
+scripts/check-zip.sh            # asserts the docs, config files and demos are inside
 ```
 
-### 5. Create GitHub Release
-
-1. Go to: https://github.com/JNK234/Netlogo-LLM-Extension/releases
-2. Click "Create a new release"
-3. Select tag: `v0.2.0`
-4. Title: `LLM Extension v0.2.0`
-5. Attach: `llm-0.2.0.zip`
-6. Write release notes
-7. Publish release
-
-## Release Checklist
+Output: `llm-<version>.zip` in the repo root (gitignored). It contains `llm.jar`,
+its dependency jars, `docs/README.md`, `demos/config-reference.txt`, the curated
+demos flattened into `demos/`, and `demos/config.txt` copied from the tracked
+`demos/config-placeholder.txt` (never the developer's local config, which may
+hold real keys). `sbt packageZip` also prints the `libraries.conf` entry to use.
 
-- [ ] Version updated in `build.sbt`
-- [ ] `sbt clean packageZip` completed successfully
-- [ ] `sbt test` passed
-- [ ] ZIP file tested in NetLogo
-- [ ] Optional live-provider checks run (`demos/tests/tests.nlogox`)
-- [ ] Documentation updated if needed
-- [ ] Git tag created
-- [ ] GitHub release published
-- [ ] ZIP file attached to release
+Check the manifest says `NetLogo-Extension-API-Version: 7.0`:
 
-## Build Outputs
-
-### For Development
 ```bash
-sbt clean assembly
+unzip -p llm-<version>.zip llm.jar > /tmp/llm.jar && unzip -p /tmp/llm.jar META-INF/MANIFEST.MF
 ```
-- Output: `target/scala-3.7.0/llm.jar` (172MB)
-- Use: Local testing, quick install
-
-### For Distribution
-```bash
-sbt clean packageZip
-```
-- Output: `llm-x.x.x.zip` (11MB)
-- Use: Official releases, NetLogo Library submission
-
-## Version Numbering
 
-Follow semantic versioning: `MAJOR.MINOR.PATCH`
+## 3. Test the release
 
-- **MAJOR**: Breaking changes to API
-- **MINOR**: New features, backward compatible
-- **PATCH**: Bug fixes, backward compatible
+1. `sbt test` (deterministic, no network) must be green; CI runs the same plus
+   the zip check.
+2. Live harness: open `demos/e2e-tests/e2e-tests.nlogox` with a local
+   `config-<provider>.txt` (see the `.example` files) and run it against at least
+   one cloud provider, Ollama, and TypeSafe (Jev).
+3. Install the zip into a NetLogo 7.0.4 app
+   (`<NetLogo 7.0.4>/extensions/llm/`), open a bundled demo, and run it.
 
-Examples:
-- `0.1.0` - Initial release
-- `0.2.0` - Added new primitives
-- `0.2.1` - Fixed bug in config loading
-- `1.0.0` - Stable API, production ready
+## 4. Tag and publish on GitHub
 
-## Publishing to NetLogo Extension Library
+```bash
+git tag v<version>
+git push upstream main v<version>
+gh release create v<version> llm-<version>.zip -R NetLogo/Netlogo-LLM-Extension \
+  --title "LLM Extension v<version>" --notes-file <notes.md>
+```
 
-After creating a GitHub release:
+## 5. Publish to the Extension Manager
 
-1. The package metadata is generated by `sbt packageZip`:
-   ```json
-   {
-     name:             "LLM-Extension"
-     codeName:         "llm"
-     version:          "0.x.x"
-     downloadURL:      "https://github.com/.../llm-0.x.x.zip"
-   }
-   ```
+1. Fork https://github.com/NetLogo/NetLogo-Libraries and branch from **`7.0`**
+   (the branch NetLogo 7.0.x reads). Maintainers cherry-pick to `7.1`.
+2. Add `extensions/llm-<version>.zip`.
+3. In `libraries.conf`, update the `llm` entry's `version` (and descriptions if
+   they changed) using the block `sbt packageZip` printed.
+4. Open the PR against `7.0`. For reference, v1.0.0 was NetLogo-Libraries PR #87.
 
-2. Submit to NetLogo Extension Library:
-   - Fork: https://github.com/NetLogo/NetLogo-Libraries
-   - Add entry to `libraries.conf`
-   - Create pull request
+## Checklist
 
-## Cleanup After Release
+- [ ] `version` set, `isSnapshot := false`, tree committed
+- [ ] `sbt clean test packageZip` green, `scripts/check-zip.sh` passes
+- [ ] Manifest API version is 7.0
+- [ ] Live e2e harness run (cloud provider, Ollama, Jev)
+- [ ] Zip installed and a demo run in NetLogo 7.0.4
+- [ ] Docs updated (`docs/API-REFERENCE.md`, `docs/CONFIGURATION.md`, `docs/PROVIDER-GUIDE.md`)
+- [ ] Tag pushed, GitHub release published with the zip
+- [ ] NetLogo-Libraries PR opened against `7.0`
+- [ ] `isSnapshot := true` restored for development
 
-Remove old build artifacts:
+## Development builds
 
 ```bash
-# Remove old JARs from root (keep only latest ZIP)
-rm -f *.jar
-
-# Remove old version directories
-rm -rf llm-0.0.*/
-
-# Keep only:
-# - llm-0.x.x.zip (latest version)
-# - target/ (regenerated on build)
+sbt clean assembly     # fat jar at target/scala-3.7.0/llm.jar, for local installs
+./build.sh             # same, plus install when NETLOGO_DIR is set
 ```