Documentation: Publish a Docusaurus site, update the LICENCE and add the missing governance files

.coderabbit.yaml

@@ -41,7 +41,7 @@ reviews:
     - ".whitesource"
     - ".github/**"
     - ".settings/**"
-    - "docs/**"
+    - "documentation/**"
     - "src/**"
     - "pom.xml"
     - "README.md"
@@ -105,7 +105,7 @@ reviews:
         Review GitHub Actions for least-privilege permissions, safe event choice,
         pinned third-party actions, safe pull_request_target usage, no secret exposure
         to untrusted code, and branch-protection compatibility.
-    - path: docs/**/*.md
+    - path: documentation/docs/**/*.md
       instructions: >-
         Use current British English. Check that security guarantees, known limitations,
         and required external fixtures are explicit and do not overstate enforcement.

.editorconfig

@@ -0,0 +1,79 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+#
+# The `end_of_line` values below deliberately mirror .gitattributes. Git normalises every
+# text file to LF in the object database but checks most of them out as CRLF
+# (`* text=auto eol=crlf`), with LF reserved for the files that break otherwise: shell
+# scripts, YAML and pom.xml. An editor configured to write LF everywhere would fight that
+# checkout policy and produce a renormalisation diff on every save, so keep the two files in
+# step whenever either changes.
+
+root = true
+
+[*]
+end_of_line = crlf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = tab
+indent_size = 4
+
+# Markdown treats two trailing spaces as a hard line break, so they must survive.
+[*.md]
+trim_trailing_whitespace = false
+indent_style = space
+indent_size = 2
+
+[*.mdx]
+trim_trailing_whitespace = false
+indent_style = space
+indent_size = 2
+
+# Ares formats Java with tabs; see the Spotless configuration in pom.xml.
+[*.java]
+indent_style = tab
+
+[*.xml]
+indent_style = tab
+
+# .gitattributes pins pom.xml to LF.
+[pom.xml]
+end_of_line = lf
+indent_style = tab
+
+# .gitattributes pins YAML to LF.
+[{*.yml,*.yaml}]
+end_of_line = lf
+indent_style = space
+indent_size = 2
+
+# .gitattributes pins shell scripts to LF; CRLF makes them fail with "bad interpreter".
+[{*.sh,*.bash,*.fish,gradlew}]
+end_of_line = lf
+indent_style = space
+indent_size = 2
+
+# .gitattributes pins these to CRLF explicitly; they are Windows scripts.
+[{*.bat,*.cmd,*.ps1}]
+end_of_line = crlf
+
+[{*.ats,*.cts,*.mts,*.ts,*.tsx}]
+indent_style = space
+indent_size = 4
+ij_typescript_use_double_quotes = false
+ij_typescript_spaces_within_imports = true
+
+[{*.cjs,*.mjs,*.js,*.jsx}]
+indent_style = space
+indent_size = 4
+ij_javascript_use_double_quotes = false
+ij_javascript_spaces_within_imports = true
+
+[*.json]
+indent_style = space
+indent_size = 2
+
+[*.css]
+indent_style = space
+indent_size = 4

.github/PULL_REQUEST_TEMPLATE.md

