From 7fa9168757b15bfb00fd02624abc472b22e0ba03 Mon Sep 17 00:00:00 2001 From: krahd Date: Sun, 10 May 2026 00:02:30 -0300 Subject: [PATCH 1/3] Publish BatLLM project site --- STATUS.md | 11 +- docs/.nojekyll | 1 + docs/index.html | 745 ++++++++++++++++++++++++++++++++++++++++-------- 3 files changed, 638 insertions(+), 119 deletions(-) create mode 100644 docs/.nojekyll diff --git a/STATUS.md b/STATUS.md index a58eff5..ee0d2d0 100644 --- a/STATUS.md +++ b/STATUS.md @@ -1,6 +1,6 @@ # BatLLM Status -Last updated: 2026-05-09 23:45 +Last updated: 2026-05-10 00:01 ## Project Purpose @@ -89,6 +89,7 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins - Mock-Ollama smoke validation now accepts a responding `/api/version` endpoint when process-level inspection cannot identify the mock server as an Ollama process. - Generated Doxygen output under `docs/code/` was regenerated after source and version changes. Existing Doxygen warnings are mostly undocumented Kivy/test helper classes and remain non-blocking documentation debt. - Architecture and runtime-flow SVG diagrams were redrawn with larger canvases, wrapped text, boundary-aligned connectors, plain arrow labels, and clearer label placement. +- `docs/index.html` is now the public GitHub Pages showcase site for `https://krahd.github.io/BatLLM/`; the grant-support notes are visible in a prominent front-page section. - The git worktree was clean at the start of this audit; current changes are intentional audit/remediation updates. ## Current Implementation State @@ -179,6 +180,8 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins - `docs/ROADMAP.md` describes 1.0 local desktop hardening and 2.0 networked-play direction using current `0.3.x` line wording. - `docs/RELEASE_CRITERIA_1_0.md` defines CI, reliability, UX, bundle, and documentation gates for a future 1.0 candidate. - `docs/CHANGELOG.md` keeps active unreleased notes on the `0.x` hold and draft 1.0 notes. +- `docs/index.html` is the static project showcase served by GitHub Pages from `main` `/docs`. +- `docs/.nojekyll` keeps GitHub Pages from applying Jekyll processing to the static documentation tree. - `docs/FIRST_RUN_RELEASE_CHECKLIST.md` and `docs/UI_UNIFICATION_PLAN_1_0.md` remain release-preparation references. - `docs/images/architecture-modelito.svg` and `docs/images/request-flow-modelito.svg` are maintained standalone SVG diagrams used by `STATUS.md`; they were refreshed for legibility and connector accuracy. - `docs/code/` contains generated Doxygen HTML/LaTeX output and should be treated as generated documentation. @@ -200,6 +203,9 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins - Documentation local-link sanity check for `docs/*.md` -> passed (`documentation-local-links-ok`). - `python3 - <<'PY' ...` XML parse check for `docs/images/architecture-modelito.svg` and `docs/images/request-flow-modelito.svg` -> passed. - `rsvg-convert -o /tmp/architecture-modelito.png docs/images/architecture-modelito.svg` and `rsvg-convert -o /tmp/request-flow-modelito.png docs/images/request-flow-modelito.svg` -> passed; both diagrams rendered to temporary PNGs without errors. +- GitHub Pages configuration check with `gh api repos/krahd/BatLLM/pages` -> passed; Pages serves `https://krahd.github.io/BatLLM/` from branch `main` and path `/docs`. +- `python3 - <<'PY' ...` static HTML reference check for `docs/index.html` -> passed; verified local asset/doc references and visible grant-support copy. +- Local static server check with `python3 -m http.server 8040` from `docs/` plus `curl` -> passed; confirmed `index.html`, `images/logo-small.png`, `images/request-flow-modelito.svg`, and `images/architecture-modelito.svg` were served successfully. ### Recent Previously Recorded Validation @@ -220,6 +226,7 @@ The previous status report recorded these successful checks from the same releas - A headless launcher import attempt reached Kivy window initialisation and failed with `Unable to get a Window`; this is an environment limitation, not a substitute for manual GUI launch validation. - `python run_tests.py full` was not run during this audit because it can start and stop a real local Ollama service. - Homebrew install-level smoke (`validate_packaging_smoke.py --run-homebrew-install-smoke`) was not run because it installs/uninstalls through the local Homebrew installation. +- Quick Look HTML thumbnail rendering with `qlmanage` was not completed because the sandbox rejected Quick Look initialisation; local HTTP/static checks were used instead. ## Known Issues, Risks, And Limitations @@ -267,4 +274,4 @@ The previous status report recorded these successful checks from the same releas - Design the 2.0 server contract before adding web or repository-backed prompt/game sharing. - Add broader tests for malformed model responses, slow startup, missing models, session compatibility, analyzer edge cases, and packaged first-run behaviour. -Last updated: 2026-05-09 23:45 +Last updated: 2026-05-10 00:01 diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/docs/.nojekyll @@ -0,0 +1 @@ + diff --git a/docs/index.html b/docs/index.html index 401b8e9..23cd288 100644 --- a/docs/index.html +++ b/docs/index.html @@ -3,162 +3,673 @@ - BatLLM Documentation + + BatLLM -
-
-
+
+
+ +
-
- - Start Here - README -

