Bootstrap architecture docs and add reveal.js support

.github/copilot-instructions.md

@@ -0,0 +1,21 @@
+# Repository Instructions For GitHub Copilot
+
+Follow the project `AGENTS.md`.
+
+This project uses architecture-knowledge-toolkit for architecture documentation,
+ADRs, quality scenarios, risks, traceability metadata, templates, validators,
+generated include fragments, and SDLC task workflows that are not described more
+specifically in this repository.
+
+Use the toolkit repository as source of truth when local toolkit files are missing:
+
+https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
+
+For architecture-related or SDLC workflow changes:
+
+- prefer small, reviewable changes
+- preserve stable IDs
+- keep AI-generated or AI-modified architecture content in `draft` or `proposed` state unless reviewed
+- do not manually maintain generated fragments
+- consult the relevant toolkit skill before issue slicing, issue implementation, commit message, pull request review, post-merge synchronization, ADR, quality scenario, risk, or traceability-review work when local instructions are missing
+- do not introduce Copilot-specific rules into engine-independent toolkit files

.github/workflows/architecture-docs.yml

@@ -0,0 +1,63 @@
+name: Architecture Documentation
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+concurrency:
+  group: architecture-docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Build Architecture Documentation
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build architecture HTML
+        run: ./build.sh build
+
+  build-pages:
+    name: Build Architecture Pages
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build architecture HTML
+        run: ./build.sh build
+
+      - name: Upload architecture HTML
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/architecture
+
+  deploy-pages:
+    name: Deploy Architecture Pages
+    runs-on: ubuntu-latest
+    needs: build-pages
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -39,4 +39,7 @@ bin/
 .vscode/
 
 ### Mac OS ###
-.DS_Store
+.DS_Store
+
+### Generated architecture documentation ###
+**/generated/

AGENTS.md

@@ -0,0 +1,40 @@
+# Project Agent Instructions
+
+This project uses architecture-knowledge-toolkit for architecture work and
+software-development-lifecycle tasks that are not described more specifically in
+this repository.
+
+Apply instructions in this order:
+
+1. User instruction
+2. This project `AGENTS.md`
+3. Relevant toolkit skill or contract
+4. Toolkit `general-semantic-contracts.md`
+
+Use the toolkit for product clarification, arc42 documentation, ADRs, quality
+scenarios, risks and technical debt, runtime scenarios, traceability metadata,
+templates, validators, generated include fragments, issue slicing, issue
+implementation workflow, commit messages, pull request reviews, post-merge
+synchronization, and traceability reviews.
+
+Toolkit source of truth:
+
+https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
+
+Preferred local lookup order:
+
+1. `$ARCHITECTURE_KNOWLEDGE_TOOLKIT`
+2. `../architecture-knowledge-toolkit`
+3. project-local recorded toolkit reference, submodule, vendored copy, or pinned path
+4. the public repository above, preferably at a stable release tag or commit SHA
+
+Before architecture or SDLC workflow work:
+
+- inspect existing `src/docs/`, `metamodel/`, `templates/`, `scripts/`, and `skills/`
+- verify referenced toolkit skill paths before copying or linking them
+- preserve stable artifact IDs
+- use AsciiDoc as the default architecture documentation format
+- mark AI-created or AI-modified architecture content as `draft` or `proposed`
+- set `reviewed: false` unless human acceptance is already recorded
+- do not manually maintain generated fragments when a generator exists
+- copy missing toolkit templates, schemas, validators, and generator scripts from the toolkit instead of inventing alternatives

Dockerfile

@@ -15,10 +15,11 @@ RUN apt-get update && apt-get install -y \
     graphviz \
     unzip \
     curl \