@@ -307,7 +307,7 @@ No breaking changes or migration.
 - [ ] I followed the [guidelines for inclusive, diversity-sensitive and appreciative language](https://docs.artemis.tum.de/developer/guidelines/language).
 - [ ] I have self-reviewed the diff of this pull request.
 - [ ] Tests were added or updated for the behaviour changed here.
-- [ ] Documentation (`docs/`, `README.adoc`, Javadoc) was updated where the change is user-facing.
+- [ ] Documentation (`documentation/`, `README.md`, Javadoc) was updated where the change is user-facing.
 - [ ] CI is green, or every remaining failure is explained above.
 - [ ] No secrets, tokens or absolute local paths are contained in the diff.
 

.github/actionlint.yaml

@@ -0,0 +1,14 @@
+# Configuration for actionlint, run by .github/workflows/actionlint.yml.
+# Reference: https://github.com/rhysd/actionlint/blob/main/docs/config.md
+#
+# Ares 2 runs entirely on GitHub-hosted runners, so no self-hosted labels are declared.
+# Add a label here if a job ever moves to a self-hosted runner, otherwise actionlint will
+# reject the unknown `runs-on` value.
+self-hosted-runner:
+  labels: []
+
+# Ares 2 uses no repository or organisation configuration variables in workflows yet.
+# Declaring the list empty is what makes `actionlint` reject every `vars.` expression it finds.
+# Omitting the key entirely would allow all of them, so the empty list is the strict setting and
+# the one we want. Add the name here when a configuration variable is genuinely introduced.
+config-variables: []

.github/labeler.yml

@@ -4,15 +4,17 @@ aop:
           - src/main/java/de/tum/cit/ase/ares/api/aop/**/*
           - src/test/java/de/tum/cit/ase/ares/api/aop/**/*
           - src/test/java/de/tum/cit/ase/ares/integration/aop/**/*
-          - docs/aop/**/*
+          - documentation/docs/contributor/subsystems/aop/**/*
+          - documentation/docs/contributor/technologies/aop-tests/**/*
 
 architecture:
   - changed-files:
       - any-glob-to-any-file:
           - src/main/java/de/tum/cit/ase/ares/api/architecture/**/*
           - src/test/java/de/tum/cit/ase/ares/api/architecture/**/*
           - src/test/java/de/tum/cit/ase/ares/integration/architecture/**/*
-          - docs/architecture/**/*
+          - documentation/docs/contributor/subsystems/architecture/**/*
+          - documentation/docs/contributor/technologies/architecture-tests/**/*
 
 ast:
   - changed-files:
@@ -27,14 +29,14 @@ policy:
           - src/main/java/de/tum/cit/ase/ares/api/policy/**/*
           - src/test/java/de/tum/cit/ase/ares/api/policy/**/*
           - src/test/resources/de/tum/cit/ase/ares/integration/testuser/securitypolicies/**/*
-          - docs/policy/**/*
+          - documentation/docs/contributor/subsystems/policy/**/*
+          - documentation/docs/contributor/policy/**/*
 
 docs:
   - changed-files:
       - any-glob-to-any-file:
-          - docs/**/*
+          - documentation/**/*
           - "*.md"
-          - "*.adoc"
           - SECURITY.md
 
 tests:
@@ -47,7 +49,7 @@ securitytest:
       - any-glob-to-any-file:
           - src/main/java/de/tum/cit/ase/ares/api/securitytest/**/*
           - src/test/java/de/tum/cit/ase/ares/api/securitytest/**/*
-          - docs/securitytest/**/*
+          - documentation/docs/contributor/subsystems/securitytest/**/*
 
 other:
   - changed-files:

.github/workflows/deploy-documentation.yml

@@ -0,0 +1,50 @@
+# Publishes documentation/ to GitHub Pages at https://ls1intum.github.io/Ares2/.
+#
+# One-time repository setup, which a workflow cannot do for you:
+#   Settings -> Pages -> Build and deployment -> Source = "GitHub Actions"
+# Without it the deploy job fails with a "Pages is not enabled" error.
+#
+# workflow_dispatch is kept so the site can be republished without a documentation change,
+# for example after a failed deploy or a change to the Pages settings.
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
+      - '.github/workflows/deploy-documentation.yml'
+  workflow_dispatch:
+
+permissions: {}
+
+# Serialised against every other Pages deploy. cancel-in-progress stays false so an in-flight
+# deploy is allowed to finish rather than leaving the site half-published.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  documentation:
+    uses: ./.github/workflows/documentation.yml
+    permissions:
+      contents: read
+    with:
+      upload_pages_artifact: true
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: documentation
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    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@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

.github/workflows/documentation-ci.yml

@@ -0,0 +1,34 @@
+# Pull request validation for the documentation site.
+#
+# Builds documentation/ without publishing anything, so a broken link, a stale PlantUML render
+# or a type error is caught on the pull request rather than on the deploy.
+name: Documentation CI
+
+on:
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
+      - '.github/workflows/documentation-ci.yml'
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
+      - '.github/workflows/documentation-ci.yml'
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: documentation-ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  documentation:
+    uses: ./.github/workflows/documentation.yml
+    permissions:
+      contents: read
+    with:
+      upload_pages_artifact: false

.github/workflows/documentation.yml

@@ -0,0 +1,112 @@
+# Reusable build of the Docusaurus site in documentation/.
+#
+# This workflow has no triggers of its own. Two callers use it:
+#   - documentation-ci.yml validates every pull request that touches the docs.
+#   - deploy-documentation.yml builds and then publishes to GitHub Pages.
+#
+# Keeping the build in one place means the artefact that gets deployed is produced by exactly
+# the same steps that validated it on the pull request.
+name: Build Documentation
+
+on:
+  workflow_call:
+    inputs:
+      upload_pages_artifact:
+        description: >-
+          Also upload the built site as a GitHub Pages artefact. Set true by the deploy path;
+          pull request validation leaves it false so no artefact is produced.
+        required: false
+        default: false
+        type: boolean
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build Docusaurus site
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '24'
+
+      # pnpm is activated through Corepack rather than pnpm/action-setup. This repository
+      # restricts Actions to GitHub-owned ones (plus one explicit pattern), so a third-party
+      # action makes the workflow fail to start at all. Corepack ships with Node and reads the
+      # exact version from the packageManager field in documentation/package.json, so CI and a
+      # local `corepack enable` resolve to the same pnpm, with one less supply-chain dependency.
+      - name: Set up pnpm through Corepack
+        working-directory: documentation
+        run: |
+          corepack enable
+          corepack install
+          pnpm --version
+
+      # Cached by hand because actions/setup-node's built-in pnpm cache resolves the store path
+      # before Corepack has run. actions/cache is GitHub-owned and therefore permitted.
+      - name: Resolve the pnpm store path
+        id: pnpm-store
+        working-directory: documentation
+        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
+
+      - name: Restore the pnpm store
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('documentation/pnpm-lock.yaml') }}
+          restore-keys: ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        working-directory: documentation
+        run: pnpm install --frozen-lockfile
+
+      - name: Code style
+        working-directory: documentation
+        run: pnpm run lint
+
+      - name: Type check
+        working-directory: documentation
+        run: pnpm run typecheck
+
+      # PlantUML sources are rendered to SVG and the SVGs are committed, the same way the
+      # .drawio sources sit next to committed .drawio.png renders. This fails the build when a
+      # .puml was edited without regenerating its diagram, so the site can never show a
+      # diagram that disagrees with its source.
+      - name: Verify committed PlantUML renders
+        working-directory: documentation
+        run: pnpm run diagrams:check
+
+      # onBrokenLinks and onBrokenAnchors are set to 'throw', so a dangling cross-reference
+      # fails here rather than shipping to the published site.
+      - name: Build Docusaurus site
+        working-directory: documentation
+        run: pnpm run build
+
+      # Drives the built site in a real browser. This is the only check that sees what a
+      # reader actually gets: the build verifies that every link resolves, but not that a page
+      # renders. It is what caught 53 admonitions that were silently rendering as plain text
+      # because they used the Docusaurus 2 title syntax.
+      - name: Install the test browser
+        working-directory: documentation
+        run: pnpm exec playwright install --with-deps --only-shell chromium
+
+      - name: Documentation integration tests
+        working-directory: documentation
+        run: pnpm run test
+
+      # Only on the deploy path; the deploy job consumes this. Uploading needs no extra
+      # permissions of its own, `pages: write` lives on the deploy job.
+      - name: Upload Pages artefact
+        if: ${{ inputs.upload_pages_artifact }}
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: documentation/build

.github/workflows/examples.yml

@@ -13,7 +13,7 @@ on:
       - 'examples/**'
       - 'src/main/**'
       - 'pom.xml'
-      - 'docs/HowToMakeAProjectAnAresProject.md'
+      - 'documentation/docs/instructor/protect-a-java-project/**'
       - '.github/workflows/examples.yml'
   push:
     branches: [ "main" ]

AGENTS.md

@@ -1,6 +1,9 @@
 # AGENTS.md
 
-Repository conventions for automated agents and contributors working on Ares.
+Repository conventions for automated agents and contributors working on Ares 2. Every
+convention lives here, stated once. [CLAUDE.md](./CLAUDE.md) imports this file and adds the
+orientation an agent needs beside it: what the project is, how it is built, and where its
+parts live.
 
 ## Testing network access (incoming and outgoing)