Project overview and documentation entry point for both users and contributors.

- - - Usage - User Guide -

Game-manual style user documentation covering rules, match flow, screens, modes, commands, and Ollama usage.

- - - Development - Contributing -

Developer and contribution manual covering setup, architecture, configuration, testing, and troubleshooting.

- - - Questions - FAQ -

Shared high-signal answers about gameplay, Ollama usage, configuration, and contributor-facing practical questions.

- - - History - Changelog -

Running record of documentation and release-level changes.

- - - Project - Credits -

Project authorship, support, and institutional context.

- - - Download - Releases -

GitHub release bundles for macOS, Linux, Windows, and the compressed source package.

- +
+
+
+

BatLLM

+

+ A local AI-mediated battle game for studying prompts, model behaviour, strategy, + and the practical limits of generative systems through play. +

+
+ Download Releases + View Source +
+
- +
+
+

Grant-supported research software

+
+

+ BatLLM began as part of a project supported by the + 2024 Arts & Humanities Grant Program + of the + Research & Innovation Office + at the University of Colorado Boulder. +

+

+ BatLLM has also received a + CHA Small Grant, + from the + Center for the Humanities & the Arts + at the University of Colorado Boulder. +

+
+
+
+ +
+
+
+

A game for learning how AI mediation really behaves

+

+ BatLLM is free and libre software that turns prompting into a concrete, inspectable + activity. Players do not move directly; they must persuade local AI systems to act + on their behalf inside a simple human-vs-human battle arena. +

+
+
+
+ Research And Education +

Designed for AI literacy, prompt quality experiments, and critical discussion of model behaviour.

+
+
+ Local-First Play +

Runs as a desktop Python/Kivy application with local Ollama and modelito integration.

+
+
+ Replay Analysis +

Saved sessions can be reviewed in a standalone Game Analyzer with prompts, responses, and outcomes.

+
+
+ Open Tooling +

Maintained docs, tests, release tooling, and Homebrew packaging support the current 0.x line.

+
+
+
+
+ +
+
+
+

How a match becomes data

+

+ Every prompt, response, action, and result becomes part of the learning surface. + The game is playable, but it is also an instrument for examining AI-mediated decisions. +

+
    +
  1. 1
    PromptPlayers write instructions and strategy for their bots.
    2. +
  2. 2
    MediateBatLLM sends structured messages through the local model path.
    3. +
  3. 3
    ActModel responses are parsed into movement, rotation, shooting, and shielding.
    4. +
  4. 4
    ReviewSaved sessions preserve prompt history and board outcomes for analysis.
    5. +
+
+
+ Diagram of BatLLM local model request and replay flow +
+
+
+ +
+
+ Diagram of BatLLM architecture and local model integration +
+
+

Local model workflows stay visible

+

+ BatLLM routes gameplay, model selection, downloads, lifecycle checks, and smoke validation + through a shared service layer. The same path supports the game, the configurator tooling, + and repeatable analyzer sessions. +

+
+ Read The Overview + Open The User Guide +
+
+
+ +
+

Build, play, inspect, and contribute

+

+ Start with the project documentation, then install from source or releases. The repository + keeps the research framing, setup notes, tests, packaging details, and release criteria together. +

+
+ + README +

Project overview, setup, compatibility, Homebrew notes, and troubleshooting.

+ + + User Guide +

Rules, match flow, settings, Ollama screens, analyzer workflow, and saved sessions.

+ + + Contributing +

Developer setup, architecture, tests, release workflow, and documentation process.

+ + + Credits +

Project authorship, grant support, institutional context, and acknowledgements.

