Pinont · Pinont · Sep 1, 2026
diff --git a/.github/workflows/pages-repo.yml b/.github/workflows/pages-repo.yml
@@ -5,10 +5,18 @@ on:
     branches: [ main, "rework/v2" ]
   workflow_dispatch:
 
+# Shared with publish-javadoc.yml so Maven-layout and JavaDoc pushes to
+# Pinont/singularity-maven gh-pages do not race.
+concurrency:
+  group: singularity-maven-gh-pages
+  cancel-in-progress: false
+
 jobs:
   deploy:
     # Pushes the maven repo layout to Pinont/singularity-maven (Pages-served,
     # anonymous reads). Accumulative: previously published versions are kept.
+    # JavaDoc HTML is published separately under /javadoc/ by publish-javadoc.yml
+    # — do not delete that tree.
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

diff --git a/.github/workflows/publish-javadoc.yml b/.github/workflows/publish-javadoc.yml
@@ -0,0 +1,111 @@
+name: publish-javadoc
+
+# Generates JavaDoc HTML and copies it into Pinont/singularity-maven (gh-pages),
+# which is served at https://maven.pinont.me. Paths are under /javadoc/ so they
+# never collide with the Maven layout (io/, com/) written by pages-repo.yml.
+#
+# Do not enable GitHub Pages on Pinont/SingularityLib — that URL is the
+# portfolio (pinont.me), not this library.
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+concurrency:
+  group: singularity-maven-gh-pages
+  cancel-in-progress: false
+
+jobs:
+  javadoc:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup JDK 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '25'
+
+      - name: Install annotation processor module
+        run: mvn -q install -DskipTests -f singularitylib-processor/pom.xml
+
+      - name: Resolve project version
+        id: ver
+        run: |
+          VERSION=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.version)
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate JavaDoc HTML
+        run: mvn -q javadoc:javadoc -DskipTests
+
+      - name: Locate JavaDoc output
+        id: javadoc
+        run: |
+          if [ -d target/site/apidocs ]; then
+            echo "dir=target/site/apidocs" >> "$GITHUB_OUTPUT"
+          elif [ -d target/reports/apidocs ]; then
+            echo "dir=target/reports/apidocs" >> "$GITHUB_OUTPUT"
+          else
+            echo "JavaDoc output not found under target/site or target/reports" >&2
+            find target -type d -name apidocs || true
+            exit 1
+          fi
+
+      - name: Clone singularity-maven (gh-pages)
+        run: |
+          git clone --depth 1 --branch gh-pages \
+            "https://x-access-token:${{ secrets.MAVEN_REPO_TOKEN }}@github.com/Pinont/singularity-maven.git" \
+            singularity-maven-pages
+
+      - name: Stage JavaDoc (Maven group paths untouched)
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+          JAVADOC_DIR: ${{ steps.javadoc.outputs.dir }}
+        run: |
+          set -euo pipefail
+          ROOT="singularity-maven-pages"
+          DEST="${ROOT}/javadoc/singularitylib"
+          mkdir -p "${DEST}"
+          cp docs/javadoc-root.html "${ROOT}/javadoc/index.html"
+          cp docs/index.html "${DEST}/index.html"
+          rm -rf "${DEST}/${VERSION}"
+          mkdir -p "${DEST}/${VERSION}"
+          cp -R "${JAVADOC_DIR}/." "${DEST}/${VERSION}/"
+          # Copy, not symlink — GitHub Pages does not follow git symlinks.
+          rm -rf "${DEST}/latest"
+          mkdir -p "${DEST}/latest"
+          cp -R "${JAVADOC_DIR}/." "${DEST}/latest/"
+          touch "${ROOT}/.nojekyll"
+
+      - name: Commit and push
+        run: |
+          set -euo pipefail
+          cd singularity-maven-pages
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add javadoc .nojekyll
+          if git diff --cached --quiet; then
+            echo "No javadoc changes"
+            exit 0
+          fi
+          git commit -m "docs: javadoc singularitylib ${{ steps.ver.outputs.version }} (${{ github.sha }})"
+          for i in 1 2 3 4; do
+            git pull --rebase origin gh-pages
+            if git push origin gh-pages; then
+              exit 0
+            fi
+            sleep $((i * 4))
+          done
+          echo "Failed to push gh-pages after retries" >&2
+          exit 1
+
+      - name: Trigger Pages rebuild
+        run: |
+          curl -s -X POST \
+            -H "Authorization: Bearer ${{ secrets.MAVEN_REPO_TOKEN }}" \
+            -H "Accept: application/vnd.github+json" \
+            https://api.github.com/repos/Pinont/singularity-maven/pages/builds -o /dev/null -w "%{http_code}\n"
diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # SingularityLib
 