+    && gem install --no-document asciidoctor-diagram asciidoctor-diagram-plantuml asciidoctor-revealjs \
     && rm -rf /var/lib/apt/lists/*
 
 # Arbeitsverzeichnis
 WORKDIR /app
 
 # Flexible entrypoint – beliebige Commands
-ENTRYPOINT []
+ENTRYPOINT []

README.md

@@ -24,6 +24,9 @@ Unlike ad-hoc setups, this image is designed to be **the single source of truth
 - Reproducible documentation builds across environments
 - Zero-setup onboarding for contributors
 - Consistent toolchain in local and CI workflows
+- Diagram rendering without project-specific host setup
+- Reveal.js presentation builds from AsciiDoc sources
+- Direct Asciidoctor CLI builds and Gradle/AsciidoctorJ builds in the same runtime
 
 ---
 
@@ -32,9 +35,12 @@ Unlike ad-hoc setups, this image is designed to be **the single source of truth
 This image provides a ready-to-use toolchain for **Docs-as-Code pipelines**:
 
 - Asciidoctor
+- Asciidoctor Diagram with PlantUML support
+- Asciidoctor reveal.js converter
 - Pandoc
 - Graphviz
 - Common CLI utilities
+- Java runtime support for Gradle/AsciidoctorJ-based documentation builds
 
 👉 Everything preconfigured to work together.
 
@@ -64,19 +70,73 @@ docker run --rm \
   -v $(pwd):/workspace \
   -w /workspace \
   ghcr.io/docs-as-code-toolkit/docs-toolbox:latest \
-  ./asciidoctor -v
+  asciidoctor -v
 ```
 
 > 💡 On Windows, replace `$(pwd)` with the appropriate path syntax.
 
+### Render AsciiDoc with diagrams
+
+```bash
+docker run --rm \
+  -v $(pwd):/workspace \
+  -w /workspace \
+  ghcr.io/docs-as-code-toolkit/docs-toolbox:latest \
+  asciidoctor \
+    -r asciidoctor-diagram \
+    -r asciidoctor-diagram/plantuml \
+    --failure-level=ERROR \
+    docs/index.adoc
+```
+
+### Render reveal.js presentations
+
+The image includes the Ruby `asciidoctor-revealjs` CLI. Point `revealjsdir` at a
+CDN or at project-provided Reveal.js assets:
+
+```bash
+docker run --rm \
+  -v $(pwd):/workspace \
+  -w /workspace \
+  ghcr.io/docs-as-code-toolkit/docs-toolbox:latest \
+  asciidoctor-revealjs \
+    -a revealjsdir=https://cdn.jsdelivr.net/npm/reveal.js@4.5.0 \
+    docs/slides.adoc
+```
+
+For offline or customized slide decks, vendor Reveal.js in the project and set
+`revealjsdir` to that local path.
+
+### Use with Gradle / AsciidoctorJ
+
+The image includes a Java runtime, so projects can run Gradle builds that use
+AsciidoctorJ and its diagram module:
+
+```bash
+docker run --rm \
+  -v $(pwd):/workspace \
+  -w /workspace \
+  ghcr.io/docs-as-code-toolkit/docs-toolbox:latest \
+  ./gradlew --no-daemon build
+```
+
 ### Use in scripts (example)
 
 ```bash
 ./build.sh <some action>
 ```
 (assuming your project wraps the container execution)
 
-### GitHub Actions (example
+This repository's own `build.sh` validates the toolkit metadata, generates
+derived architecture fragments, and renders the assembled architecture HTML.
+It first looks for a published `df-<Dockerfile-hash>` image and builds a local
+image from the current Dockerfile if that exact image does not exist.
+
+```bash
+./build.sh build
+```
+
+### GitHub Actions (example)
 
 ```yaml
 jobs:
@@ -92,6 +152,8 @@ jobs:
 
 ## 🧩 Typical Use Cases
 - 📄 Generate HTML / PDF / Markdown from AsciiDoc
+- 🖼️ Render PlantUML diagrams from AsciiDoc
+- 🎞️ Build Reveal.js presentations from AsciiDoc
 - 🧱 Docs-as-Code pipelines
 - 📦 CI/CD documentation builds
 - 👥 Onboarding without local setup
@@ -104,12 +166,45 @@ This image follows a few simple principles:
 - 🧼 No hidden magic
 
 ## 🔄 Versioning
-- latest → most recent stable toolbox
-- version tags → reproducible builds
-- `df-<hash>` → image of latest commit (does not need to be the same as 'latest')
+- `latest` → most recent tagged stable toolbox image
+- version tags → reproducible release builds
+- `df-<hash>` → image built from a Dockerfile with that SHA-256 hash prefix
 
 👉 Pin versions in CI for full determinism.
 
+The `df-<hash>` tag is useful for local wrappers: compute the hash of the local
+Dockerfile, try to pull that image, and build locally when the image is not yet
+published.
+
+## 🏗️ Architecture Documentation
+
+This repository contains toolkit-compatible architecture documentation under
+`src/docs/`.
+
+The architecture documentation is dogfooded: it is generated with this
+project's own toolbox image. `build.sh` computes the local Dockerfile hash,
+uses the matching published `df-<hash>` image when available, and otherwise
+builds the current Dockerfile locally before rendering the documentation.
+
+Build it locally with:
+
+```bash
+./build.sh build
+```
+
+The output is written to:
+
+```text
+build/architecture/index.html
+```
+
+Pull requests validate the architecture metadata. Builds on `main` generate the
+architecture HTML and publish it through GitHub Pages.
+
+Expected GitHub Pages URL after the first successful deployment:
+
+👉 https://docs-as-code-toolkit.github.io/docs-toolbox/
+
 ## 🛠️ Customization
 If you need additional tools:
 - Extend this image via your own Dockerfile