docs: add GitHub Pages documentation site and AGENT.md

.github/workflows/ci-full.yml

@@ -1,11 +1,12 @@
 name: CI Full
 
 # Full test matrix (all OS × build types × Python versions) plus wheel/sdist builds.
-# One-click via "Run workflow" in GitHub UI — also calls the coverage gate so
-# everything runs together. The coverage gate also runs automatically on
-# push/PR to main (ci.yml).
+# Triggered manually ("Run workflow") or by posting `/run-ci` in any PR comment.
+# The coverage gate also runs automatically on push/PR to main (ci.yml).
 on:
   workflow_dispatch:
+  issue_comment:
+    types: [created]
 
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
@@ -18,10 +19,18 @@ jobs:
   # ── Coverage gate (reuses ci.yml definition — no duplication) ─────────────
   coverage:
     name: Coverage Gate
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.issue.pull_request != null &&
+       contains(github.event.comment.body, '/run-ci'))
     uses: ./.github/workflows/ci.yml
 
   test:
     name: Test / ${{ matrix.os }} / ${{ matrix.build-type }} / py${{ matrix.python-version }}
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.issue.pull_request != null &&
+       contains(github.event.comment.body, '/run-ci'))
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -43,6 +52,8 @@ jobs:
         with:
           submodules: recursive
           lfs: true
+          # When triggered by a PR comment, check out the PR head branch
+          ref: ${{ github.event_name == 'issue_comment' && format('refs/pull/{0}/head', github.event.issue.number) || github.sha }}
 
       - name: Install dependencies (Linux)
         if: runner.os == 'Linux'
@@ -52,14 +63,23 @@ jobs:
         if: runner.os == 'macOS'
         run: |
           brew install llvm
-          echo "$(brew --prefix llvm)/bin" >> $GITHUB_PATH
+          LLVM_PREFIX="$(brew --prefix llvm)"
+          echo "${LLVM_PREFIX}/bin" >> "$GITHUB_PATH"
+          echo "CC=${LLVM_PREFIX}/bin/clang"   >> "$GITHUB_ENV"
+          echo "CXX=${LLVM_PREFIX}/bin/clang++" >> "$GITHUB_ENV"
 
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
 
       - name: Configure
-        run: cmake -B build -DCMAKE_BUILD_TYPE=${{ matrix.build-type }} -DUSE_PYTHON=ON -DUSE_TESTS=ON
+        run: |
+          cmake -B build \
+            -DCMAKE_BUILD_TYPE=${{ matrix.build-type }} \
+            -DUSE_PYTHON=ON \
+            -DUSE_TESTS=ON \
+            "-DCMAKE_CXX_CLANG_TIDY="
 
       - name: Build
         run: cmake --build build --config ${{ matrix.build-type }} --parallel

.github/workflows/pages.yml

@@ -0,0 +1,63 @@
+name: GitHub Pages
+
+on:
+  push:
+    branches: [main, docs]
+    paths:
+      - 'docs/**'
+      - 'cpp/rcspp/**'
+      - 'python/src/rcspp/**'
+      - 'python/bindings/**'
+      - 'AGENT.md'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/configure-pages@v5
+
+      - name: Install Doxygen
+        run: sudo apt-get update -q && sudo apt-get install -y doxygen
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install Python dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Generate Doxygen XML
+        working-directory: docs
+        run: doxygen Doxyfile
+
+      - name: Build Sphinx site
+        working-directory: docs
+        run: sphinx-build -b html . _site -W --keep-going
+        env:
+          SPHINXOPTS: "-j auto"
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -62,3 +62,8 @@ Testing/
 
 # Clion
 .idea/
+
+# Sphinx / Doxygen generated
+docs/_doxygen/
+docs/_site/
+docs/cpp/api/

.markdownlint.json

@@ -0,0 +1,15 @@
+{
+  "default": true,
+  "MD013": {
+    "line_length": 120,
+    "code_block_line_length": 200,
+    "tables": false
+  },
+  "MD024": {
+    "siblings_only": true
+  },
+  "MD025": {
+    "front_matter_title": ""
+  },
+  "MD060": false
+}