-[![](https://img.shields.io/github/license/pinont/singularitylib)](https://github.com/Pinont/SingularityLib/blob/main/LICENSE) [![](https://img.shields.io/maven-central/v/io.github.pinont/singularitylib)](https://central.sonatype.com/artifact/io.github.pinont/singularitylib) [![](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml/badge.svg)](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml)
+[![](https://img.shields.io/github/license/pinont/singularitylib)](https://github.com/Pinont/SingularityLib/blob/main/LICENSE) [![](https://img.shields.io/maven-central/v/io.github.pinont/singularitylib)](https://central.sonatype.com/artifact/io.github.pinont/singularitylib) [![](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml/badge.svg)](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml) [![JavaDoc](https://img.shields.io/badge/docs-JavaDoc-e0a54b)](https://maven.pinont.me/javadoc/singularitylib/)
+
+**Docs / JavaDoc:** [maven.pinont.me/javadoc/singularitylib](https://maven.pinont.me/javadoc/singularitylib/) · [latest API](https://maven.pinont.me/javadoc/singularitylib/latest/) · [javadoc.io fallback](https://javadoc.io/doc/io.github.pinont/singularitylib/2.0.0)
 
 A fork of [ExperienceLib](https://github.com/pinont/ExperienceLib)
 

diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,168 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>SingularityLib — Docs</title>
+  <meta name="description" content="SingularityLib JavaDoc and install coordinates. A PaperMC plugin development library.">
+  <style>
+    :root {
+      --bg: #0f1419;
+      --panel: #171e27;
+      --ink: #e8eef4;
+      --muted: #9aa8b5;
+      --line: #2a3542;
+      --accent: #e0a54b;
+      --accent-ink: #1a1408;
+      --link: #7ec8e8;
+    }
+    * { box-sizing: border-box; }
+    html, body { margin: 0; padding: 0; }
+    body {
+      font-family: "Segoe UI", system-ui, sans-serif;
+      background: var(--bg);
+      color: var(--ink);
+      line-height: 1.55;
+      min-height: 100vh;
+    }
+    main {
+      max-width: 44rem;
+      margin: 0 auto;
+      padding: 3.5rem 1.25rem 4rem;
+    }
+    .eyebrow {
+      font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+      font-size: 0.75rem;
+      letter-spacing: 0.12em;
+      text-transform: uppercase;
+      color: var(--accent);
+      margin: 0 0 0.75rem;
+    }
+    h1 {
+      font-size: 2.15rem;
+      font-weight: 600;
+      letter-spacing: -0.02em;
+      margin: 0 0 0.75rem;
+    }
+    .lead { color: var(--muted); margin: 0 0 1.75rem; }
+    .actions {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 0.6rem;
+      margin: 0 0 2.25rem;
+    }
+    a.btn {
+      display: inline-flex;
+      align-items: center;
+      text-decoration: none;
+      font-weight: 500;
+      font-size: 0.95rem;
+      padding: 0.55rem 0.95rem;
+      border-radius: 6px;
+      border: 1px solid var(--line);
+      color: var(--ink);
+      background: var(--panel);
+    }
+    a.btn.primary {
+      background: var(--accent);
+      color: var(--accent-ink);
+      border-color: var(--accent);
+    }
+    a.btn:hover { filter: brightness(1.08); }
+    section {
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 10px;
+      padding: 1.15rem 1.2rem 1.05rem;
+      margin: 0 0 1rem;
+    }
+    h2 {
+      font-size: 0.95rem;
+      font-weight: 600;
+      margin: 0 0 0.65rem;
+    }
+    p { margin: 0 0 0.7rem; }
+    p:last-child { margin-bottom: 0; }
+    code, pre {
+      font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+      font-size: 0.85rem;
+    }
+    pre {
+      margin: 0;
+      overflow-x: auto;
+      background: #0c1015;
+      border: 1px solid var(--line);
+      border-radius: 6px;
+      padding: 0.85rem 1rem;
+      color: var(--ink);
+    }
+    a { color: var(--link); }
+    ul { margin: 0.25rem 0 0; padding-left: 1.2rem; color: var(--muted); }
+    li { margin: 0.2rem 0; }
+    footer {
+      margin-top: 2rem;
+      color: var(--muted);
+      font-size: 0.85rem;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <p class="eyebrow">PaperMC · JDK 25 · Maven Central</p>
+    <h1>SingularityLib</h1>
+    <p class="lead">
+      Core API library for Paper plugins: commands, config, GUI, items, entities,
+      compile-time auto-registration, database helpers, and Discord JDA bootstrap.
+    </p>
+
+    <div class="actions">
+      <a class="btn primary" href="./latest/index.html">Browse JavaDoc</a>
+      <a class="btn" href="https://github.com/Pinont/SingularityLib#installation-maven">Install (README)</a>
+      <a class="btn" href="https://central.sonatype.com/artifact/io.github.pinont/singularitylib">Maven Central</a>
+    </div>
+
+    <section>
+      <h2>Maven Central coordinates</h2>
+      <p>Releases are on Central — no extra repository block. Scope <code>provided</code>; the lib loads as its own server plugin.</p>
+      <pre><code>&lt;dependency&gt;
+  &lt;groupId&gt;io.github.pinont&lt;/groupId&gt;
+  &lt;artifactId&gt;singularitylib&lt;/artifactId&gt;
+  &lt;version&gt;2.0.0&lt;/version&gt;
+  &lt;scope&gt;provided&lt;/scope&gt;
+&lt;/dependency&gt;</code></pre>
+    </section>
+
+    <section>
+      <h2>JavaDoc</h2>
+      <p>
+        HTML is generated from <code>src/main/java</code> and published on
+        <code>maven.pinont.me</code> next to the snapshot Maven repository.
+      </p>
+      <ul>
+        <li><a href="./latest/index.html">Latest from <code>main</code></a> — <code>/javadoc/singularitylib/latest/</code></li>
+        <li>Per-version copies live under <code>/javadoc/singularitylib/&lt;version&gt;/</code></li>
+        <li>Fallback:
+          <a href="https://javadoc.io/doc/io.github.pinont/singularitylib/2.0.0">javadoc.io (2.0.0)</a>
+          (Central sync may lag)
+        </li>
+      </ul>
+    </section>
+
+    <section>
+      <h2>Snapshots</h2>
+      <p>
+        Dev builds: <code>io.github.pinont:singularitylib:2.0.0-SNAPSHOT</code> from
+        <a href="https://maven.pinont.me">https://maven.pinont.me</a>.
+        Full install notes, including the bootstrap <code>paper-plugin.yml</code> snippet, are in the
+        <a href="https://github.com/Pinont/SingularityLib#installation-maven">README</a>.
+      </p>
+    </section>
+
+    <footer>
+      <a href="https://github.com/Pinont/SingularityLib">GitHub</a>
+      ·
+      <a href="https://github.com/Pinont/SingularityLib/blob/main/LICENSE">MIT</a>
+    </footer>
+  </main>
+</body>
+</html>
diff --git a/docs/javadoc-root.html b/docs/javadoc-root.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Singularity JavaDoc</title>
+  <meta http-equiv="refresh" content="0; url=singularitylib/">
+  <link rel="canonical" href="singularitylib/">
+</head>
+<body>
+  <p>JavaDoc: <a href="singularitylib/">SingularityLib</a></p>
+</body>
+</html>
diff --git a/pom.xml b/pom.xml
@@ -170,18 +170,20 @@
                 </executions>
             </plugin>
 
-            <!-- Javadoc JAR (failOnError=false to avoid build breaks) -->
+            <!-- Javadoc JAR (attached for Central) + HTML via javadoc:javadoc for the docs site.
+                 failOnError stays false so missing comments / JDK 25 lint do not fail the build. -->
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <version>3.7.0</version>
+                <configuration>
+                    <failOnError>false</failOnError>
+                    <failOnWarnings>false</failOnWarnings>
+                </configuration>
                 <executions>
                     <execution>
                         <id>attach-javadocs</id>
                         <goals><goal>jar</goal></goals>
-                        <configuration>
-                            <failOnError>false</failOnError>
-                        </configuration>
                     </execution>
                 </executions>
             </plugin>