docs: add Sourcey-generated API site

.github/workflows/sourcey-docs.yml

@@ -0,0 +1,78 @@
+name: Sourcey docs
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/sourcey-docs.yml"
+      - "docs-sourcey/**"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/sourcey-docs.yml"
+      - "docs-sourcey/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: sourcey-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7.0.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7.0.0
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: docs-sourcey/package-lock.json
+
+      - name: Install dependencies
+        working-directory: docs-sourcey
+        run: npm ci
+
+      - name: Build Sourcey site
+        working-directory: docs-sourcey
+        run: npm run build
+
+      - name: Validate generated documentation
+        working-directory: docs-sourcey
+        run: npm run validate
+
+      - name: Check generated internal links
+        working-directory: docs-sourcey
+        run: npm run linkcheck
+
+      - name: Verify governed receipt
+        working-directory: docs-sourcey
+        run: npm run verify-receipt
+
+      - name: Configure GitHub Pages
+        if: github.event_name != 'pull_request'
+        uses: actions/configure-pages@v6.0.0
+
+      - name: Upload GitHub Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v5.0.0
+        with:
+          path: docs-sourcey/dist
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-24.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5.0.0

docs-sourcey/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+validation-receipts/
+validation-run.json
+/sha256-*.json

docs-sourcey/README.md

@@ -0,0 +1,29 @@
+# Sourcey documentation
+
+This directory builds a Sourcey documentation site for ftpserverlib. It combines
+five maintained guides with a generated Go API reference sourced from a committed
+`godoc.json` snapshot.
+
+The snapshot is pinned to commit
+`b4c3694ee73399d8a55293d568e5100c25e4d2d4`, so documentation builds do not need
+the Go toolchain and every generated source link resolves to the exact code that
+was documented.
+
+## Build and validate
+
+```sh
+npm ci
+npm run build
+npm run validate
+npm run verify-receipt
+```
+
+`npm run verify-receipt` verifies the committed RunX receipt with its public
+Ed25519 key. The private signing seed is not stored in this repository.
+
+## Deployment
+
+The `Sourcey docs` workflow builds pull requests and deploys the generated `dist`
+directory to this repository's GitHub Pages site after a merge to `main`.
+Repository owners need to select **GitHub Actions** as the Pages source once if it
+is not already enabled.

docs-sourcey/REPORT.md

@@ -0,0 +1,29 @@
+# Sourcey Go documentation report
+
+This contribution adds a reproducible Sourcey documentation site for
+`fclairamb/ftpserverlib`, a maintained MIT-licensed Go library.
+
+The generated reference is pinned to commit
+`b4c3694ee73399d8a55293d568e5100c25e4d2d4`. The committed GoDoc snapshot
+contains 92 public API concepts, and the generated API page contains 65 links
+back to exact lines at that commit. Five authored guides cover setup, the driver
+contract, server settings, and extension points. The build also emits `llms.txt`
+and `llms-full.txt` for machine-readable discovery.
+
+Validation is intentionally independent of a local Go installation:
+
+```sh
+npm ci
+npm run build
+npm run validate
+npm run verify-receipt
+```
+
+The governed RunX receipt uses `runx-cli 0.7.0` and a production Ed25519
+signature. Its public verification key is committed in the verifier; the private
+signing seed is not published.
+
+The workflow validates every relevant pull request. After merge, it deploys the
+same generated output to the repository-owned GitHub Pages site. If Pages has not
+been enabled for this repository before, an owner needs to select **GitHub
+Actions** as the Pages source once.

docs-sourcey/driver-contract.md

@@ -0,0 +1,19 @@
+# Driver contract
+
+`MainDriver` is the integration boundary between the FTP engine and your
+application. Implement it to:
+
+- return a `Settings` value from `GetSettings`;
+- produce the welcome message in `ClientConnected`;
+- release per-client state in `ClientDisconnected`;
+- authenticate credentials and return a `ClientDriver` from `AuthUser`;
+- return the current `tls.Config` from `GetTLSConfig` when TLS is enabled.
+
+`ClientDriver` embeds `afero.Fs`. This keeps ordinary filesystem operations in
+a familiar interface and lets a server choose memory, disk, object-backed, or
+application-specific storage.
+
+Callbacks receive a `ClientContext`. It exposes the connection ID, addresses,
+current path, TLS state, debug flag, last command, last data-channel mode, and
+a method to close the connection. Treat it as connection-scoped state; do not
+store it globally.

docs-sourcey/extensions.md

@@ -0,0 +1,19 @@
+# Optional extensions
+
+Implement extension interfaces only for behavior your storage layer supports.
+The core library detects these interfaces at runtime.
+
+- `ClientDriverExtensionAllocate` reserves upload space for `ALLO`.
+- `ClientDriverExtensionAvailableSpace` reports space for `AVBL`.
+- `ClientDriverExtensionSymlink` adds symbolic-link support.
+- `ClientDriverExtensionHasher` computes digests when `EnableHASH` is set.
+- `FileTransferError` receives detected abort, disconnect, and copy failures
+  before the underlying file is closed.
+
+FTP uploads do not carry a universal length header, so a server cannot detect
+every truncated upload. The transfer-error hook reports failures the protocol
+engine can observe; applications that need end-to-end completeness should add
+their own size, digest, or transaction checks.
+
+See the generated API reference for the remaining extension interfaces and
+their exact method signatures.