feat: Add OpenWiki documentation and automation workflow

Author: mkjsix

.github/workflows/openwiki-update.yml

@@ -0,0 +1,52 @@
+name: OpenWiki Update
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 8 * * *"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "22"
+
+      - name: Install OpenWiki
+        # mermaid + jsdom are optional; they add high-fidelity validation of Mermaid diagrams. Remove if your wiki has none.
+        run: npm install --global openwiki@0.2.3 mermaid@11.16.0 jsdom@29.1.1
+
+      - name: Run OpenWiki
+        run: openwiki code --update --print
+        env:
+          OPENWIKI_PROVIDER: openrouter
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          OPENWIKI_MODEL_ID: z-ai/glm-5.2
+          LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
+          LANGCHAIN_PROJECT: openwiki
+          LANGCHAIN_TRACING_V2: "true"
+
+      - name: Create OpenWiki update pull request
+        uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7
+        with:
+          add-paths: |
+            openwiki
+            AGENTS.md
+            CLAUDE.md
+            .github/workflows/openwiki-update.yml
+          branch: openwiki/update
+          commit-message: "docs: update OpenWiki"
+          title: "docs: update OpenWiki"
+          body: |
+            Automated OpenWiki documentation update.
+
+            This PR was generated by the scheduled OpenWiki workflow.

AGENTS.md

@@ -0,0 +1,9 @@
+<!-- OPENWIKI:START -->
+
+## OpenWiki
+
+This repository uses OpenWiki for recurring code documentation. Start with `openwiki/quickstart.md`, then follow its links to architecture, workflows, domain concepts, operations, integrations, testing guidance, and source maps.
+
+The scheduled OpenWiki GitHub Actions workflow refreshes the repository wiki. Do not hand-edit generated OpenWiki pages unless explicitly asked; prefer updating source code/docs and letting OpenWiki regenerate.
+
+<!-- OPENWIKI:END -->

CLAUDE.md

@@ -0,0 +1,9 @@
+<!-- OPENWIKI:START -->
+
+## OpenWiki
+
+This repository uses OpenWiki for recurring code documentation. Start with `openwiki/quickstart.md`, then follow its links to architecture, workflows, domain concepts, operations, integrations, testing guidance, and source maps.
+
+The scheduled OpenWiki GitHub Actions workflow refreshes the repository wiki. Do not hand-edit generated OpenWiki pages unless explicitly asked; prefer updating source code/docs and letting OpenWiki regenerate.
+
+<!-- OPENWIKI:END -->

README.md

