Merge remote-tracking branch 'origin/main' into chore/ai-crawler-ruleschore/ai-crawler-rules

7 files changed, 80 insertions, 0 deletions

diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json
new file mode 100644
index 0000000..e4d2756
--- /dev/null
+++ b/.config/dotnet-tools.json
@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.81.0",
+      "commands": ["docfx"],
+      "rollForward": false
+    }
+  }
+}
diff --git a/.github/workflows/backend.yml b/.github/workflows/backend.yml
index 173c5c6..a1f6320 100644
--- a/.github/workflows/backend.yml
+++ b/.github/workflows/backend.yml
@@ -11,6 +11,8 @@ on:
       - "apps/api-tests/**"
       - "Directory.Build.props"
       - "Progmaweb.slnx"
+      - "docs/api/**"
+      - ".config/dotnet-tools.json"
       - ".github/workflows/backend.yml"
   pull_request:
     paths:
@@ -18,6 +20,8 @@ on:
       - "apps/api-tests/**"
       - "Directory.Build.props"
       - "Progmaweb.slnx"
+      - "docs/api/**"
+      - ".config/dotnet-tools.json"
       - ".github/workflows/backend.yml"
   workflow_dispatch:
 
@@ -43,6 +47,11 @@ jobs:
       - run: dotnet build Progmaweb.slnx --configuration Release --no-restore
       - run: dotnet test --project apps/api-tests/Progmaweb.Api.Tests.csproj --configuration Release --no-build --coverlet --coverlet-output-format cobertura
 
+      # Documentation gate: DocFX reads the API project and builds the
+      # reference; an unresolved reference or a broken link is an error.
+      - run: dotnet tool restore
+      - run: dotnet docfx docs/api/docfx.json --warningsAsErrors
+
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: progmaweb-backend-coverage
diff --git a/.gitignore b/.gitignore
index 641c3ae..dada051 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,3 +18,7 @@ obj/
 .env
 .env.*
 !.env.example
+
+# DocFX output
+docs/api/_site/
+docs/api/reference/
diff --git a/docs/api/docfx.json b/docs/api/docfx.json
new file mode 100644
index 0000000..e10a9b0
--- /dev/null
+++ b/docs/api/docfx.json
@@ -0,0 +1,26 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../../apps/api",
+          "files": ["Progmaweb.Api.csproj"]
+        }
+      ],
+      "dest": "reference",
+      "includePrivateMembers": true
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": ["index.md", "toc.yml", "reference/**/*.yml"]
+      }
+    ],
+    "dest": "_site",
+    "globalMetadata": {
+      "_appTitle": "Progmaweb API",
+      "_enableSearch": false
+    }
+  }
+}
diff --git a/docs/api/index.md b/docs/api/index.md
new file mode 100644
index 0000000..868fff1
--- /dev/null
+++ b/docs/api/index.md
@@ -0,0 +1,19 @@
+<!--
+SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com>
+SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1
+-->
+
+# Progmaweb API
+
+Reference documentation of the Progmaweb account service, generated by DocFX
+from the XML documentation comments of `apps/api`.
+
+The service is an application, not a library, so most of its types are
+internal. The reference includes them: it documents the code for the people
+who maintain it.
+
+Build it from the repository root:
+
+```sh
+docfx docs/api/docfx.json --warningsAsErrors
+```
diff --git a/docs/api/toc.yml b/docs/api/toc.yml
new file mode 100644
index 0000000..cf49dc1
--- /dev/null
+++ b/docs/api/toc.yml
@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1
+
+- name: Overview
+  href: index.md
+- name: Reference
+  href: reference/
diff --git a/justfile b/justfile
index 99ccdbd..d3c29c6 100644
--- a/justfile
+++ b/justfile
@@ -19,3 +19,7 @@ api-test:
     dotnet test --project apps/api-tests/Progmaweb.Api.Tests.csproj --configuration Release
 
 verify: web-check web-build api-build api-test
+
+api-docs:
+    dotnet tool restore
+    dotnet docfx docs/api/docfx.json --warningsAsErrors