+ +
+
+ 
git clone https://github.com/krahd/BatLLM.git
+cd BatLLM
+python3 -m venv .venv_BatLLM
+source .venv_BatLLM/bin/activate
+pip install -r requirements.txt
+python run_batllm.py
+ 
python run_game_analyzer.py
+
+python -m pytest -q
+
+python create_release_bundles.py
+
+
+ + From 7f2bbaaa064d35f22d9d23c3b089c1a875ff3055 Mon Sep 17 00:00:00 2001 From: krahd Date: Sun, 10 May 2026 00:05:06 -0300 Subject: [PATCH 2/3] Record Pages publication status --- STATUS.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/STATUS.md b/STATUS.md index ee0d2d0..37166d2 100644 --- a/STATUS.md +++ b/STATUS.md @@ -1,6 +1,6 @@ # BatLLM Status -Last updated: 2026-05-10 00:01 +Last updated: 2026-05-10 00:04 ## Project Purpose @@ -180,7 +180,7 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins - `docs/ROADMAP.md` describes 1.0 local desktop hardening and 2.0 networked-play direction using current `0.3.x` line wording. - `docs/RELEASE_CRITERIA_1_0.md` defines CI, reliability, UX, bundle, and documentation gates for a future 1.0 candidate. - `docs/CHANGELOG.md` keeps active unreleased notes on the `0.x` hold and draft 1.0 notes. -- `docs/index.html` is the static project showcase served by GitHub Pages from `main` `/docs`. +- `docs/index.html` is the static project showcase served by GitHub Pages from branch `pages/batllm-site` and path `/docs`. - `docs/.nojekyll` keeps GitHub Pages from applying Jekyll processing to the static documentation tree. - `docs/FIRST_RUN_RELEASE_CHECKLIST.md` and `docs/UI_UNIFICATION_PLAN_1_0.md` remain release-preparation references. - `docs/images/architecture-modelito.svg` and `docs/images/request-flow-modelito.svg` are maintained standalone SVG diagrams used by `STATUS.md`; they were refreshed for legibility and connector accuracy. @@ -203,9 +203,12 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins - Documentation local-link sanity check for `docs/*.md` -> passed (`documentation-local-links-ok`). - `python3 - <<'PY' ...` XML parse check for `docs/images/architecture-modelito.svg` and `docs/images/request-flow-modelito.svg` -> passed. - `rsvg-convert -o /tmp/architecture-modelito.png docs/images/architecture-modelito.svg` and `rsvg-convert -o /tmp/request-flow-modelito.png docs/images/request-flow-modelito.svg` -> passed; both diagrams rendered to temporary PNGs without errors. -- GitHub Pages configuration check with `gh api repos/krahd/BatLLM/pages` -> passed; Pages serves `https://krahd.github.io/BatLLM/` from branch `main` and path `/docs`. +- GitHub Pages configuration check with `gh api repos/krahd/BatLLM/pages` -> passed; Pages serves `https://krahd.github.io/BatLLM/` from branch `pages/batllm-site` and path `/docs`. - `python3 - <<'PY' ...` static HTML reference check for `docs/index.html` -> passed; verified local asset/doc references and visible grant-support copy. - Local static server check with `python3 -m http.server 8040` from `docs/` plus `curl` -> passed; confirmed `index.html`, `images/logo-small.png`, `images/request-flow-modelito.svg`, and `images/architecture-modelito.svg` were served successfully. +- Pages build request with `gh api repos/krahd/BatLLM/pages/builds --method POST` -> passed; build `991944945` completed successfully for commit `7fa9168`. +- Published-site verification with `curl -sL https://krahd.github.io/BatLLM/` -> passed; confirmed the public HTML includes `Grant-supported research software`, `2024 Arts & Humanities Grant Program`, and `CHA Small Grant`. +- Published asset checks with `curl -I` for `/images/logo-small.png`, `/images/request-flow-modelito.svg`, and `/images/architecture-modelito.svg` -> passed with HTTP 200 responses. ### Recent Previously Recorded Validation @@ -274,4 +277,4 @@ The previous status report recorded these successful checks from the same releas - Design the 2.0 server contract before adding web or repository-backed prompt/game sharing. - Add broader tests for malformed model responses, slow startup, missing models, session compatibility, analyzer edge cases, and packaged first-run behaviour. -Last updated: 2026-05-10 00:01 +Last updated: 2026-05-10 00:04 From ef7c70d631937030a0a1d4b615e3f639b8cdb122 Mon Sep 17 00:00:00 2001 From: krahd Date: Sun, 10 May 2026 00:12:57 -0300 Subject: [PATCH 3/3] chore: update website - remove grant section, replace SVG diagrams with gameplay demo --- docs/index.html | 26 +++----------------------- 1 file changed, 3 insertions(+), 23 deletions(-) diff --git a/docs/index.html b/docs/index.html index 23cd288..ab081c8 100644 --- a/docs/index.html +++ b/docs/index.html @@ -533,27 +533,7 @@

BatLLM

-
-
-

Grant-supported research software

-
-

- BatLLM began as part of a project supported by the - 2024 Arts & Humanities Grant Program - of the - Research & Innovation Office - at the University of Colorado Boulder. -

-

- BatLLM has also received a - CHA Small Grant, - from the - Center for the Humanities & the Arts - at the University of Colorado Boulder. -

-
-
-
+
@@ -602,14 +582,14 @@

How a match becomes data

- Diagram of BatLLM local model request and replay flow + BatLLM gameplay demo
- Diagram of BatLLM architecture and local model integration + BatLLM gameplay demo

Local model workflows stay visible