@@ -2,9 +2,28 @@
 
 [![Docker image](https://github.com/SoftInstigate/graalvm-maven-docker/actions/workflows/deploy-image.yml/badge.svg)](https://github.com/SoftInstigate/graalvm-maven-docker/actions/workflows/deploy-image.yml)
 
-Minimal Docker image with [GraalVM](https://graalvm.org) + [Maven](https://maven.apache.org) installed via [SDKMAN!](https://sdkman.io). Use it to build JVM apps and GraalVM native images without installing toolchains locally.
+A minimal Docker image that packages [GraalVM](https://graalvm.org) and [Apache Maven](https://maven.apache.org) for building JVM applications and compiling GraalVM native images. No local toolchain setup required.
 
-Images are automatically published on Docker Hub and GHCR when a git tag is pushed.
+## Purpose
+
+Building Java applications—especially GraalVM native images—requires a specific combination of JDK, build tools, and native libraries. Developers waste time installing and maintaining these toolchains across machines, CI runners, and team environments. This image solves that problem by providing a ready-to-use, versioned build environment.
+
+### Why use this image?
+
+- **Zero local setup** — Pull the image and start building. No JDK, Maven, or GraalVM installation needed.
+- **Reproducible builds** — Pin a tag (e.g. `25-graalce`) and every developer and CI job gets the exact same toolchain.
+- **Native image support** — Includes all dependencies (`build-essential`, `libz-dev`, `zlib1g-dev`) required by GraalVM's `native-image` compiler out of the box.
+- **Multi-arch** — Works on both `linux/amd64` and `linux/arm64` (Apple Silicon, Graviton, etc.).
+- **CI/CD ready** — Ideal for GitHub Actions, GitLab CI, Jenkins, or any container-based pipeline.
+
+### When to use it
+
+| Use case | Example |
+|---|---|
+| Build a Maven project without installing Java | `docker run --rm -v "$PWD":/opt/app softinstigate/graalvm-maven clean package` |
+| Compile a GraalVM native image | `docker run --rm -v "$PWD":/opt/app softinstigate/graalvm-maven -Pnative native:compile` |
+| Run builds in CI with consistent tooling | Use as a container image in your CI workflow |
+| Avoid version conflicts across projects | Different tags for different GraalVM/Maven versions |
 
 ## Current versions
 
@@ -37,7 +56,13 @@ docker pull softinstigate/graalvm-maven:25-graalce
 docker pull ghcr.io/softinstigate/graalvm-maven:25-graalce
 ```
 
-## Quick start
+## How it works
+
+The image is based on `debian:stable-slim` and uses [SDKMAN!](https://sdkman.io) to install GraalVM and Maven. This approach makes version upgrades simple—just change the `ARG` values in the `Dockerfile` and rebuild.
+
+An entrypoint script (`bin/entrypoint.sh`) activates SDKMAN! and delegates to `mvn`, so the image behaves like a standalone Maven command.
+
+## Building a project
 
 The default `ENTRYPOINT` is `mvn`. The working directory is `/opt/app`.
 
@@ -55,7 +80,7 @@ docker run -it --rm \
 
 > Mounting `~/.m2` speeds up builds by reusing your local Maven cache.
 
-## Native image builds
+## Compiling a native image
 
 Use the [GraalVM Native Build Tools (Maven plugin)](https://graalvm.github.io/native-build-tools/latest/maven-plugin.html/) in your project. Then run:
 
@@ -71,7 +96,9 @@ docker run -it --rm \
     -Pnative -DskipTests native:compile
 ```
 
-## Local development of this image
+## Contributing: local development
+
+To build and test the image locally:
 
 ```bash
 # Build the image locally (no cache)
@@ -84,7 +111,7 @@ docker run -it --rm softinstigate/graalvm-maven --version
 ./bin/push.sh
 ```
 
-## CI/CD and release process
+## Release process
 
 - GitHub Actions workflow: `.github/workflows/deploy-image.yml`
 - Trigger: push of any git tag

openwiki/.last-update.json

@@ -0,0 +1,6 @@
+{
+  "updatedAt": "2026-08-07T10:53:53.654Z",
+  "command": "update",
+  "gitHead": "8c322f3a42477edce275e9d14b4ad13f7aa495fd",
+  "model": "xiaomi/mimo-v2.5-pro"
+}

openwiki/INSTRUCTIONS.md

@@ -0,0 +1 @@
+A code wiki for this local repository. Prioritize a concise quickstart, architecture overview, source map, key workflows, domain concepts, operations/runbook notes, testing guidance, and integration points. Inspect git history to understand reasoning behind code changes and the progression of the repository. Keep pages grounded in the repository structure and recent code changes. Prefer practical navigation for engineers over generic summaries.

openwiki/ci-cd.md

@@ -0,0 +1,86 @@
+---
+type: Reference
+title: CI/CD and Release Process
+description: GitHub Actions workflow for building and publishing multi-arch Docker images to Docker Hub and GHCR, including release steps, secrets, and OpenWiki automation.
+tags: [ci-cd, github-actions, docker, release, openwiki]
+---
+
+# CI/CD and Release Process
+
+## Image deployment workflow
+
+[`.github/workflows/deploy-image.yml`](/.github/workflows/deploy-image.yml) builds and publishes multi-arch Docker images automatically when any git tag is pushed.
+
+### Trigger
+
+```yaml
+on:
+  push:
+    tags:
+      - "*"
+```
+
+Pushing **any** tag triggers the build. There is no branch filter — the tag itself determines the image tag name.
+
+### Build pipeline
+
+```mermaid
+sequenceDiagram
+    participant Dev as Developer
+    participant GH as GitHub Actions
+    participant Buildx as Docker Buildx (QEMU)
+    participant Hub as Docker Hub
+    participant GHCR as ghcr.io
+
+    Dev->>GH: push tag (e.g. 25-graalce)
+    GH->>GH: checkout, setup QEMU + Buildx
+    GH->>Hub: login (DOCKER_USER / DOCKER_TOKEN)
+    GH->>GHCR: login (GITHUB_TOKEN)
+    GH->>Buildx: build linux/amd64 + linux/arm64
+    Buildx->>Hub: push :latest + :<tag>
+    Buildx->>GHCR: push :latest + :<tag>
+```
+
+### Output
+
+Each build pushes to **both** registries with two tags:
+
+| Tag pattern | Example |
+|-------------|---------|
+| `latest` | `softinstigate/graalvm-maven:latest` |
+| `<git-tag>` | `softinstigate/graalvm-maven:25-graalce` |
+
+### Required secrets
+
+| Secret | Used by | Purpose |
+|--------|---------|---------|
+| `DOCKER_USER` | Docker Hub login | Hub username |
+| `DOCKER_TOKEN` | Docker Hub login | Hub access token |
+| `GITHUB_TOKEN` | GHCR login | Automatic — no manual setup needed |
+
+## Release process (maintainer steps)
+
+1. Update `ARG JAVA_VERSION` and `ARG MAVEN_VERSION` in [`Dockerfile`](/Dockerfile).
+2. Update the version table in [`README.md`](/README.md) to match.
+3. Commit and push to `main`.
+4. Create and push a git tag matching the GraalVM version (e.g. `25-graalce`):
+   ```bash
+   git tag 25-graalce
+   git push origin 25-graalce
+   ```
+5. GitHub Actions builds and publishes the image automatically.
+
+## OpenWiki automation
+
+[`.github/workflows/openwiki-update.yml`](/.github/workflows/openwiki-update.yml) runs a scheduled OpenWiki documentation refresh:
+
+- **Schedule:** daily at 08:00 UTC (`cron: "0 8 * * *"`)
+- **Trigger:** also available via `workflow_dispatch`
+- **Process:** checks out the repo, installs OpenWiki globally, runs `openwiki code --update --print`, then opens a PR on the `openwiki/update` branch with any documentation changes.
+- **PR scope:** changes under `openwiki/`, `AGENTS.md`, `CLAUDE.md`, and the workflow file itself.
+
+The workflow uses OpenRouter as the LLM provider (configured via `OPENROUTER_API_KEY` secret).
+
+## Relationship to Dockerfile
+
+The CI workflow consumes the Dockerfile as-is — it does not override `ARG` values at build time. This means the version `ARG`s in the Dockerfile are the sole source of truth for what gets installed in the published image.

openwiki/dockerfile.md

@@ -0,0 +1,79 @@
+---
+type: Reference
+title: Dockerfile and Image Structure
+description: Layer-by-layer breakdown of the Dockerfile, SDKMAN configuration, ARG-controlled versions, entrypoint behavior, and build dependencies required for native-image compilation.
+tags: [dockerfile, sdkman, graalvm, build, entrypoint]
+---
+
+# Dockerfile and Image Structure
+
+The entire image is defined in a single [`Dockerfile`](/Dockerfile) at the repository root. It builds a Debian-based container with SDKMAN-managed Java and Maven toolchains.
+
+## Base image and layers
+
+```
+FROM debian:stable-slim
+```
+
+The image uses `debian:stable-slim` for minimal footprint. Layers are organized as two `RUN` instructions:
+
+1. **System dependencies + SDKMAN install** — installs OS packages, sets locale, fetches SDKMAN, and writes its config.
+2. **Java + Maven install** — sources SDKMAN and runs `sdk install` for both tools, then cleans up archive/temp files.
+
+## Version control via ARGs
+
+```dockerfile
+ARG JAVA_VERSION="25-graalce"
+ARG MAVEN_VERSION="3.9.11"
+```
+
+These `ARG` directives are the single source of truth for installed tool versions. To upgrade GraalVM or Maven, change these values and update the README version table to match.
+
+The image label and git tag convention reflect the GraalVM version (e.g. `25-graalce`).
+
+## SDKMAN configuration
+
+SDKMAN is configured in three lines written to `$SDKMAN_DIR/etc/config`:
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| `sdkman_auto_answer` | `true` | Non-interactive installs (no prompts) |
+| `sdkman_auto_selfupdate` | `false` | Prevents SDKMAN version drift at build time |
+| `sdkman_insecure_ssl` | `true` | Compatibility with some corporate proxy environments |
+
+The SDKMAN directory is `/root/.sdkman` (set via `ENV SDKMAN_DIR`).
+
+## System build packages
+
+These packages are installed and **must not be removed** — they are required for GraalVM native-image compilation:
+
+- `build-essential` — C/C++ compiler toolchain
+- `libz-dev`, `zlib1g-dev` — compression libraries needed by native-image
+- `ca-certificates` — TLS trust store
+- `fontconfig`, `locales` — locale and font support for JVM
+
+## Entrypoint script
+
+[`bin/entrypoint.sh`](/bin/entrypoint.sh) is a three-line shell script:
+
+```bash
+#!/bin/bash
+source /root/.bashrc && mvn "$@"
+```
+
+It sources `.bashrc` to activate the SDKMAN environment (which adds `mvn` and `java` to `PATH`), then forwards all container arguments to Maven. The `Dockerfile` sets `SHELL ["/bin/bash", "-i", "-c"]` and `ENTRYPOINT ["/root/entrypoint.sh"]`.
+
+Without sourcing `.bashrc`, `mvn` would not be found when the container starts — this is the most common cause of "command not found" errors when users override the entrypoint with a shell.
+
+## Helper scripts
+
+| Script | Purpose |
+|--------|---------|
+| [`bin/build.sh`](/bin/build.sh) | Local no-cache Docker build, tags as `:latest` |
+| [`bin/push.sh`](/bin/push.sh) | Pushes `:latest` to Docker Hub (manual testing only) |
+
+CI handles production image builds and pushes — see [CI/CD and release process](/openwiki/ci-cd.md).
+
+## Relationship to CI/CD
+
+The Dockerfile's `ARG` values and the README version table are the two places that must stay in sync during a release. The [CI/CD workflow](/openwiki/ci-cd.md) reads the Dockerfile as-is and publishes the resulting image under both `latest` and the git tag name.

openwiki/index.md

@@ -0,0 +1,9 @@
+---
+okf_version: "0.1"
+---
+
+# Files
+
+- [CI/CD and Release Process](ci-cd.md) - GitHub Actions workflow for building and publishing multi-arch Docker images to Docker Hub and GHCR, including release steps, secrets, and OpenWiki automation.
+- [Dockerfile and Image Structure](dockerfile.md) - Layer-by-layer breakdown of the Dockerfile, SDKMAN configuration, ARG-controlled versions, entrypoint behavior, and build dependencies required for native-image compilation.
+- [GraalVM Maven Docker — Quickstart](quickstart.md) - Minimal Docker image providing GraalVM and Maven via SDKMAN for building JVM apps and native images without local toolchains.