From ac592aa98651aa2f5e890f8ec1bd701a3dac7036 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Tue, 10 Nov 2026 15:01:27 +0000
Subject: [PATCH 1/5] docs: document the LibreSign 16 native webhook
 integration

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 _templates/home.html                          |   4 +-
 developer_manual/index.rst                    |   2 +
 .../integration/_native-webhooks.inc          |  15 +-
 developer_manual/webhooks/configuration.rst   |  91 +++++++
 developer_manual/webhooks/event-catalog.rst   | 121 +++++++++
 .../webhooks/external-signing-flow.rst        | 231 ++++++++++++++++++
 developer_manual/webhooks/index.rst           |  23 ++
 .../webhooks/signing_completion.rst           |  61 +++++
 style_guide.rst                               |  20 +-
 9 files changed, 549 insertions(+), 19 deletions(-)
 create mode 100644 developer_manual/webhooks/configuration.rst
 create mode 100644 developer_manual/webhooks/event-catalog.rst
 create mode 100644 developer_manual/webhooks/external-signing-flow.rst
 create mode 100644 developer_manual/webhooks/index.rst
 create mode 100644 developer_manual/webhooks/signing_completion.rst

diff --git a/_templates/home.html b/_templates/home.html
index afa3fcb4..453e0e9d 100644
--- a/_templates/home.html
+++ b/_templates/home.html
@@ -58,7 +58,7 @@ <h2 id="versions-title">Available versions</h2>
           <article class="version-row {% if entry.status == 'current' %}version-current{% endif %}" data-version="{{ entry.slug }}">
             <div class="version-identification">
               <h3><a href="{{ entry.slug }}/">
-                {% if entry.slug == 'main' %}main{% else %}LibreSign {{ entry.slug }}{% endif %}
+                {% if entry.slug == 'main' %}{% if entry.app_version is defined %}LibreSign {{ entry.app_version.split('.')[0] }}{% else %}Development{% endif %}{% else %}LibreSign {{ entry.slug }}{% endif %}
               </a></h3>
               <p class="release-status">
                 {% if entry.status == 'development' %}Development (not a stable release)
@@ -68,7 +68,7 @@ <h3><a href="{{ entry.slug }}/">
               </p>
               <p class="compatibility">Nextcloud {{ entry.nextcloud_min }}{% if entry.nextcloud_min != entry.nextcloud_max %}–{{ entry.nextcloud_max }}{% endif %}</p>
             </div>
-            <nav class="manual-links" aria-label="{% if entry.slug == 'main' %}Development{% else %}LibreSign {{ entry.slug }}{% endif %} manuals">
+            <nav class="manual-links" aria-label="{% if entry.slug == 'main' %}{% if entry.app_version is defined %}LibreSign {{ entry.app_version.split('.')[0] }}{% else %}Development{% endif %}{% else %}LibreSign {{ entry.slug }}{% endif %} manuals">
               <a href="{{ entry.slug }}/user_manual/">User manual</a>
               <a href="{{ entry.slug }}/admin_manual/">Administrator manual</a>
               <a href="{{ entry.slug }}/developer_manual/">Developer manual and API</a>
diff --git a/developer_manual/index.rst b/developer_manual/index.rst
index b658a152..4ab20930 100644
--- a/developer_manual/index.rst
+++ b/developer_manual/index.rst
@@ -21,6 +21,7 @@ Start here
 - :doc:`getting-started/tests` — choose and run the appropriate validation.
 - :doc:`api/index` — work with the public API.
 - :doc:`integration/index` — choose an integration architecture for an existing system.
+- :doc:`webhooks/index` — configure webhook subscriptions for signing workflows.
 - :doc:`translation` — contribute translations and document source-string context.
 - :doc:`release-process` — maintain and publish releases.
 
@@ -51,6 +52,7 @@ For professional services or partnerships,
    development-workflow
    api/index
    integration/index
+   webhooks/index
    translation
    requesting-features
    release-process
diff --git a/developer_manual/integration/_native-webhooks.inc b/developer_manual/integration/_native-webhooks.inc
index 033e6797..bd264153 100644
--- a/developer_manual/integration/_native-webhooks.inc
+++ b/developer_manual/integration/_native-webhooks.inc
@@ -1,11 +1,8 @@
 .. note::
 
-   **Development line (LibreSign 16 / Nextcloud 36):** The application source
-   now implements the aggregate ``SigningRequestCompletedEvent`` using
-   Nextcloud's ``IWebhookCompatibleEvent``. It represents a document or
-   envelope workflow changing to ``SIGNED``, not each individual signature.
-   This is a source-level contract; verify installed event availability,
-   Nextcloud worker HTTP delivery and receiver authentication before use.
-   The administrator and payload reference is maintained specifically in
-   `LibreSign 16's Webhooks guide
-   <https://github.com/LibreSign/documentation/blob/main/versioned/16/developer_manual/webhooks/index.rst>`_.
+   For signing-workflow notifications, subscribe to native LibreSign
+   events through Nextcloud Webhook Listeners. Events represent persisted
+   business transitions and deliver JSON metadata without signed PDFs.
+   See :doc:`../webhooks/event-catalog` for the available classes,
+   :doc:`../webhooks/configuration` for subscription setup, and
+   :doc:`../webhooks/external-signing-flow` for document recovery.
diff --git a/developer_manual/webhooks/configuration.rst b/developer_manual/webhooks/configuration.rst
new file mode 100644
index 00000000..e5c22a72
--- /dev/null
+++ b/developer_manual/webhooks/configuration.rst
@@ -0,0 +1,91 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: CC-BY-3.0
+
+============================
+Configure webhook deliveries
+============================
+
+Native LibreSign webhooks use Nextcloud's **Webhook Listeners** application.
+A Nextcloud administrator registers a receiving HTTPS endpoint and selects
+which event class should trigger it. A separate receiver application can keep
+its own authentication and user interface. The complete procedure, from
+creating an external signing request to fetching its PDF, is in
+:doc:`external-signing-flow`.
+
+Prerequisites
+-------------
+
+Nextcloud documents ``occ`` subcommands independently of the operating
+system and installation method. Execute them through the appropriate Nextcloud
+administration CLI for your installation, rather than assuming ``sudo``, an
+HTTP-user name or a container name. See Nextcloud's
+`Using the occ command <https://docs.nextcloud.com/server/stable/admin_manual/occ_command.html>`_,
+`Docker instructions <https://github.com/nextcloud/docker#accessing-the-nextcloud-command-line-interface-occ>`_
+and `Snap instructions <https://github.com/nextcloud-snap/nextcloud-snap/wiki/OCC-management-console>`_.
+
+- Choose an event class from :doc:`event-catalog`.
+- Enable **Webhook Listeners** from the Nextcloud **Apps** administration page,
+  or use the Nextcloud command:
+
+  .. code-block:: console
+
+     occ app:enable webhook_listeners
+
+- Select **Cron** mode under Nextcloud background-job settings, or use:
+
+  .. code-block:: console
+
+     occ background:cron
+
+  This only selects the execution mode; it **does not install a scheduler**.
+  Configure an actual scheduler to run ``cron.php`` periodically (or use the
+  equivalent provided by your installation) and verify jobs execute.
+  Follow Nextcloud's
+  `background-jobs configuration <https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/background_jobs_configuration.html>`_.
+
+- Allow the Nextcloud server to reach the receiver over HTTPS.
+- Provide a receiver that accepts JSON requests, authenticates the sender,
+  and can process duplicate messages safely.
+
+Register a listener
+-------------------
+
+Use Nextcloud's Webhook Listeners administration API, not LibreSign's signing
+API, to create the subscription:
+
+.. code-block:: text
+
+   POST /ocs/v2.php/apps/webhook_listeners/api/v1/webhooks
+
+Authenticate as an administrator authorized to manage Webhook Listeners, using
+an App Password where supported and the ``OCS-APIRequest: true`` header.
+The registration fields include:
+
+- ``httpMethod``: use ``POST``.
+- ``uri``: HTTPS URL of the receiver; do not include credentials in the URL.
+- ``event``: the fully qualified event name shown on its reference page.
+- ``eventFilter``: omit or use an empty filter to accept every occurrence, or
+  define a filter supported by your Nextcloud version.
+- ``userIdFilter``: leave unset for events initiated by external signers or
+  background jobs, where no Nextcloud user may be in the current session.
+- ``headers``, ``authMethod`` and ``authData``: configure the authentication
+  mechanism supported by your installed Webhook Listeners version. Use a
+  dedicated receiver credential and keep it outside source control.
+
+For the complete request schema, permission rules and available authentication
+modes, consult your installed Nextcloud Webhook Listeners API documentation.
+Each release of Nextcloud controls these administrative fields independently.
+
+Delivery and recovery
+---------------------
+
+Webhook Listeners schedules HTTP delivery through Nextcloud background jobs.
+A successful signing operation does not mean the HTTP request has already
+reached the receiver. Return a ``2xx`` response when an event is accepted and
+store an event-specific idempotency key when the event provides one.
+
+Do not assume exactly-once delivery, guaranteed ordering or automatic retry
+of failed HTTP requests. Inspect the Nextcloud log and the receiver log when
+notifications are missing. Reconcile the current workflow using authenticated
+LibreSign API operations and the permissions of the integrating account.
+Never use a webhook payload as authorization to download a signed file.
diff --git a/developer_manual/webhooks/event-catalog.rst b/developer_manual/webhooks/event-catalog.rst
new file mode 100644
index 00000000..de59c53a
--- /dev/null
+++ b/developer_manual/webhooks/event-catalog.rst
@@ -0,0 +1,121 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: CC-BY-3.0
+
+=======================
+LibreSign event catalog
+=======================
+
+LibreSign provides signing-workflow events through Nextcloud's
+**Webhook Listeners** app. An administrator can subscribe to any event
+listed below by its fully qualified PHP class name. The subscription
+is managed by Nextcloud and delivered asynchronously by its background
+jobs. All six classes implement
+``OCP\EventDispatcher\IWebhookCompatibleEvent``.
+
+Available events
+----------------
+
+All classes use the ``OCA\Libresign\Events`` namespace.
+
+.. list-table:: Webhook-compatible events
+   :header-rows: 1
+   :widths: 38 62
+
+   * - Class name
+     - When it is emitted
+   * - ``SigningRequestReadyEvent``
+     - A document or envelope is created ready to sign, or its workflow
+       moves from draft to ready. Repeated updates to the ready state do
+       not generate another event.
+   * - ``SignerSignedWebhookEvent``
+     - One signer completes a signature for a document. An envelope
+       containing multiple documents can produce an event per signed
+       document, all associated with the same envelope request.
+   * - ``SignerRejectedWebhookEvent``
+     - A signer's rejection is persisted, once per business rejection,
+       regardless of how many identification methods are configured.
+       The payload indicates whether the workflow was canceled.
+   * - ``SigningRequestCompletedEvent``
+     - The document or parent envelope reaches its completed state.
+       Partial signatures alone do not generate a completion event.
+       A workflow may complete even if a signer rejected, depending on
+       its rejection policy.
+   * - ``SigningRequestCanceledEvent``
+     - A rejection causes the document or parent envelope's workflow
+       to enter the canceled state. This does not represent the removal
+       of an individual signer.
+   * - ``NotificationDeliveryStatusChangedEvent``
+     - A notification submission attempt receives a persisted outcome
+       from the configured channel adapter. This does not establish
+       that a recipient received or read the message.
+
+Event payloads
+--------------
+
+The serialized ``event`` object of every LibreSign webhook contains:
+
+- ``contractVersion``: version of the event's JSON contract (``1``).
+- ``eventId``: stable identifier for deduplicating repeated deliveries.
+- ``requestUuid``: identifier of the signing workflow or parent envelope.
+- ``requestType``: ``document`` or ``envelope``.
+
+Each event also provides these fields:
+
+.. list-table:: Event-specific fields
+   :header-rows: 1
+   :widths: 38 62
+
+   * - Class name
+     - Additional fields
+   * - ``SigningRequestReadyEvent``
+     - ``status: "ready_to_sign"``.
+   * - ``SignerSignedWebhookEvent``
+     - ``status: "signed"``, ``documentUuid``, ``signerId``.
+   * - ``SignerRejectedWebhookEvent``
+     - ``status: "rejected"``, ``documentUuid``, ``signerId``,
+       ``workflowCanceled`` (boolean).
+   * - ``SigningRequestCompletedEvent``
+     - ``status: "completed"``.
+   * - ``SigningRequestCanceledEvent``
+     - ``status: "canceled"``.
+   * - ``NotificationDeliveryStatusChangedEvent``
+     - ``deliveryId``, ``channel``, ``state``, ``attempt``.
+
+For workflow events, ``eventId`` is derived from the request UUID and
+transition. Signer events use deterministic identifiers associated with
+the persisted signing or rejection action. Notification delivery events
+identify the delivery record, attempt and outcome. Do not rely on the
+arrival order or assume that a delivery occurs exactly once.
+
+The notification ``state`` can be ``accepted``,
+``temporary_failure``, ``permanent_failure``, ``failed``,
+``unknown`` or ``canceled``. In particular, ``accepted`` means that
+the channel adapter accepted the submission, **not** that an email or
+other message reached its recipient. Pending and in-progress attempts
+are not published as outcome events.
+
+Receiving events securely
+-------------------------
+
+Subscribe to the complete class name, for example:
+
+``OCA\Libresign\Events\SigningRequestCompletedEvent``
+
+Webhook Listeners sends the event through Nextcloud's JSON wrapper.
+The receiver must authenticate each request, associate ``requestUuid``
+with a workflow it is authorized to handle and deduplicate by
+``eventId``. Individual signer events expose a numeric ``signerId``
+and ``documentUuid`` for correlation, but not invitation links or
+bearer-style signing tokens.
+
+Webhooks contain neither the signed PDF nor credentials granting access
+to it. Retrieve and validate signed documents separately using an
+authorized LibreSign/Nextcloud account. Configure working Cron jobs to
+process asynchronous deliveries.
+
+See :doc:`configuration` for subscriptions and receiver authentication,
+:doc:`signing_completion` for a complete event body, and
+:doc:`external-signing-flow` for the signing and PDF-retrieval workflow.
+
+``occ webhook_listeners:list`` lists **registered subscriptions** on a
+Nextcloud installation; it is not a complete catalog of event classes.
diff --git a/developer_manual/webhooks/external-signing-flow.rst b/developer_manual/webhooks/external-signing-flow.rst
new file mode 100644
index 00000000..b2e9208b
--- /dev/null
+++ b/developer_manual/webhooks/external-signing-flow.rst
@@ -0,0 +1,231 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: CC-BY-3.0
+
+=======================================
+External signing with native webhooks
+=======================================
+
+This guide follows an **existing external application** that keeps its own
+interface and authentication. It creates a LibreSign signing request for
+a person **without a Nextcloud account**, controls the invitation, receives
+a signed-workflow event, then retrieves the final PDF with authorization.
+
+.. important::
+
+   Webhook Listeners delivers **JSON event metadata**, not the signed PDF.
+   Configure an authenticated receiver in Nextcloud. Retrieve documents
+   separately using credentials authorized for the signing request.
+
+1. Prepare the Nextcloud environment
+------------------------------------
+
+Enable Webhook Listeners and configure Nextcloud's **Cron** background
+jobs. Ensure the server can reach the receiver over HTTPS and can deliver
+e-mail.
+
+As in Nextcloud's official documentation, these ``occ`` examples specify
+subcommands without an installation-specific wrapper:
+
+.. code-block:: console
+
+   occ app:enable webhook_listeners
+   occ background:cron
+
+Use the Nextcloud CLI appropriate to your installation and privileges, as
+explained in :doc:`configuration`. Selecting Cron mode does **not** schedule
+``cron.php``: configure an actual scheduler and confirm that background jobs
+run, following the Nextcloud guidance linked there.
+
+For testing, use an SMTP capture server such as Mailpit. Use a dedicated
+Nextcloud integration account with an App Password and only the permissions
+needed to create requests and access its own PDFs.
+
+2. Register the native completion event
+---------------------------------------
+
+An authorized **Nextcloud administrator** registers a webhook subscription
+using Webhook Listeners' own OCS API, not LibreSign's signing API.
+
+.. code-block:: bash
+
+   export NC_URL="https://cloud.example.test"
+   export NC_ADMIN="nextcloud-admin"
+   export NC_ADMIN_APP_PASSWORD="<from-secret-manager>"
+   export RECEIVER_URL="https://integrator.example.test/webhooks/libresign"
+   export RECEIVER_SECRET="<random-per-receiver-secret>"
+
+   curl --fail-with-body -sS \
+     -u "$NC_ADMIN:$NC_ADMIN_APP_PASSWORD" \
+     -H "OCS-APIRequest: true" \
+     -H "Accept: application/json" \
+     --data-urlencode "httpMethod=POST" \
+     --data-urlencode "uri=$RECEIVER_URL" \
+     --data-urlencode 'event=OCA\Libresign\Events\SigningRequestCompletedEvent' \
+     --data-urlencode "authMethod=header" \
+     --data-urlencode "authData[X-LibreSign-Webhook-Token]=$RECEIVER_SECRET" \
+     "$NC_URL/ocs/v2.php/apps/webhook_listeners/api/v1/webhooks"
+
+Inspect both HTTP status and ``ocs.meta.statuscode``. The receiver must
+reject requests without the expected secret. Leave ``userIdFilter`` unset
+for external signers, because the incoming wrapper's ``user`` can be null.
+Exact administrative fields and authentication modes depend on the installed
+Nextcloud Webhook Listeners version; see :doc:`configuration`.
+
+3. Create the request without an initial invitation
+---------------------------------------------------
+
+Authenticate as the **integration requester**, not the signer. Prepare a
+base64-encoded PDF and replace the sample ``<BASE64_PDF_BYTES>`` value.
+The signer's e-mail is an identity method, not a Nextcloud username.
+
+.. code-block:: bash
+
+   export NC_USER="integration-account"
+   export NC_APP_PASSWORD="<from-secret-manager>"
+   export API="$NC_URL/ocs/v2.php/apps/libresign/api/v1"
+
+   curl --fail-with-body -sS \
+     -u "$NC_USER:$NC_APP_PASSWORD" \
+     -H "OCS-APIRequest: true" \
+     -H "Content-Type: application/json" \
+     -H "Accept: application/json" \
+     -d '{
+       "name": "External contract",
+       "file": {"name": "contract.pdf", "base64": "<BASE64_PDF_BYTES>"},
+       "status": 1,
+       "signers": [{
+         "displayName": "External signer",
+         "notify": 0,
+         "identifyMethods": [{
+           "method": "email",
+           "value": "signer@example.test",
+           "requirement": "required"
+         }]
+       }]
+     }' \
+     "$API/request-signature"
+
+Capture the returned file ``id`` and workflow ``uuid``. Confirm the
+request is ``Able to sign`` (status 1) before inviting anyone.
+With ``notify: 0``, LibreSign does not send the initial invitation.
+Verify the absence of an invitation in the test mail transport.
+
+4. Send the invitation explicitly
+---------------------------------
+
+Send it using LibreSign's authenticated endpoint:
+
+.. code-block:: bash
+
+   export FILE_ID="123"  # replace with the returned request ID
+
+   curl --fail-with-body -sS \
+     -u "$NC_USER:$NC_APP_PASSWORD" \
+     -H "OCS-APIRequest: true" \
+     -H "Content-Type: application/json" \
+     -d '{"fileId":123,"signers":[{"email":"signer@example.test"}]}' \
+     "$API/notify/signers"
+
+Replace the example numeric ID in the JSON. This endpoint lets **LibreSign**
+send the signer's invitation; it does not provide a contract for extracting
+or constructing a secret signing URL. Verify that the explicit request
+produced the intended invitation without duplication. An HTTP success
+response is not proof of delivery to the recipient.
+
+5. Sign without a Nextcloud session
+-----------------------------------
+
+Open the invitation URL in a fresh browser profile **without Nextcloud
+authentication**. Complete the signing method permitted by the configured
+policy, such as ``clickToSign``. Email-token signing may require a
+separate verification e-mail; the authentication policy determines the steps.
+
+For multiple signers, the first signature may leave the document
+``Partially signed``. That state is **not** a completion event. For an
+envelope, wait for the parent envelope workflow to complete, not merely
+one child PDF.
+
+6. Receive, authenticate and correlate the event
+------------------------------------------------
+
+Nextcloud queues a ``WebhookCall`` background job. Cron performs an
+asynchronous HTTP POST; the event is **not delivered synchronously** by
+the signing endpoint. The receiver verifies the configured header, parses
+the JSON body, and checks:
+
+- ``event.class`` equals
+  ``OCA\Libresign\Events\SigningRequestCompletedEvent``.
+- ``event.contractVersion`` equals ``1``.
+- ``event.status`` equals ``completed``.
+- ``event.requestUuid`` maps to a request controlled by this integrator.
+- ``event.eventId`` has not already been processed successfully.
+
+For the JSON shape, including ``requestType`` (``document`` or
+``envelope``) and an optional null ``user``, see
+:doc:`signing_completion`. Persist the event ID and return a 2xx when
+accepted. Do not expect exactly-once delivery, guaranteed ordering, or
+automatic retries; run periodic, bounded reconciliation independently.
+
+7. Recover and validate the signed document
+-------------------------------------------
+
+The event does not contain the PDF or authorize its download.
+Using the **requesting account's** credentials, reconcile the current
+state and determine the actual authorized file path:
+
+.. code-block:: bash
+
+   curl --fail-with-body -sS \
+     -u "$NC_USER:$NC_APP_PASSWORD" \
+     -H "OCS-APIRequest: true" \
+     -H "Accept: application/json" \
+     "$API/file/list?details=1&fileIds%5B%5D=$FILE_ID"
+
+Check the intended entry's ``status``, ``uuid`` and file/envelope
+membership. Resolve the final signed file through the authorized account's
+file listing. **Never derive a WebDAV path from the webhook UUID.**
+
+.. code-block:: bash
+
+   export SIGNED_DAV_URL="https://cloud.example.test/remote.php/dav/files/integration-account/Contracts/contract.signed.pdf"
+
+   curl --fail-with-body -sS \
+     -u "$NC_USER:$NC_APP_PASSWORD" \
+     -o signed-contract.pdf "$SIGNED_DAV_URL"
+
+   pdfsig signed-contract.pdf
+
+The path above is **illustrative**; use the actual authorized path in
+your installation. Check the PDF signature's cryptographic validity,
+coverage and trust chain separately. Verify that anonymous callers and
+other authenticated users **cannot** retrieve the document. Do not
+assume that the same HTTP denial status is used by every installation.
+
+8. Handle envelopes and non-completion states
+---------------------------------------------
+
+An envelope may remain in Draft after ``POST /request-signature``,
+even when status 1 was requested. Read the returned state before
+notifying. Where authorized, use ``PATCH /request-signature`` with
+the envelope ``uuid`` and ``status: 1`` to make it ready for signing.
+The completion event for an envelope has ``requestType: "envelope"``.
+
+When rejection policy ``cancel`` ends the workflow in Canceled
+(status 6), it does **not** emit a completion event. Subscribe to
+``SigningRequestCanceledEvent`` to handle workflow cancellation and
+``SignerRejectedWebhookEvent`` to handle individual rejections.
+Reconcile the authoritative state with authenticated API requests.
+
+Integration verification checklist
+----------------------------------
+
+1. Register the native event subscription in Nextcloud and secure the
+   receiver using the authentication mechanism supported by your installation.
+2. Create a request with an external email signer and ``notify: 0``; confirm
+   that no invitation is sent before calling ``/notify/signers``.
+3. Complete signing in a browser without a Nextcloud session. Verify
+   the authenticated HTTP POST from Nextcloud's background-job worker.
+4. Match the event's ``requestUuid`` to a request owned by the integrator,
+   deduplicate using ``eventId`` and reconcile the current workflow state.
+5. Recover and validate the signed PDF using an authorized Nextcloud account.
+   Confirm that unrelated and unauthenticated callers cannot download it.
diff --git a/developer_manual/webhooks/index.rst b/developer_manual/webhooks/index.rst
new file mode 100644
index 00000000..177a4131
--- /dev/null
+++ b/developer_manual/webhooks/index.rst
@@ -0,0 +1,23 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: CC-BY-3.0
+
+========
+Webhooks
+========
+
+Webhooks allow an external system to react to LibreSign events without
+replacing its own interface or repeatedly querying LibreSign. Native event
+delivery is provided by Nextcloud's **Webhook Listeners** app. The
+:doc:`event-catalog` describes supported classes, their triggers and
+payload fields.
+
+Webhook Listeners delivers JSON event metadata to a receiver configured in
+Nextcloud. Retrieve signed PDFs separately with authorized credentials.
+
+.. toctree::
+   :maxdepth: 1
+
+   event-catalog
+   configuration
+   signing_completion
+   external-signing-flow
diff --git a/developer_manual/webhooks/signing_completion.rst b/developer_manual/webhooks/signing_completion.rst
new file mode 100644
index 00000000..0b56fc9b
--- /dev/null
+++ b/developer_manual/webhooks/signing_completion.rst
@@ -0,0 +1,61 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: CC-BY-3.0
+
+==============================
+Signing workflow completed
+==============================
+
+**Event:** ``OCA\Libresign\Events\SigningRequestCompletedEvent``
+
+When it is emitted
+------------------
+
+This event indicates that the signing **workflow** for a document or envelope
+has reached LibreSign's completed status. It is not emitted for an individual
+signer completing one step while the overall request is still partially
+signed. An envelope completes when its overall signing workflow reaches the
+completed state, rather than when an individual file is signed.
+
+Completion is not evidence that every invited participant signed: policy may
+allow a workflow to finish after a signer rejects. Inspect the final workflow
+and evidence using the authenticated LibreSign API when that distinction
+matters to your system.
+
+Received body
+-------------
+
+After registering the event as described in :doc:`configuration`, the receiver
+gets Nextcloud's event wrapper. This is a synthetic example; ``user`` can be
+``null`` when no Nextcloud user session is active.
+
+.. code-block:: json
+
+   {
+     "event": {
+       "class": "OCA\\Libresign\\Events\\SigningRequestCompletedEvent",
+       "contractVersion": 1,
+       "eventId": "libresign.workflow.completed.v1:4ce5a91a-3f2c-4cf0-b4a3-8baad19ac82f",
+       "requestUuid": "4ce5a91a-3f2c-4cf0-b4a3-8baad19ac82f",
+       "requestType": "envelope",
+       "status": "completed"
+     },
+     "user": null,
+     "time": 1794170000
+   }
+
+``requestUuid`` identifies the whole signing request, not an individual
+signer's invitation UUID. ``requestType`` is ``document`` or ``envelope``.
+``contractVersion`` is the version of this event's data contract, not a
+LibreSign release number. ``eventId`` is a stable correlation/deduplication
+key for this request, not a unique identifier of each HTTP delivery attempt.
+
+Use the same ``eventId`` to avoid repeated processing of duplicate deliveries.
+If a completed workflow is later reopened, check its current status before
+acting on a new notification with the same identifier.
+
+The event delivers metadata only; it does not contain a signed PDF or grant
+file-download permissions. The LibreSign event data does not contain signer
+email addresses, private file URLs, document contents or credentials.
+Nextcloud may include information about the current user in its outer
+``user`` field. Retrieve signed documents and evidence separately using
+authenticated, authorized LibreSign and Nextcloud file operations.
diff --git a/style_guide.rst b/style_guide.rst
index 7c5e8da8..3f324e6f 100644
--- a/style_guide.rst
+++ b/style_guide.rst
@@ -17,10 +17,14 @@ When you are writing your text, make it as literal and specific as possible. Put
 yourself in the place of the person who is using LibreSign and looking for 
 instructions on performing a task. Don't make them guess, but spell 
 out every step in order, and tell exactly what buttons to click or what form 
-fields to fill out. Give complete information; for example, when making an OCC
-configuration change, specify the exact command to run, with the exact
-parameters, and the exact user to run it as. When you are describing 
-features of a GUI administration form use the exact literal names of buttons, 
+fields to fill out. Give complete information; for example, specify the
+exact Nextcloud ``occ`` subcommand and parameters for an administration task.
+Do not assume a ``sudo`` wrapper, operating-system user, PHP path or container
+name in a generic procedure. Instead, link to Nextcloud's
+`occ administration guide <https://docs.nextcloud.com/server/stable/admin_manual/occ_command.html>`_
+for the invocation appropriate to the reader's installation. Only describe a
+concrete wrapper when the page targets that specific deployment. When
+describing GUI administration forms, use the exact literal names of buttons,
 form fields, and menus in English. Specify if menus are dropdown, right-click, 
 left-click, or mouseover.
 
@@ -94,14 +98,14 @@ This is how they render:
    
 Use double-backticks for inline code and command examples::
   
-  ``sudo -E -u www-data php occ libresign:configure:check --help``
-  ``libresign:uninstall --jsignpdf``
+  ``occ app:enable webhook_listeners``
+  ``occ webhook_listeners:list``
   
 This is how they render:
 
-``sudo -E -u www-data php occ libresign:configure:check --help``
+``occ app:enable webhook_listeners``
 
-``libresign:uninstall --jsignpdf``
+``occ webhook_listeners:list``
 
 When you are giving hyperlinks as examples, use double-backticks rather than 
 creating a live hyperlink::

From 142113190cb50a1d9294fd2e7c011c9801faa8d8 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Tue, 10 Nov 2026 15:01:53 +0000
Subject: [PATCH 2/5] refactor(docs): source stable manuals from signed release
 branches

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../api/_external-email-signers-release.inc   |  49 ------
 .../api/_external-email-signers-release.inc   |  49 ------
 .../api/_external-email-signers-release.inc   |  50 ------
 versioned/16/developer_manual/index.rst       |  16 --
 .../integration/_native-webhooks.inc          |  12 --
 .../webhooks/configuration.rst                |  78 ---------
 .../16/developer_manual/webhooks/index.rst    |  31 ----
 .../webhooks/signing_completion.rst           |  63 -------
 versioned/base/admin_manual/configuration.rst |  36 ----
 versioned/base/admin_manual/index.rst         |  28 ----
 versioned/base/admin_manual/installation.rst  |  41 -----
 versioned/base/admin_manual/maintenance.rst   |  37 -----
 versioned/base/admin_manual/security.rst      |  38 -----
 .../api/_external-email-signers-release.inc   |   5 -
 .../api/external-email-signers.rst            | 143 ----------------
 versioned/base/developer_manual/api/index.rst |  11 --
 versioned/base/developer_manual/index.rst     |  33 ----
 .../integration/_native-webhooks.inc          |   7 -
 versioned/base/main/index.rst                 |  19 ---
 versioned/base/main/lifecycle.rst             |  34 ----
 versioned/base/user_manual/faq.rst            |  39 -----
 versioned/base/user_manual/functionality.rst  |  77 ---------
 versioned/base/user_manual/index.rst          |  28 ----
 versioned/base/user_manual/start.rst          |  39 -----
 versioned/base/user_manual/support.rst        |  19 ---
 versioned/shared.json                         |   3 -
 versioning/build.py                           |  67 +++-----
 versioning/external_contract.py               |  93 ++++++-----
 {versioned => versioning}/legacy-routes.json  |   0
 versioning/pr_preview.py                      | 156 ++++--------------
 versioning/seo.py                             |   2 +-
 versioning/sources.py                         |  67 ++++++++
 versioning/verify.py                          |   4 +
 33 files changed, 183 insertions(+), 1191 deletions(-)
 delete mode 100644 versioned/13/developer_manual/api/_external-email-signers-release.inc
 delete mode 100644 versioned/14/developer_manual/api/_external-email-signers-release.inc
 delete mode 100644 versioned/15/developer_manual/api/_external-email-signers-release.inc
 delete mode 100644 versioned/16/developer_manual/index.rst
 delete mode 100644 versioned/16/developer_manual/integration/_native-webhooks.inc
 delete mode 100644 versioned/16/developer_manual/webhooks/configuration.rst
 delete mode 100644 versioned/16/developer_manual/webhooks/index.rst
 delete mode 100644 versioned/16/developer_manual/webhooks/signing_completion.rst
 delete mode 100644 versioned/base/admin_manual/configuration.rst
 delete mode 100644 versioned/base/admin_manual/index.rst
 delete mode 100644 versioned/base/admin_manual/installation.rst
 delete mode 100644 versioned/base/admin_manual/maintenance.rst
 delete mode 100644 versioned/base/admin_manual/security.rst
 delete mode 100644 versioned/base/developer_manual/api/_external-email-signers-release.inc
 delete mode 100644 versioned/base/developer_manual/api/external-email-signers.rst
 delete mode 100644 versioned/base/developer_manual/api/index.rst
 delete mode 100644 versioned/base/developer_manual/index.rst
 delete mode 100644 versioned/base/developer_manual/integration/_native-webhooks.inc
 delete mode 100644 versioned/base/main/index.rst
 delete mode 100644 versioned/base/main/lifecycle.rst
 delete mode 100644 versioned/base/user_manual/faq.rst
 delete mode 100644 versioned/base/user_manual/functionality.rst
 delete mode 100644 versioned/base/user_manual/index.rst
 delete mode 100644 versioned/base/user_manual/start.rst
 delete mode 100644 versioned/base/user_manual/support.rst
 delete mode 100644 versioned/shared.json
 rename {versioned => versioning}/legacy-routes.json (100%)
 create mode 100644 versioning/sources.py

diff --git a/versioned/13/developer_manual/api/_external-email-signers-release.inc b/versioned/13/developer_manual/api/_external-email-signers-release.inc
deleted file mode 100644
index 1d0f7c7e..00000000
--- a/versioned/13/developer_manual/api/_external-email-signers-release.inc
+++ /dev/null
@@ -1,49 +0,0 @@
-**Release:** LibreSign |LibreSignRelease|, Nextcloud |NextcloudRelease|.
-**Executable request template:** ``request-13.json``.
-This template is specific to the published application contract.
-
-.. code-block:: json
-
-   {
-     "name": "Synthetic service agreement",
-     "status": 1,
-     "file": {
-       "name": "synthetic.pdf",
-       "base64": "REPLACE_WITH_BASE64"
-     },
-     "signers": [
-       {
-         "displayName": "External Test Signer",
-         "notify": 0,
-         "identifyMethods": [
-           {
-             "method": "email",
-             "value": "signer@example.test",
-             "mandatory": 1
-           }
-         ]
-       }
-     ]
-   }
-
-Select the documentation line before running either client:
-
-.. code-block:: bash
-
-   export LIBRESIGN_DOC_LINE=13
-
-This release requires the integer ``mandatory`` on an email identify method;
-``requirement`` is not part of this release's declared identity schema.
-Its ``POST /request-signature`` accepts ``signatureFlow`` with values
-``parallel`` and ``ordered_numeric``. Supply signer ``signingOrder`` when
-the configured flow is ordered.
-
-The cited browser tests belong to application branch ``stable33``;
-the exact source commit used in this build is in the linked provenance:
-
-* `Guest signing and visible signature <https://github.com/LibreSign/libresign/blob/stable33/playwright/e2e/sign-envelope-unauthenticated-visible-signature.spec.ts>`_
-* `Unauthenticated email-token signing <https://github.com/LibreSign/libresign/blob/stable33/playwright/e2e/sign-email-token-unauthenticated.spec.ts>`_
-* `Sequential signing <https://github.com/LibreSign/libresign/blob/stable33/playwright/e2e/multi-signer-sequential.spec.ts>`_
-
-**Evidence limit:** source tests are present; their existence does not
-prove that SMTP, browser behavior or PDF signing passed in this deployment.
diff --git a/versioned/14/developer_manual/api/_external-email-signers-release.inc b/versioned/14/developer_manual/api/_external-email-signers-release.inc
deleted file mode 100644
index 5ba6a306..00000000
--- a/versioned/14/developer_manual/api/_external-email-signers-release.inc
+++ /dev/null
@@ -1,49 +0,0 @@
-**Release:** LibreSign |LibreSignRelease|, Nextcloud |NextcloudRelease|.
-**Executable request template:** ``request-14.json``.
-This template is specific to the published application contract.
-
-.. code-block:: json
-
-   {
-     "name": "Synthetic service agreement",
-     "status": 1,
-     "file": {
-       "name": "synthetic.pdf",
-       "base64": "REPLACE_WITH_BASE64"
-     },
-     "signers": [
-       {
-         "displayName": "External Test Signer",
-         "notify": 0,
-         "identifyMethods": [
-           {
-             "method": "email",
-             "value": "signer@example.test",
-             "mandatory": 1
-           }
-         ]
-       }
-     ]
-   }
-
-Select the documentation line before running either client:
-
-.. code-block:: bash
-
-   export LIBRESIGN_DOC_LINE=14
-
-This release requires the integer ``mandatory`` on an email identify method;
-``requirement`` is not part of this release's declared identity schema.
-Its ``POST /request-signature`` accepts ``signatureFlow`` with values
-``parallel`` and ``ordered_numeric``. Supply signer ``signingOrder`` when
-the configured flow is ordered.
-
-The cited browser tests belong to application branch ``stable34``;
-the exact source commit used in this build is in the linked provenance:
-
-* `Guest signing and visible signature <https://github.com/LibreSign/libresign/blob/stable34/playwright/e2e/sign-envelope-unauthenticated-visible-signature.spec.ts>`_
-* `Unauthenticated email-token signing <https://github.com/LibreSign/libresign/blob/stable34/playwright/e2e/sign-email-token-unauthenticated.spec.ts>`_
-* `Sequential signing <https://github.com/LibreSign/libresign/blob/stable34/playwright/e2e/multi-signer-sequential.spec.ts>`_
-
-**Evidence limit:** source tests are present; their existence does not
-prove that SMTP, browser behavior or PDF signing passed in this deployment.
diff --git a/versioned/15/developer_manual/api/_external-email-signers-release.inc b/versioned/15/developer_manual/api/_external-email-signers-release.inc
deleted file mode 100644
index badf0041..00000000
--- a/versioned/15/developer_manual/api/_external-email-signers-release.inc
+++ /dev/null
@@ -1,50 +0,0 @@
-**Release:** LibreSign |LibreSignRelease|, Nextcloud |NextcloudRelease|.
-**Executable request template:** ``request-15.json``.
-This template is specific to the published application contract.
-
-.. code-block:: json
-
-   {
-     "name": "Synthetic service agreement",
-     "status": 1,
-     "file": {
-       "name": "synthetic.pdf",
-       "base64": "REPLACE_WITH_BASE64"
-     },
-     "signers": [
-       {
-         "displayName": "External Test Signer",
-         "notify": 0,
-         "identifyMethods": [
-           {
-             "method": "email",
-             "value": "signer@example.test",
-             "requirement": "required"
-           }
-         ]
-       }
-     ]
-   }
-
-Select the documentation line before running either client:
-
-.. code-block:: bash
-
-   export LIBRESIGN_DOC_LINE=15
-
-This release requires ``requirement: "required"`` on an email identify
-method, not the old integer ``mandatory``. Its ``POST /request-signature``
-does **not** declare ``signatureFlow``: do not send that request field.
-Use verified effective server policies and inspect the returned flow.
-The signer schema also declares ``geolocationRequired``; do not
-assume this option is available in earlier releases.
-
-The cited browser tests belong to application branch ``stable35``;
-the exact source commit used in this build is in the linked provenance:
-
-* `Guest signing and visible signature <https://github.com/LibreSign/libresign/blob/stable35/playwright/e2e/sign-envelope-unauthenticated-visible-signature.spec.ts>`_
-* `Unauthenticated email-token signing <https://github.com/LibreSign/libresign/blob/stable35/playwright/e2e/sign-email-token-unauthenticated.spec.ts>`_
-* `Sequential signing <https://github.com/LibreSign/libresign/blob/stable35/playwright/e2e/multi-signer-sequential.spec.ts>`_
-
-**Evidence limit:** source tests are present; their existence does not
-prove that SMTP, browser behavior or PDF signing passed in this deployment.
diff --git a/versioned/16/developer_manual/index.rst b/versioned/16/developer_manual/index.rst
deleted file mode 100644
index df530929..00000000
--- a/versioned/16/developer_manual/index.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-Developer manual — LibreSign |LibreSignRelease|
-===============================================
-
-This is the **release-specific API contract** for LibreSign
-|LibreSignRelease| and Nextcloud |NextcloudRelease|.
-
-The schema is pinned to an application commit on the corresponding stable
-branch. API calls and payloads available only in the development branch
-are not presented as features of this release.
-
-.. toctree::
-   :maxdepth: 2
-
-   api/index
-   integration/index
-   webhooks/index
diff --git a/versioned/16/developer_manual/integration/_native-webhooks.inc b/versioned/16/developer_manual/integration/_native-webhooks.inc
deleted file mode 100644
index 513cd68d..00000000
--- a/versioned/16/developer_manual/integration/_native-webhooks.inc
+++ /dev/null
@@ -1,12 +0,0 @@
-.. note::
-
-   **LibreSign 16 on Nextcloud 36:** Subscribe only to the public
-   ``OCA\Libresign\Events\SigningRequestCompletedEvent`` when the installed
-   application includes it. It implements ``IWebhookCompatibleEvent``
-   and exposes contract version 1 with ``eventId``, ``requestUuid``,
-   ``requestType`` and ``status``. It represents an aggregate transition
-   to ``SIGNED``, not an individual signer action. See the
-   :doc:`../webhooks/configuration` and
-   :doc:`../webhooks/signing_completion` guides for registration,
-   payloads and delivery constraints. Verify actual worker HTTP delivery
-   before replacing polling or claiming end-to-end acceptance.
diff --git a/versioned/16/developer_manual/webhooks/configuration.rst b/versioned/16/developer_manual/webhooks/configuration.rst
deleted file mode 100644
index 15430d63..00000000
--- a/versioned/16/developer_manual/webhooks/configuration.rst
+++ /dev/null
@@ -1,78 +0,0 @@
-.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
-.. SPDX-License-Identifier: CC-BY-3.0
-
-============================
-Configure webhook deliveries
-============================
-
-Native LibreSign webhooks use Nextcloud's **Webhook Listeners** application.
-A Nextcloud administrator registers a receiving HTTPS endpoint and selects
-which event class should trigger it. A separate receiver application can keep
-its own authentication and user interface.
-
-Prerequisites
--------------
-
-- LibreSign must include the event you want to subscribe to. See the event
-  reference pages for availability and payloads.
-- Enable **Webhook Listeners** in Nextcloud. On an installation where the
-  web-server account is ``www-data``, an administrator can run:
-
-  .. code-block:: console
-
-     sudo -u www-data php occ app:enable webhook_listeners
-
-- Configure Nextcloud background jobs in **Cron** mode and allow the server to
-  reach the receiver over HTTPS.
-- Provide a receiver that accepts JSON requests, authenticates the sender,
-  and can process duplicate messages safely.
-
-Register a listener
--------------------
-
-Use Nextcloud's Webhook Listeners administration API, not LibreSign's signing
-API, to create the subscription:
-
-.. code-block:: text
-
-   POST /ocs/v2.php/apps/webhook_listeners/api/v1/webhooks
-
-Authenticate as an administrator authorized to manage Webhook Listeners, using
-an App Password where supported and the ``OCS-APIRequest: true`` header.
-The registration fields include:
-
-- ``httpMethod``: use ``POST``.
-- ``uri``: HTTPS URL of the receiver; do not include credentials in the URL.
-- ``event``: the fully qualified event name shown on its reference page.
-- ``eventFilter``: omit or use an empty filter to accept every occurrence, or
-  define a filter supported by your Nextcloud version.
-- ``userIdFilter``: leave unset for events initiated by external signers or
-  background jobs, where no Nextcloud user may be in the current session.
-- ``headers``, ``authMethod`` and ``authData``: configure the authentication
-  mechanism supported by your installed Webhook Listeners version. Use a
-  dedicated receiver credential and keep it outside source control.
-
-For the complete request schema, permission rules and available authentication
-modes, consult your installed Nextcloud Webhook Listeners API documentation.
-Each release of Nextcloud controls these administrative fields independently.
-
-Delivery and recovery
----------------------
-
-Webhook Listeners schedules HTTP delivery through Nextcloud background jobs.
-A successful signing operation does not mean the HTTP request has already
-reached the receiver. Return a ``2xx`` response when an event is accepted and
-store an event-specific idempotency key when the event provides one.
-
-Do not assume exactly-once delivery, guaranteed ordering or automatic retry
-of failed HTTP requests. Inspect the Nextcloud log and the receiver log when
-notifications are missing. Reconcile the current workflow using authenticated
-LibreSign API operations and the permissions of the integrating account.
-Never use a webhook payload as authorization to download a signed file.
-
-Event availability
-------------------
-
-Event pages describe the version and precise workflow condition for each
-subscription. Do not assume that an event documented for the development
-line exists on an older installed LibreSign version.
diff --git a/versioned/16/developer_manual/webhooks/index.rst b/versioned/16/developer_manual/webhooks/index.rst
deleted file mode 100644
index 9935fba9..00000000
--- a/versioned/16/developer_manual/webhooks/index.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
-.. SPDX-License-Identifier: CC-BY-3.0
-
-========
-Webhooks
-========
-
-Webhooks allow an external system to react to LibreSign events without
-replacing its own interface or repeatedly querying LibreSign. Native event
-delivery is provided by Nextcloud's **Webhook Listeners** app. Each supported
-event has its own reference page, including the point in the workflow that
-triggers delivery and the data sent to the receiver.
-
-**Availability:** LibreSign 16 with Nextcloud 36. These native LibreSign
-events are **not available in LibreSign 13, 14 or 15**. The exact application
-release and source revision are shown in :doc:`../api/openapi`. Nextcloud's
-Webhook Listeners app must be enabled and the installed LibreSign release must
-include the relevant event.
-
-Native webhooks and the existing LibreSign per-request callback are separate
-mechanisms. An integration may receive notifications through both transports.
-
-.. toctree::
-   :maxdepth: 1
-
-   configuration
-   signing_completion
-
-The existing LibreSign callback continues to work independently. When an
-integration enables both mechanisms, it must handle notifications from each
-without assuming they have identical delivery formats or timing.
diff --git a/versioned/16/developer_manual/webhooks/signing_completion.rst b/versioned/16/developer_manual/webhooks/signing_completion.rst
deleted file mode 100644
index e6c6e0f1..00000000
--- a/versioned/16/developer_manual/webhooks/signing_completion.rst
+++ /dev/null
@@ -1,63 +0,0 @@
-.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
-.. SPDX-License-Identifier: CC-BY-3.0
-
-==============================
-Signing workflow completed
-==============================
-
-**Event:** ``OCA\Libresign\Events\SigningRequestCompletedEvent``
-
-**Available from:** LibreSign 16 on Nextcloud 36. This event is not available
-in LibreSign 13, 14 or 15. Verify that your installed LibreSign build includes
-the event before registering a listener.
-
-When it is emitted
-------------------
-
-This event indicates that the signing **workflow** for a document or envelope
-has reached LibreSign's completed status. It is not emitted for an individual
-signer completing one step while the overall request is still partially
-signed. An envelope completes when its overall signing workflow reaches the
-completed state, rather than when an individual file is signed.
-
-Completion is not evidence that every invited participant signed: policy may
-allow a workflow to finish after a signer rejects. Inspect the final workflow
-and evidence using the authenticated LibreSign API when that distinction
-matters to your system.
-
-Received body
--------------
-
-After registering the event as described in :doc:`configuration`, the receiver
-gets Nextcloud's event wrapper. This is a synthetic example; ``user`` can be
-``null`` when no Nextcloud user session is active.
-
-.. code-block:: json
-
-   {
-     "event": {
-       "class": "OCA\\Libresign\\Events\\SigningRequestCompletedEvent",
-       "contractVersion": 1,
-       "eventId": "libresign.workflow.completed.v1:4ce5a91a-3f2c-4cf0-b4a3-8baad19ac82f",
-       "requestUuid": "4ce5a91a-3f2c-4cf0-b4a3-8baad19ac82f",
-       "requestType": "envelope",
-       "status": "completed"
-     },
-     "user": null,
-     "time": 1794170000
-   }
-
-``requestUuid`` identifies the whole signing request, not an individual
-signer's invitation UUID. ``requestType`` is ``document`` or ``envelope``.
-``contractVersion`` is the version of this event's data contract, not a
-LibreSign release number. ``eventId`` is a stable correlation/deduplication
-key for this request, not a unique identifier of each HTTP delivery attempt.
-
-Use the same ``eventId`` to avoid repeated processing of duplicate deliveries.
-If a completed workflow is later reopened, check its current status before
-acting on a new notification with the same identifier.
-
-The LibreSign event data does not contain signer email addresses, private file
-URLs, document contents or credentials. Nextcloud may include information about
-the current user in its outer ``user`` field. Retrieve any signed document or
-evidence separately, using an authenticated and authorized LibreSign API call.
diff --git a/versioned/base/admin_manual/configuration.rst b/versioned/base/admin_manual/configuration.rst
deleted file mode 100644
index 8efd4376..00000000
--- a/versioned/base/admin_manual/configuration.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-Configure signing
-=================
-
-Open **Administration settings** in Nextcloud and find LibreSign. Configuration
-is server-owned: users should not be asked to change a system-wide signing
-policy to complete a single request.
-
-Signing and identity
---------------------
-
-Review the available signature engine and signing methods before enabling
-external signers. The user's available choices can depend on permissions,
-identity methods, and policy settings. Test the configured invitation method
-with a non-production request before relying on it.
-
-The administrative layout changes across supported releases. In LibreSign 13
-and 14, several settings appear as individual controls; LibreSign 15 includes
-the Policy Workbench for applicable configuration. Consult the visible
-controls in your installed version rather than looking for an identically
-named control in every release.
-
-Certificates and dependencies
------------------------------
-
-- Review **Certificate engine** and **Root certificate data** and the chosen
-  trust model before issuing signatures.
-- Use **Configuration check** and the **Dependencies** section to diagnose
-  an incomplete installation.
-- Record the selected certificate policy and secure storage location as part
-  of your deployment's operational documentation.
-
-Changing a trust anchor or regenerating a root certificate is not routine
-configuration. See :doc:`security` and :doc:`maintenance` first.
-
-For integration and version-pinned API payloads, use the
-`developer API reference <../developer_manual/api/index.html>`_.
diff --git a/versioned/base/admin_manual/index.rst b/versioned/base/admin_manual/index.rst
deleted file mode 100644
index fbaa7911..00000000
--- a/versioned/base/admin_manual/index.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-Administrator manual — LibreSign |LibreSignRelease|
-===================================================
-
-This manual covers LibreSign |LibreSignRelease| for Nextcloud
-|NextcloudRelease|. Check the matching app release before changing server
-settings or restoring data. Procedures are limited to the stable versions
-listed in the documentation version selector.
-
-Choose an operation
--------------------
-
-- :doc:`installation` — install LibreSign and complete initial setup.
-- :doc:`configuration` — find the signing and certificate configuration.
-- :doc:`maintenance` — back up, upgrade, and troubleshoot an installation.
-- :doc:`security` — protect signing credentials and review security choices.
-
-For the signing experience, see the `user manual
-<../user_manual/index.html>`_; for API authentication and integration,
-consult the `developer manual <../developer_manual/index.html>`_.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Operations
-
-   installation
-   configuration
-   maintenance
-   security
diff --git a/versioned/base/admin_manual/installation.rst b/versioned/base/admin_manual/installation.rst
deleted file mode 100644
index a37932d2..00000000
--- a/versioned/base/admin_manual/installation.rst
+++ /dev/null
@@ -1,41 +0,0 @@
-Install and initialize LibreSign
-================================
-
-Prerequisites
--------------
-
-Use a supported Nextcloud instance and the matching LibreSign release. The
-application declares compatibility in its ``appinfo/info.xml``; this site's
-release selector distinguishes LibreSign versions from Nextcloud versions.
-Use an administrator account and plan for adequate disk space and network
-access if the application must download signing dependencies.
-
-Install the app
----------------
-
-#. Open Nextcloud's **Apps** administration page.
-#. Search for **LibreSign** and install or enable the release offered for
-   your compatible Nextcloud version.
-#. Open the LibreSign administration settings and inspect **Configuration
-   check** for resources requiring attention.
-#. In **Dependencies**, use **Download binaries** if prompted, then
-   **Validate setup** to check the installation. The operation can take time
-   and requires server resources.
-#. Configure the certificate engine and the **Root certificate data**
-   appropriate to your organization. For the OpenSSL engine, the root
-   certificate form asks for a **Common Name (CN)** and allows generating a
-   root certificate when the installation requires it.
-#. Resolve remaining configuration errors before sending real invitations.
-
-The location and presentation of some settings differ between LibreSign
-releases; see :doc:`configuration`. Do not regenerate an existing production
-root certificate merely to repeat initial setup.
-
-Check the installation
-----------------------
-
-Open LibreSign with a permitted user account. In a test environment, create
-a request, complete its supported signing method, and open **Validate
-signature** on the result. A successful installation check is not equivalent
-to verifying mail delivery, external identity providers, or production
-certificate policy; exercise those separately when enabled.
diff --git a/versioned/base/admin_manual/maintenance.rst b/versioned/base/admin_manual/maintenance.rst
deleted file mode 100644
index ca2b3e9d..00000000
--- a/versioned/base/admin_manual/maintenance.rst
+++ /dev/null
@@ -1,37 +0,0 @@
-Maintain an installation
-========================
-
-Before upgrading
-----------------
-
-#. Confirm the target LibreSign release is compatible with the installed
-   Nextcloud version; do not assume matching numbers refer to the same product.
-#. Record the current application and Nextcloud versions, configuration,
-   certificate engine, and enabled signing or identification methods.
-#. Back up the Nextcloud database, configuration, related files, and the
-   certificate material and signing keys required by your deployment.
-   Protect these backups according to their sensitivity.
-#. Follow Nextcloud's supported application upgrade procedure and consult
-   the `LibreSign releases <https://github.com/LibreSign/libresign/releases>`_
-   for changes relevant to your target version.
-#. Check **Configuration check** after the upgrade; perform a test signing
-   and validate its resulting PDF before resuming production activity.
-
-Backups must be recoverable: verify recovery on an isolated system, including
-access to the certificate material necessary for previously signed documents.
-Do not expose private keys in tickets, logs, or example configurations.
-
-Troubleshooting
----------------
-
-- **Cannot request a signature:** check the user's permissions and the
-  allowed identification methods in :doc:`configuration`.
-- **Setup is incomplete:** inspect **Configuration check** and
-  **Dependencies**, and check Nextcloud's application logs.
-- **An invitation was not received:** verify the request status and the
-  configured delivery channel; inspect the mail system only if email delivery
-  is configured. Avoid resending invitations blindly.
-- **Validation fails:** inspect the reported certificate or PDF error, and
-  confirm that the signing environment's trust material is still available.
-
-Do not regenerate the root certificate as a generic troubleshooting step.
diff --git a/versioned/base/admin_manual/security.rst b/versioned/base/admin_manual/security.rst
deleted file mode 100644
index c52e6fba..00000000
--- a/versioned/base/admin_manual/security.rst
+++ /dev/null
@@ -1,38 +0,0 @@
-Security and trust
-==================
-
-Protect signing credentials
----------------------------
-
-Restrict administrator access to certificate configuration and any signing
-keys. Protect backups and limit access to credentials; do not copy private
-keys into public reports or screenshots. Keep Nextcloud, LibreSign, and the
-underlying TLS configuration maintained.
-
-Certificate lifecycle
----------------------
-
-LibreSign's **Root certificate data** interface provides a root certificate
-configuration. The OpenSSL engine explicitly warns that **Regenerate root
-certificate** invalidates existing signing keys. Treat regeneration as a
-planned key lifecycle or recovery operation, not as ordinary maintenance.
-Prepare and test a recovery and validation plan before changing a trust
-anchor used by existing documents.
-
-Signers and access
-------------------
-
-Review which accounts may create requests and which identification methods
-are available to external signers. A signing invitation is sensitive: avoid
-publishing the link or including it in a public issue. Test the separation
-between request owner, intended signer, and unrelated users when configuring
-external access.
-
-Validation and compliance
--------------------------
-
-Provide recipients with a way to validate signed PDFs. Technical signature
-validation and certificate status do not by themselves prove legal compliance
-in every jurisdiction or that a signer's identity was established to a
-particular assurance level. Document applicable organizational rules
-separately from the application's cryptographic capabilities.
diff --git a/versioned/base/developer_manual/api/_external-email-signers-release.inc b/versioned/base/developer_manual/api/_external-email-signers-release.inc
deleted file mode 100644
index e8517c41..00000000
--- a/versioned/base/developer_manual/api/_external-email-signers-release.inc
+++ /dev/null
@@ -1,5 +0,0 @@
-.. warning::
-
-   This release does not yet have a reviewed request template. Do not
-   copy another release's identify-method fields. Publication CI must
-   reject a version that lacks a matching fixture and contract evidence.
diff --git a/versioned/base/developer_manual/api/external-email-signers.rst b/versioned/base/developer_manual/api/external-email-signers.rst
deleted file mode 100644
index c763afc4..00000000
--- a/versioned/base/developer_manual/api/external-email-signers.rst
+++ /dev/null
@@ -1,143 +0,0 @@
-External email signers: integration
-===================================
-
-**Applicable release:** LibreSign |LibreSignRelease| on Nextcloud |NextcloudRelease|.
-The exact source commit and contract hash are published as
-`pinned OpenAPI provenance <openapi.provenance.json>`_.
-The path /api/v1 is the API protocol version, not the LibreSign major version.
-
-An existing system may retain its own interface and authentication while
-its backend creates LibreSign signature requests. An external signer may
-sign in LibreSign without a Nextcloud account.
-
-Authentication and identity are separate
-----------------------------------------
-
-The integrator uses a dedicated Nextcloud account authorized to request
-signatures, over HTTPS. HTTP Basic with a revocable Nextcloud App Password
-and the OCS-APIRequest: true header is supported. OpenAPI also declares
-bearer authentication, but external OAuth/OIDC tokens only work if the
-deployed Nextcloud server validates them for a mapped, permitted account.
-SSO may create a Nextcloud browser session; it is not automatically an
-OCS service credential. Never send integrator credentials to the signer.
-
-External signers are identified by email. Enable the email identify
-method and an allowed signing method (clickToSign or emailToken) in the
-effective LibreSign policies. The latter uses a separate emailed code.
-Receipt of an invitation is not strong legal identity verification.
-Administrators also must configure mail delivery, a signing certificate
-engine, writable storage, requester permissions, validation privacy,
-and any mandatory identity-document or visible signature policies.
-
-Create and invite with OCS v1
------------------------------
-
-All four documented release lines use this OCS prefix:
-
-.. code-block:: text
-
-   https://cloud.example.com/ocs/v2.php/apps/libresign/api/v1
-
-The request structure is selected for this documentation release. Use only
-the version-specific fixture below with the executable cURL or PHP clients
-in ``examples/external-email-signers``. The version selector is mandatory.
-
-.. include:: _external-email-signers-release.inc
-
-The scripts POST /request-signature,
-verify ocs.meta and retain ocs.data.id (LibreSign file ID) and
-ocs.data.uuid (document UUID). notify: 0 disables initial auto-invites;
-the scripts explicitly POST /notify/signers with the returned file ID:
-
-.. code-block:: json
-
-   {"fileId": 123, "signers": [{"email": "signer@example.test"}]}
-
-A processed notification request is not proof of email delivery.
-Do not send duplicate invitations. Use an actual test inbox.
-
-.. code-block:: bash
-
-   export NC_BASE_URL=https://cloud.example.com
-   export NC_USER=integration-user
-   export PDF_PATH=./synthetic.pdf
-   export SIGNER_EMAIL=signer@controlled-mailbox.example
-   # cURL: use a private netrc file (mode 0600) with App Password
-   export NC_NETRC="$HOME/.config/libresign-integration.netrc"
-   ./flow.sh start
-   # PHP: obtain the App Password from private environment
-   export NC_APP_PASSWORD=provided-by-secret-manager
-   php flow.php start
-
-The signer receives an individual invitation link, opens the public
-signing browser page and completes the configured identification and
-signature checks without Nextcloud login. A file UUID differs from the
-signer's sign-request UUID; never generate or disclose a genuine link.
-
-Poll, validate and retrieve
----------------------------
-
-Use the integrator identity to GET /file/list?details=1; find the
-saved file UUID in the paginated ocs.data.data array. Common statuses:
-0 draft; 1 ready; 2 partially signed; 3 signed; 4 deleted. Check all
-required signers and envelope children before marking completion.
-
-.. code-block:: bash
-
-   export FILE_UUID=UUID_RETURNED_BY_START
-   ./flow.sh check
-   php flow.php check
-
-GET /file/validate/file_id/{fileId} enforces file access and returns
-available validation data. Public /file/validate/uuid/{uuid} is
-restricted by the private-validation policy, not unrestricted evidence
-access. Validation output is not a guaranteed standalone audit dossier.
-
-.. code-block:: bash
-
-   export FILE_ID=ID_RETURNED_BY_START
-   ./flow.sh validate
-   php flow.php validate
-
-The OCS specification has no generic binary GET /file/download/{id}.
-The public LibreSign PDF viewer is governed by validation privacy, not
-a general backend download authorization. Discover the actual signed
-file path in the integrator's readable Nextcloud Files folder, using
-authenticated WebDAV PROPFIND if necessary. Then use WebDAV GET:
-
-.. code-block:: text
-
-   /remote.php/dav/files/<integration-user>/<encoded-signed-PDF-path>
-
-Neither a LibreSign file ID, nodeId, signedNodeId nor sign-request UUID
-is a WebDAV path. Both scripts support retrieve with SIGNED_DAV_URL
-and SIGNED_OUTPUT set to a private output path. Verify the downloaded
-PDF signature and certificate chain independently. Do not bypass file
-permissions or query LibreSign database tables directly.
-
-Ordering, release differences, errors and security
---------------------------------------------------
-
-Use separate signers[] records and signingOrder when ordered signing
-is configured. Sequential recipients are activated in order; parallel
-signers can act independently. files[] can create envelopes when enabled.
-The specific supported request options for this LibreSign release are
-documented above. Do not copy parameters from other major versions.
-
-Typical errors: 401 authentication; 403 file permission; 404 missing
-or inaccessible resource; 412 missing OCS header where enforced; 422
-validation or policy violation (inspect ocs.data.message/errors).
-Main notifications also document 500/502 for failed/unconfirmed
-transport; older contracts differ. POST is not generally idempotent:
-check for existing workflows before retrying after a timeout.
-
-Protect invitation links, App Passwords, signer metadata and PDFs.
-Poll with backoff; native webhooks require a separately verified
-LibreSign event contract for the deployed Nextcloud version.
-
-The release-specific section links to browser-test sources from that
-application branch. Their presence is source evidence; running them
-against the installed release is still necessary to establish E2E behavior.
-Contract checks cannot prove SMTP, browser signing or certificate trust.
-
-Consult the OpenAPI reference beside this page for exact schemas.
diff --git a/versioned/base/developer_manual/api/index.rst b/versioned/base/developer_manual/api/index.rst
deleted file mode 100644
index fec60d4f..00000000
--- a/versioned/base/developer_manual/api/index.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-API reference
-=============
-
-The schema below is built from the exact ``openapi.json`` in this
-release's application source revision, not from ``main``.
-
-.. toctree::
-   :maxdepth: 2
-
-   external-email-signers
-   openapi
diff --git a/versioned/base/developer_manual/index.rst b/versioned/base/developer_manual/index.rst
deleted file mode 100644
index 29cec956..00000000
--- a/versioned/base/developer_manual/index.rst
+++ /dev/null
@@ -1,33 +0,0 @@
-Developer manual — LibreSign |LibreSignRelease|
-===============================================
-
-This is the **release-specific API contract** for LibreSign
-|LibreSignRelease| and Nextcloud |NextcloudRelease|. The schema is pinned
-to an application commit on the corresponding stable branch. Development-only
-API calls and payloads are not presented as features of this release.
-
-Integrate an external application
----------------------------------
-
-- :doc:`integration/index` — choose an integration architecture for an
-  existing application.
-- :doc:`api/external-email-signers` — follow a release-specific API example
-  for inviting an external email signer.
-- :doc:`api/openapi` — inspect the OpenAPI schema pinned to this release.
-
-Contribute or develop LibreSign
--------------------------------
-
-Source architecture, coding standards, development environment, tests, and
-release engineering follow the project's current development branch. They
-are available in the `development and contributor manual
-<../../main/developer_manual/index.html>`_. That manual may describe
-unreleased functionality. For integrating with LibreSign |LibreSignRelease|,
-continue to use the version-specific reference above.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Release-specific integration
-
-   api/index
-   integration/index
diff --git a/versioned/base/developer_manual/integration/_native-webhooks.inc b/versioned/base/developer_manual/integration/_native-webhooks.inc
deleted file mode 100644
index 9e7bd5a8..00000000
--- a/versioned/base/developer_manual/integration/_native-webhooks.inc
+++ /dev/null
@@ -1,7 +0,0 @@
-.. note::
-
-   **LibreSign 13–15:** These release lines do not publish the native
-   aggregate LibreSign signing-completion event for Webhook Listeners.
-   Use authenticated polling with reconciliation instead. Nextcloud's
-   Webhook Listeners installation alone does not make an arbitrary internal
-   LibreSign event available over HTTP.
diff --git a/versioned/base/main/index.rst b/versioned/base/main/index.rst
deleted file mode 100644
index 8229221d..00000000
--- a/versioned/base/main/index.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-LibreSign |LibreSignRelease| documentation
-==========================================
-
-This is the documentation for **LibreSign |LibreSignRelease|** on
-**Nextcloud |NextcloudRelease|**. API contracts, compatibility and source
-revisions are specific to this LibreSign release line.
-
-Choose the manual for your task:
-
-* `User manual <user_manual/>`_
-* `Administrator manual <admin_manual/>`_
-* `Developer and OpenAPI manual <developer_manual/>`_
-
-`Browse all versions and manuals <../>`_
-
-.. toctree::
-   :maxdepth: 1
-
-   lifecycle
diff --git a/versioned/base/main/lifecycle.rst b/versioned/base/main/lifecycle.rst
deleted file mode 100644
index 32488d39..00000000
--- a/versioned/base/main/lifecycle.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-Release lifecycle and extended support
-======================================
-
-LibreSign versions are identified by the application's **major version**.
-Each published documentation path, such as ``/13/``, corresponds to the
-matching stable application branch and its compatible Nextcloud release.
-The OpenAPI artifact published with each line comes from the exact application
-commit identified on the API page.
-
-``/main/`` is a development snapshot and must not be treated as a stable
-release contract. A version selector distinguishes the current stable release
-line, earlier lines, and explicitly designated end-of-support (EOL) lines.
-
-**The existence of a stable branch or archived documentation does not guarantee
-maintenance, security fixes, or a commercial support commitment.** There is no
-implicit EOL date. When project maintainers announce end of support, the
-lifecycle metadata must be updated so the version selector marks that line EOL.
-
-Organizations requiring assistance beyond a release's community maintenance
-window may seek a separately negotiated extended-support arrangement.
-Availability, scope, duration, pricing, and service levels are not promised
-by the public project documentation.
-
-The canonical release history is in
-`LibreSign/libresign <https://github.com/LibreSign/libresign/releases>`_;
-this documentation intentionally does not mirror its changelogs.
-
-Updating versions
------------------
-
-Release and backport documentation is generated from the actual stable branch,
-including ``appinfo/info.xml`` and ``openapi.json``. See the
-`documentation repository <https://github.com/LibreSign/documentation>`_
-for the repeatable build and publication process.
diff --git a/versioned/base/user_manual/faq.rst b/versioned/base/user_manual/faq.rst
deleted file mode 100644
index 35eb4eab..00000000
--- a/versioned/base/user_manual/faq.rst
+++ /dev/null
@@ -1,39 +0,0 @@
-Frequently asked questions
-==========================
-
-Do I need a Nextcloud account to sign?
---------------------------------------
-
-Not always. A requester can invite an external email signer without creating
-an account when the administrator enables that identification method. Creating
-signature requests from the Nextcloud interface does require appropriate
-permissions. See :doc:`start`.
-
-Must I upload my own digital certificate?
------------------------------------------
-
-That depends on the signing method required for the request and the server's
-certificate configuration. If a personal certificate is required, LibreSign
-will prompt for it. A drawn or typed appearance is not the same thing as the
-cryptographic signature embedded in a signed PDF.
-
-How do I know whether everyone has signed?
-------------------------------------------
-
-Check the request details and each signer's progress in :ref:`see_signed_file`.
-One completed signer does not prove a multi-signer document is finished.
-
-Does validation prove a signature is legally valid everywhere?
---------------------------------------------------------------
-
-No. :ref:`validate_document` checks technical evidence. Applicable laws,
-identity-assurance requirements, retention duties, and acceptance by a
-recipient depend on the context and jurisdiction. LibreSign is not a blanket
-GDPR/LGPD or legal-compliance certification.
-
-What if my invitation does not work?
-------------------------------------
-
-Check that you opened the intended invitation, then ask the requester to
-verify its status, recipient, and configured identification method. Do not
-send your password or signing credential to support staff. See :doc:`support`.
diff --git a/versioned/base/user_manual/functionality.rst b/versioned/base/user_manual/functionality.rst
deleted file mode 100644
index daa819b0..00000000
--- a/versioned/base/user_manual/functionality.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-Documents, signatures, and validation
-=====================================
-
-.. _main_screen:
-
-Find your documents
--------------------
-
-Open **LibreSign** in Nextcloud and choose **Files** to see documents and
-signature requests available to you. Select a file to inspect its details
-and signers. An individual signer can be **pending** or **signed**; do not
-assume the entire request is complete merely because one person has signed.
-
-.. _add_signature:
-
-Request signatures
-------------------
-
-#. Choose **Request Signatures**. Use **Upload** for a PDF on your device,
-   **Choose from Files** for an existing Nextcloud file, or **Upload from
-   URL** if your administrator allows it.
-#. Review the selected file before asking another person to sign.
-#. Use **Search signer** to select a recipient or an allowed identification
-   method, including an external email recipient where enabled.
-#. Check the signer's name and identification details and select **Save**.
-   Repeat for every required signer.
-#. Configure the remaining signing steps shown by LibreSign and submit the
-   request. Do not consider a draft a delivered invitation.
-#. Open the request details in **Files** to see who is still pending.
-
-Available signer identification methods, permissions, delivery channels, and
-signing order depend on the administrator's configuration. Use the options
-shown for your request rather than assuming every channel is enabled.
-
-.. _sign_invitation:
-
-Sign an invitation
-------------------
-
-#. Open the link supplied to you for the signing request; verify its sender
-   before entering any personal information.
-#. Read the PDF and check that you are the intended signer.
-#. Complete any requested identification step. If LibreSign asks for a
-   certificate or signature password, follow the instructions for your
-   configured signing method.
-#. Choose **Sign** or **Sign document** and confirm the operation.
-#. Check for the completion message. If other signers remain, the request
-   may still be in progress.
-
-If the link is expired, rejected, or requires a method you cannot use,
-contact the requester. Do not reuse someone else's invitation.
-
-.. _see_signed_file:
-
-Follow signing progress
------------------------
-
-Open the document details in **Files** and check the signer list. A signer
-marked **pending** has not completed their part; **signed** records a completed
-part. The document's overall completion depends on all required signatures
-and the configured workflow. Download the final PDF when it becomes available.
-
-.. _validate_document:
-
-Validate a signature
---------------------
-
-#. Open LibreSign's **Validate signature** page.
-#. Choose **Upload** to select a PDF, drag and drop a PDF onto the page, or
-   choose **From UUID** if you have the document identifier.
-#. Run **Validation** and review the results, including certificate and
-   signing information shown by the application.
-#. Investigate any reported error instead of treating a visual stamp or QR
-   code as conclusive proof of validity.
-
-Validation evaluates the available cryptographic and certificate evidence.
-It does not, by itself, determine every legal requirement in your jurisdiction.
diff --git a/versioned/base/user_manual/index.rst b/versioned/base/user_manual/index.rst
deleted file mode 100644
index 832c5bae..00000000
--- a/versioned/base/user_manual/index.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-User manual — LibreSign |LibreSignRelease|
-==========================================
-
-Use this manual for LibreSign |LibreSignRelease| on Nextcloud
-|NextcloudRelease|. It covers the signing and validation workflows available
-in this release, rather than features under development in ``main``.
-
-Choose a task
--------------
-
-- :doc:`start` — find the correct entry point for requesting or signing.
-- :doc:`functionality` — prepare a document, invite signers, follow progress,
-  sign a request, or validate a PDF.
-- :doc:`faq` — understand account, certificate, and legal considerations.
-- :doc:`support` — troubleshoot a problem and find support channels.
-
-For installation and server configuration, use the
-`administrator manual <../admin_manual/index.html>`_. Integrations belong in
-the `developer manual <../developer_manual/index.html>`_.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Tasks
-
-   start
-   functionality
-   faq
-   support
diff --git a/versioned/base/user_manual/start.rst b/versioned/base/user_manual/start.rst
deleted file mode 100644
index 40f58281..00000000
--- a/versioned/base/user_manual/start.rst
+++ /dev/null
@@ -1,39 +0,0 @@
-Getting started
-===============
-
-Choose the path that matches your role. An administrator must install and
-configure LibreSign before users can request signatures.
-
-I want to request signatures
-----------------------------
-
-#. Sign in to the Nextcloud instance where LibreSign is enabled.
-#. Open **LibreSign** and find **Request Signatures** or the request action
-   in the **Files** screen.
-#. Select a PDF using **Upload**, **Choose from Files**, or **Upload from URL**
-   when those options are available to your account.
-#. Follow :ref:`add_signature` to add recipients and send the request.
-
-If the request controls are missing, ask your administrator whether your
-account is permitted to create requests.
-
-I received a signing invitation
--------------------------------
-
-#. Open the invitation link from the requester and check the document and
-   requested identity details before proceeding.
-#. Follow the on-screen signing steps. Depending on the configured signing
-   method, LibreSign may ask you to define a signature, provide a password,
-   upload a certificate, or complete identity verification.
-#. Review the confirmation before submitting. See :ref:`sign_invitation`.
-
-External email signers can use the invitation workflow without a Nextcloud
-account when that identification method is enabled by the administrator.
-Do not forward a personal invitation link to another person.
-
-I want to verify a signed document
-----------------------------------
-
-Use :ref:`validate_document` to check a signed PDF or a document UUID. The
-validation result must be reviewed; an image of a handwritten signature is not
-by itself evidence of a valid digital signature.
diff --git a/versioned/base/user_manual/support.rst b/versioned/base/user_manual/support.rst
deleted file mode 100644
index e7171667..00000000
--- a/versioned/base/user_manual/support.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-Help and support
-================
-
-If a signing request or validation fails, first note the action you were
-trying to perform and the exact error message, without copying private
-identification data or document contents into a public report.
-
-- For an invitation, an expired request, or a wrong recipient, contact the
-  person who requested the signature.
-- For missing permissions, signing methods, or server configuration, contact
-  your Nextcloud administrator.
-- For a reproducible LibreSign defect, consult the
-  `LibreSign issue tracker <https://github.com/LibreSign/libresign/issues>`_.
-- For project information and professional support options, see
-  `libresign.coop <https://libresign.coop/>`_.
-
-Include your LibreSign and Nextcloud version numbers in technical reports.
-Never publish signature passwords, private certificates, invitation links,
-or documents containing personal data.
diff --git a/versioned/shared.json b/versioned/shared.json
deleted file mode 100644
index 0aa25822..00000000
--- a/versioned/shared.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
-  "developer_manual": ["integration"]
-}
diff --git a/versioning/build.py b/versioning/build.py
index f9c40b0d..22375dea 100644
--- a/versioning/build.py
+++ b/versioning/build.py
@@ -17,64 +17,30 @@
 from jinja2 import Environment, FileSystemLoader, select_autoescape
 
 from versioning.catalog import discover, get_version, load_policy
+from versioning.sources import branch_sources
 
 ROOT = Path(__file__).resolve().parent.parent
 MANUALS = ("main", "user_manual", "admin_manual", "developer_manual")
 
 
-def shared_sources(manual: str) -> list[tuple[Path, Path]]:
-    """Read declarative shared sections; never assume development-only pages are stable."""
-    config = json.loads((ROOT / "versioned/shared.json").read_text(encoding="utf-8"))
-    sections = config.get(manual, [])
-    if not isinstance(sections, list):
-        raise ValueError(f"Shared sections must be a list: {manual}")
-    root = (ROOT / manual).resolve()
-    result = []
-    for name in sections:
-        if not isinstance(name, str) or not name or name.startswith("/"):
-            raise ValueError(f"Invalid shared section: {name!r}")
-        relative = Path(name)
-        if (relative == Path(".") or "//" in name or
-                any(part in ("..", ".") for part in relative.parts) or "\\" in name):
-            raise ValueError(f"Unsafe shared section: {name!r}")
-        source = (root / relative).resolve()
-        if not source.is_relative_to(root) or not source.is_dir():
-            raise ValueError(f"Missing or outside shared section: {name!r}")
-        result.append((relative, source))
-    return result
-
-
 def source_tree(stage: Path, slug: str, manual: str) -> Path:
+    """Stage one manual from the checked-out documentation release branch."""
+    repository = branch_sources(stage, slug, repository=ROOT)
     target = stage / slug / manual
-    if slug == "main":
-        shutil.copytree(ROOT / manual, target)
-    else:
-        target.mkdir(parents=True, exist_ok=True)
-        # Stable base documentation takes precedence over shared sections.
-        for relative, source in shared_sources(manual):
-            shutil.copytree(source, target / relative, dirs_exist_ok=True)
-        shutil.copytree(ROOT / "versioned/base" / manual, target, dirs_exist_ok=True)
-        overlay = ROOT / "versioned" / slug / manual
-        if overlay.exists():
-            shutil.copytree(overlay, target, dirs_exist_ok=True)
-        if manual == "developer_manual":
-            shutil.copytree(ROOT / "developer_manual/html", target / "html")
-            (target / "api").mkdir(parents=True, exist_ok=True)
-            shutil.copy2(ROOT / "developer_manual/api/openapi.rst",
-                         target / "api/openapi.rst")
-        # Keep these manuals independent of main while retaining the shared
-        # Sphinx config and shared (version-neutral) Swagger UI assets.
+    shutil.copytree(repository / manual, target)
+    if slug != "main":
+        # Sphinx renders temporary sources; GitHub edit links must still point
+        # at the real file in the stableNN branch, not at a staging directory.
         config = (
             "import os, sys\n"
             "from pathlib import Path\n"
             "root = Path(os.environ['LIBRESIGN_DOC_ROOT'])\n"
             "sys.path.insert(0, str(root))\n"
             "from conf import *\n"
-            "html_context = {**html_context, 'conf_py_path': '/versioned/base/"
-            + manual + "/'}\n"
-            "html_logo = str(root / 'images/logo.png' if "
-            "(root / 'images/logo.png').is_file() else "
-            "root / 'main/images/logo.png')\n"
+            "html_context = {**html_context, "
+            f"'github_version': 'stable{slug}', "
+            f"'conf_py_path': '/{manual}/'" + "}\n"
+            "html_logo = str(root / 'images/logo.png')\n"
             "html_extra_path = [str(root / 'developer_manual/html')] "
             "if os.environ.get('LIBRESIGN_DOC_MANUAL') == 'developer_manual' "
             "else []\n"
@@ -196,6 +162,16 @@ def build(output: Path, selected: str = "all") -> dict:
         stage = Path(tmp)
         for slug in targets:
             entry = get_version(catalog, slug)
+            source = branch_sources(stage, slug, repository=ROOT)
+            if slug == "main":
+                entry["documentation_commit"] = subprocess.check_output(
+                    ["git", "-C", str(ROOT), "rev-parse", "HEAD"],
+                    text=True, timeout=20,
+                ).strip()
+            else:
+                entry["documentation_commit"] = (
+                    source / ".source-commit"
+                ).read_text().strip()
             for manual in MANUALS:
                 source = source_tree(stage, slug, manual)
                 run_sphinx(source, output / slug / ("" if manual == "main" else manual), entry, catalog)
@@ -205,6 +181,7 @@ def build(output: Path, selected: str = "all") -> dict:
             provenance = {
                 "slug": slug, "branch": entry["branch"], "app_commit": entry["app_commit"],
                 "app_version": entry["app_version"],
+                "documentation_commit": entry["documentation_commit"],
                 "source_url": entry["source_url"],
                 "openapi_sha256": entry["openapi_sha256"],
                 "manifest_sha256": entry["manifest_sha256"],
diff --git a/versioning/external_contract.py b/versioning/external_contract.py
index 7ba20ee8..eaf120c5 100644
--- a/versioning/external_contract.py
+++ b/versioning/external_contract.py
@@ -6,10 +6,12 @@
 from __future__ import annotations
 
 import json
+import tempfile
 from pathlib import Path
 from typing import Any, Callable
 
 from versioning.catalog import fetch_source
+from versioning.sources import branch_sources
 
 PREFIX = "/ocs/v2.php/apps/libresign/api/{apiVersion}"
 REQUIRED_OPERATIONS = {
@@ -208,44 +210,55 @@ def validate_site_external_samples(
     """
     catalog = json.loads((site / "versions.json").read_text())
     verified = []
-    for entry in catalog["versions"]:
-        slug = entry["slug"]
-        fixture_file = repository / FIXTURE_FOLDER / f"request-{slug}.json"
-        partial_file = repository / (
-            Path("developer_manual/api") if slug == "main"
-            else Path("versioned") / slug / "developer_manual/api"
-        ) / PARTIAL_NAME
-        if not fixture_file.is_file() or not partial_file.is_file():
-            raise ValueError(f"{slug}: missing reviewed fixture or release-specific guide")
-        spec_file = site / slug / "developer_manual/api/openapi.json"
-        spec = json.loads(spec_file.read_text())
-        fixture = json.loads(fixture_file.read_text())
-        identity_field = validate_external_sample(spec, fixture)
-        partial = partial_file.read_text()
-        if f"request-{slug}.json" not in partial or f"LIBRESIGN_DOC_LINE={slug}" not in partial:
-            raise ValueError(f"{slug}: documentation does not select its own fixture")
-        if entry["branch"] not in partial:
-            raise ValueError(f"{slug}: wrong stable-branch evidence link")
-        documented = extract_rst_json(partial)
-        if documented != fixture:
-            raise ValueError(f"{slug}: shown JSON differs from executable fixture")
-        if identity_field not in partial:
-            raise ValueError(f"{slug}: identify-method contract not described")
-        request_fields = request_schema(operation(spec, "post", "/request-signature"))["properties"]
-        if "signatureFlow" in request_fields:
-            if "accepts" not in partial or "ordered_numeric" not in partial:
-                raise ValueError(f"{slug}: ordered signing request options not documented")
-        elif "does **not** declare" not in partial:
-            raise ValueError(f"{slug}: undocumented signatureFlow field not ruled out")
-        html_file = site / slug / "developer_manual/api/external-email-signers.html"
-        if not html_file.is_file():
-            raise ValueError(f"{slug}: guide is missing from rendered site")
-        html = html_file.read_text()
-        if entry["app_version"] not in html:
-            raise ValueError(f"{slug}: exact application release missing from page")
-        for path in ("/request-signature", "/notify/signers", "/file/list"):
-            if path not in html:
-                raise ValueError(f"{slug}: operation absent from rendered page: {path}")
-        verify_source_evidence(entry, fetch=fetch)
-        verified.append(slug)
+    with tempfile.TemporaryDirectory(prefix="libresign-doc-contracts-") as tmp:
+        branches = Path(tmp)
+        for entry in catalog["versions"]:
+            slug = entry["slug"]
+            fixture_file = repository / FIXTURE_FOLDER / f"request-{slug}.json"
+            if not fixture_file.is_file():
+                raise ValueError(f"{slug}: missing reviewed fixture")
+            source = branch_sources(
+                branches, slug, repository=repository,
+                expected_commit=entry.get("documentation_commit"),
+            )
+            partial_file = source / "developer_manual/api" / PARTIAL_NAME
+            if not partial_file.is_file():
+                raise ValueError(f"{slug}: missing release-specific guide")
+            _check_release_example(site, entry, fixture_file, partial_file, fetch)
+            verified.append(slug)
     return verified
+
+
+def _check_release_example(site: Path, entry: dict, fixture_file: Path,
+                           partial_file: Path, fetch) -> None:
+    slug = entry["slug"]
+    spec_file = site / slug / "developer_manual/api/openapi.json"
+    spec = json.loads(spec_file.read_text())
+    fixture = json.loads(fixture_file.read_text())
+    identity_field = validate_external_sample(spec, fixture)
+    partial = partial_file.read_text()
+    if f"request-{slug}.json" not in partial or f"LIBRESIGN_DOC_LINE={slug}" not in partial:
+        raise ValueError(f"{slug}: documentation does not select its own fixture")
+    if entry["branch"] not in partial:
+        raise ValueError(f"{slug}: wrong stable-branch evidence link")
+    documented = extract_rst_json(partial)
+    if documented != fixture:
+        raise ValueError(f"{slug}: shown JSON differs from executable fixture")
+    if identity_field not in partial:
+        raise ValueError(f"{slug}: identify-method contract not described")
+    request_fields = request_schema(operation(spec, "post", "/request-signature"))["properties"]
+    if "signatureFlow" in request_fields:
+        if "accepts" not in partial or "ordered_numeric" not in partial:
+            raise ValueError(f"{slug}: ordered signing request options not documented")
+    elif "does **not** declare" not in partial:
+        raise ValueError(f"{slug}: undocumented signatureFlow field not ruled out")
+    html_file = site / slug / "developer_manual/api/external-email-signers.html"
+    if not html_file.is_file():
+        raise ValueError(f"{slug}: guide is missing from rendered site")
+    html = html_file.read_text()
+    if entry["app_version"] not in html:
+        raise ValueError(f"{slug}: exact application release missing from page")
+    for path in ("/request-signature", "/notify/signers", "/file/list"):
+        if path not in html:
+            raise ValueError(f"{slug}: operation absent from rendered page: {path}")
+    verify_source_evidence(entry, fetch=fetch)
diff --git a/versioned/legacy-routes.json b/versioning/legacy-routes.json
similarity index 100%
rename from versioned/legacy-routes.json
rename to versioning/legacy-routes.json
diff --git a/versioning/pr_preview.py b/versioning/pr_preview.py
index 471867e8..54ae63e7 100644
--- a/versioning/pr_preview.py
+++ b/versioning/pr_preview.py
@@ -1,4 +1,4 @@
-"""Publish navigable, isolated previews of not-yet-released documentation.
+"""Publish navigable PR previews from the actual documentation branches.
 
 SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
 SPDX-License-Identifier: CC-BY-3.0
@@ -9,146 +9,62 @@
 import html
 import json
 import re
-import shutil
-import tempfile
 from pathlib import Path
-from urllib.parse import quote
-
-from versioning.build import ROOT, run_sphinx, source_tree
-from versioning.verify import inspect_links
-from versioning.seo import mark_preview_noindex
 
 PREVIEW_MARKER = "<!-- libresign-documentation-preview-links -->"
-REVIEW_MANUALS = ("user_manual", "admin_manual", "developer_manual")
 
 
 def preview_unreleased(site: Path, preview_root: str) -> list[str]:
-    """Render future-release overlays for PR review without publishing a release."""
-    catalog = json.loads((site / "versions.json").read_text(encoding="utf-8"))
-    versions = {entry["slug"]: entry for entry in catalog["versions"]}
-    development = versions["main"]
-    major = development["app_version"].split(".", 1)[0]
-    if not re.fullmatch(r"[1-9][0-9]*", major):
-        raise ValueError(f"Invalid development major: {major!r}")
+    """Link to the real development manual; never invent a future release tree."""
     if not preview_root.startswith("https://"):
         raise ValueError("Preview links must use HTTPS")
+    catalog = json.loads((site / "versions.json").read_text(encoding="utf-8"))
+    main = next(entry for entry in catalog["versions"] if entry["slug"] == "main")
+    major = main["app_version"].split(".", 1)[0]
+    if not re.fullmatch(r"[1-9][0-9]*", major):
+        raise ValueError("Invalid development version")
+    routes = ["/", f"/{catalog['current_stable']}/", "/main/developer_manual/",
+              "/_review/index.html"]
+    for route in routes[:-1]:
+        target = site / route.lstrip("/") / "index.html"
+        if not target.is_file():
+            raise ValueError(f"Missing source for preview route: {route}")
 
     review = site / "_review"
     review.mkdir(exist_ok=True)
-    routes = ["/", f"/{catalog['current_stable']}/",
-              "/main/developer_manual/", "/_review/index.html"]
-    candidates: list[tuple[str, str]] = []
-
-    # An existing stable major is already fully rendered at /<major>/.
-    # Never expose a synthetic stable site in the published version catalog.
-    if major not in versions:
-        overlay_root = ROOT / "versioned" / major
-        for manual in REVIEW_MANUALS:
-            overlay = overlay_root / manual
-            if not overlay.is_dir():
-                continue
-            output = review / major / manual
-            entry = {**development, "slug": major, "status": "development"}
-            with tempfile.TemporaryDirectory(prefix="libresign-pr-review-") as tmp:
-                source = source_tree(Path(tmp), major, manual)
-                run_sphinx(source, output, entry, catalog, review_only=True)
-
-            if manual == "developer_manual":
-                # The preview reads the pinned *development* contract. It is
-                # not a released stable OpenAPI and is never added to /16/.
-                for filename in ("openapi.json", "openapi.provenance.json"):
-                    source = site / "main/developer_manual/api" / filename
-                    if not source.is_file():
-                        raise ValueError(f"Missing development API: {source}")
-                    shutil.copy2(source, output / "api" / filename)
-
-            index = output / "index.html"
-            if not index.is_file():
-                raise ValueError(f"Missing preview index for {manual}")
-            index_route = f"/_review/{major}/{manual}/index.html"
-            routes.append(index_route)
-            candidates.append((f"LibreSign {major} / {manual}", index_route))
-            for rst in sorted(overlay.rglob("*.rst")):
-                relative = rst.relative_to(overlay).with_suffix(".html")
-                page = output / relative
-                if not page.is_file():
-                    raise ValueError(f"Sphinx did not render {rst.relative_to(ROOT)}")
-                route = f"/_review/{major}/{manual}/{relative.as_posix()}"
-                if route != index_route:
-                    candidates.append((f"{major} / {manual} / {relative}", route))
-                    routes.append(route)
-
-            broken = [
-                issue for page in output.rglob("*.html")
-                for issue in inspect_links(site, page)
-            ]
-            if broken:
-                raise ValueError("Broken unreleased-preview links:\n" +
-                                 "\n".join(broken[:20]))
-
-    # The navigation index is review-only; nothing under _review enters
-    # versions.json, the version selector, or production Pages.
-    links = "\n".join(
-        '<li><a href="{}">{}</a></li>'.format(
-            html.escape("../" + route.lstrip("/"), quote=True),
-            html.escape(title),
-        ) for title, route in candidates
+    url = preview_root.rstrip("/")
+    development_url = f"{url}/main/developer_manual/"
+    message = (
+        f"<p>LibreSign {html.escape(major)} is in development. "
+        "Documentation is edited in the main branch, not copied into "
+        "a release-specific overlay.</p>"
     )
-    message = ("Preview-only documentation; built from development application "
-               "metadata and OpenAPI. Not a published stable LibreSign release.")
     (review / "index.html").write_text(
         '<!doctype html><html lang="en"><head><meta charset="utf-8">'
         '<title>Preview-only documentation</title></head><body>'
-        '<main><h1>Preview-only documentation</h1>'
-        f'<p>{html.escape(message)}</p>'
-        '<p><a href="../">Published-version PR preview</a></p>'
-        f'<ul>{links}</ul></main></body></html>',
-        encoding="utf-8",
+        '<main><h1>Preview-only documentation</h1>' + message +
+        '<p><a href="../main/developer_manual/">Development manual</a></p>'
+        '</main></body></html>', encoding="utf-8",
     )
-
-    root_url = preview_root.rstrip("/")
-    comment = [
-        PREVIEW_MARKER,
-        "### Navigable documentation preview",
-        "",
-        f"- [All published documentation versions]({root_url}/)",
-        f"- [Development manual (main)]({root_url}/main/developer_manual/)",
-        f"- [Preview-only release pages]({root_url}/_review/)",
-        "",
-        "The preview is isolated from production. Unreleased pages use the",
-        "development application contract for review, **not** a released",
-        "stable LibreSign version. Sphinx, links and pinned OpenAPI are checked",
-        "in CI; screenshots are not required.",
-        "",
-    ]
-    if candidates:
-        comment.extend(["**Unreleased pages available for review:**", ""])
-        for title, route in candidates:
-            comment.append(f"- [{title}]({root_url}{quote(route, safe='/')})")
-    else:
-        comment.append("No unpublished major-version overlay is present.")
     (review / "preview-comment.md").write_text(
-        "\n".join(comment) + "\n", encoding="utf-8"
-    )
-    # These are the URLs the deployment workflow must verify on the real
-    # preview origin, not just files checked in the checkout.
-    unique_routes = list(dict.fromkeys(routes))
-    for route in unique_routes:
-        local = site / route.lstrip("/")
-        if route.endswith("/"):
-            local /= "index.html"
-        if not local.is_file():
-            raise ValueError(f"Preview route is missing: {route}")
-    mark_preview_noindex(review)
-    (review / "routes.txt").write_text(
-        "\n".join(unique_routes) + "\n", encoding="utf-8"
+        "\n".join([
+            PREVIEW_MARKER,
+            "### Navigable documentation preview",
+            "",
+            f"- [All published versions]({url}/)",
+            f"- [LibreSign {major} development manual]({development_url})",
+            "",
+            "This preview is isolated from production. Documentation for the"
+            " next release lives in the development branch until it is released.",
+            "",
+        ]), encoding="utf-8",
     )
-    return unique_routes
+    (review / "routes.txt").write_text("\n".join(routes) + "\n", encoding="utf-8")
+    return routes
 
 
 def main() -> None:
-    parser = argparse.ArgumentParser(
-        description="Build review-only HTML for unpublished documentation")
+    parser = argparse.ArgumentParser(description="Prepare a preview for documentation")
     parser.add_argument("--site", type=Path, default=Path("_publish"))
     parser.add_argument("--preview-root", required=True)
     args = parser.parse_args()
diff --git a/versioning/seo.py b/versioning/seo.py
index 43b8fd9a..7120afbf 100644
--- a/versioning/seo.py
+++ b/versioning/seo.py
@@ -101,7 +101,7 @@ def apply_seo(site: Path, catalog: dict, *, preview: bool = False) -> None:
 
 def read_legacy_routes(root: Path) -> dict[str, str]:
     """The historic unversioned routes are an immutable migration contract."""
-    routes = json.loads((root / "versioned/legacy-routes.json").read_text(encoding="utf-8"))
+    routes = json.loads((root / "versioning/legacy-routes.json").read_text(encoding="utf-8"))
     if not isinstance(routes, dict) or not routes:
         raise ValueError("Legacy URL mapping must be a nonempty object")
     for old, target in routes.items():
diff --git a/versioning/sources.py b/versioning/sources.py
new file mode 100644
index 00000000..85b11621
--- /dev/null
+++ b/versioning/sources.py
@@ -0,0 +1,67 @@
+"""Read complete documentation sources from their own version branches.
+
+SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+SPDX-License-Identifier: CC-BY-3.0
+"""
+from __future__ import annotations
+
+import io
+import re
+import subprocess
+import tarfile
+from pathlib import Path
+
+REPOSITORY = "https://github.com/LibreSign/documentation.git"
+MANUALS = ("main", "user_manual", "admin_manual", "developer_manual")
+
+
+def branch_sources(stage: Path, slug: str, *, repository: Path,
+                   expected_commit: str | None = None) -> Path:
+    """Pin a documentation branch once, then read all manuals from that SHA.
+
+    No fallback to the development manual is allowed for missing releases.
+    Only documentation trees are extracted; tooling is taken from the build PR.
+    """
+    if slug == "main":
+        return repository
+    if not re.fullmatch(r"[1-9][0-9]*", slug):
+        raise ValueError(f"Invalid LibreSign documentation release: {slug!r}")
+
+    destination = stage / "_branch_sources" / slug
+    if destination.is_dir():
+        return destination
+    branch = f"stable{slug}"
+    try:
+        subprocess.run(
+            ["git", "-C", str(repository), "fetch", "--quiet", "--no-tags",
+             "--depth=1", REPOSITORY, f"refs/heads/{branch}"],
+            check=True, capture_output=True, text=True, timeout=120,
+        )
+        revision = subprocess.check_output(
+            ["git", "-C", str(repository), "rev-parse", "FETCH_HEAD"],
+            text=True, timeout=20,
+        ).strip()
+        if expected_commit is not None and revision != expected_commit:
+            raise ValueError(
+                f"{branch} changed during documentation validation: "
+                f"expected {expected_commit}, fetched {revision}"
+            )
+        data = subprocess.check_output(
+            ["git", "-C", str(repository), "archive", "--format=tar",
+             revision, *MANUALS], timeout=90,
+        )
+    except (OSError, subprocess.CalledProcessError, subprocess.TimeoutExpired) as error:
+        raise ValueError(
+            f"Missing/unavailable documentation branch {branch}; "
+            "publish the release-specific documentation branch before building"
+        ) from error
+
+    destination.mkdir(parents=True, exist_ok=False)
+    with tarfile.open(fileobj=io.BytesIO(data), mode="r:") as archive:
+        archive.extractall(destination, filter="data")
+    for manual in MANUALS:
+        if not (destination / manual / "index.rst").is_file():
+            raise ValueError(f"{branch} has no {manual}/index.rst")
+    (destination / ".source-commit").write_text(revision + "\n")
+    print(f"Documentation {branch} pinned at {revision}")
+    return destination
diff --git a/versioning/verify.py b/versioning/verify.py
index d8dc0239..08b625c5 100644
--- a/versioning/verify.py
+++ b/versioning/verify.py
@@ -108,6 +108,10 @@ def verify_site(output: Path, versions: list[str] | None = None,
                       "nextcloud_min", "nextcloud_max"):
             if entry[field] != provenance[field]:
                 errors.append(f"OpenAPI provenance field differs: {slug}.{field}")
+        # Older, already-published versions may predate documentation SHA
+        # provenance; new builds must keep the source SHA consistent.
+        if entry.get("documentation_commit") != provenance.get("documentation_commit"):
+            errors.append(f"Documentation source SHA mismatch for {slug}")
         if slug != "main" and (provenance["branch"] == "main" or
                                  not provenance["branch"].startswith("stable")):
             errors.append(f"Stable {slug} is displaying a development branch")

From 22f6f107ce6037f42254b2fda90266c638fd477c Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Tue, 10 Nov 2026 15:02:16 +0000
Subject: [PATCH 3/5] test(docs): validate branch isolation and simplify
 preview checks

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .github/workflows/docs.yml           |   6 +-
 tests/test_branch_sources.py         |  46 +++++++++
 tests/test_external_email_signers.py |  11 ---
 tests/test_pr_preview.py             | 140 ++++++---------------------
 tests/test_seo.py                    |   4 +-
 tests/test_shared_sources.py         |  78 ---------------
 6 files changed, 82 insertions(+), 203 deletions(-)
 create mode 100644 tests/test_branch_sources.py
 delete mode 100644 tests/test_shared_sources.py

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index dff5c47b..163adae8 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -11,7 +11,11 @@ on:
       - '.github/workflows/docs.yml'
       - '.github/workflows/deploy.yml'
       - 'versioning/**'
-      - 'versioned/**'
+      - 'AGENTS.md'
+      - 'CONTRIBUTING.md'
+      - 'README.rst'
+      - 'README.md'
+      - 'docs/maintainers/**'
       - 'assets/**'
       - '_templates/**'
       - 'main/**'
diff --git a/tests/test_branch_sources.py b/tests/test_branch_sources.py
new file mode 100644
index 00000000..fa49080c
--- /dev/null
+++ b/tests/test_branch_sources.py
@@ -0,0 +1,46 @@
+"""Test branch isolation at the source-loader boundary, not per-page lists."""
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from versioning import build
+from versioning.sources import branch_sources
+
+
+class BranchSourceTests(unittest.TestCase):
+    def test_release_uses_its_branch_without_inheriting_development_sources(self):
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            latest = root / "dev"
+            stable = root / "stable"
+            for directory, label in ((latest, "Development"), (stable, "Stable")):
+                manual = directory / "developer_manual"
+                manual.mkdir(parents=True)
+                (manual / "index.rst").write_text(label)
+            (latest / "developer_manual/new-feature.rst").write_text("New feature")
+            with patch.object(build, "ROOT", latest), patch.object(
+                build, "branch_sources",
+                side_effect=lambda stage, slug, repository: latest if slug == "main" else stable,
+            ):
+                stage = root / "stage"
+                first = build.source_tree(stage, "main", "developer_manual")
+                second = build.source_tree(stage, "15", "developer_manual")
+            self.assertTrue((first / "new-feature.rst").is_file())
+            self.assertFalse((second / "new-feature.rst").exists())
+            self.assertEqual((second / "index.rst").read_text(), "Stable")
+            self.assertIn("'github_version': 'stable15'", (second / "conf.py").read_text())
+            self.assertIn("'conf_py_path': '/developer_manual/'", (second / "conf.py").read_text())
+
+    def test_missing_documentation_branch_does_not_fall_back_to_main(self):
+        with tempfile.TemporaryDirectory() as temp, patch(
+            "versioning.sources.subprocess.run", side_effect=FileNotFoundError("offline")
+        ):
+            # Errors must say which stable branch is required, not copy main.
+            with self.assertRaisesRegex(ValueError, "stable15"):
+                branch_sources(Path(temp), "15", repository=Path(temp))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_external_email_signers.py b/tests/test_external_email_signers.py
index 3858c918..95e22a2e 100644
--- a/tests/test_external_email_signers.py
+++ b/tests/test_external_email_signers.py
@@ -152,17 +152,6 @@ def test_invalid_notification_or_personal_data_is_rejected(self):
         with self.assertRaisesRegex(ValueError, "synthetic"):
             validate_external_sample(sample_spec("mandatory"), legacy)
 
-    def test_each_rendered_sample_matches_its_executable_fixture(self):
-        for slug in ("13", "14", "15", "main"):
-            with self.subTest(release=slug):
-                directory = (
-                    ROOT / "developer_manual/api" if slug == "main"
-                    else ROOT / "versioned" / slug / "developer_manual/api"
-                )
-                panel = (directory / "_external-email-signers-release.inc").read_text()
-                self.assertEqual(extract_rst_json(panel), fixture(slug))
-                self.assertIn(f"LIBRESIGN_DOC_LINE={slug}", panel)
-
     def test_pinned_source_provenance_is_checked(self):
         entry = {"slug": "13", "app_commit": "a" * 40}
         observed = []
diff --git a/tests/test_pr_preview.py b/tests/test_pr_preview.py
index fff2bc1b..feb90e89 100644
--- a/tests/test_pr_preview.py
+++ b/tests/test_pr_preview.py
@@ -1,135 +1,53 @@
-"""Review-only release previews must be navigable without screenshot tooling."""
+"""Preview links must point to the real development source, not a fake release."""
 
 import json
 import tempfile
 import unittest
 from pathlib import Path
-from unittest.mock import patch
 
-from versioning import pr_preview
-from versioning.sphinx_config import configure
+from versioning.pr_preview import preview_unreleased
 
 
-class UnreleasedPreviewTests(unittest.TestCase):
-    def fixture(self, root: Path, *, released: bool = False) -> tuple[Path, Path]:
+class DevelopmentPreviewTests(unittest.TestCase):
+    @staticmethod
+    def fixture(root: Path) -> Path:
         site = root / "site"
-        site.mkdir()
-        (site / "index.html").write_text("<h1>Docs</h1>")
-        main = site / "main/developer_manual/api"
-        main.mkdir(parents=True)
-        (main / "openapi.json").write_text("{}")
-        (main / "openapi.provenance.json").write_text('{"branch":"main"}')
-        (site / "main/developer_manual/index.html").write_text("Development")
-        (site / "15/index.html").parent.mkdir()
-        (site / "15/index.html").write_text("Stable")
-        catalog = {
+        for path in ("index.html", "15/index.html", "main/developer_manual/index.html"):
+            target = site / path
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text("<html><body>Documentation</body></html>")
+        (site / "versions.json").write_text(json.dumps({
             "current_stable": "15",
             "versions": [
                 {"slug": "15", "status": "current"},
                 {"slug": "main", "status": "development",
-                 "app_version": "16.0.0-dev.1", "app_commit": "a" * 40},
+                 "app_version": "16.0.0-dev.1"},
             ],
-        }
-        if released:
-            catalog["versions"].insert(0, {"slug": "16", "status": "current"})
-            (site / "16/index.html").parent.mkdir()
-            (site / "16/index.html").write_text("Released")
-        (site / "versions.json").write_text(json.dumps(catalog))
-        sources = root / "source"
-        overlay = sources / "versioned/16/developer_manual/webhooks"
-        overlay.mkdir(parents=True)
-        (overlay / "index.rst").write_text("Webhooks")
-        (overlay / "new_event.rst").write_text("New event")
-        return site, sources
-
-    @staticmethod
-    def fake_sphinx(source: Path, output: Path, entry: dict,
-                    catalog: dict, *, review_only: bool = False) -> None:
-        assert review_only
-        output.mkdir(parents=True)
-        (output / "index.html").write_text("<html><head></head><body>Review manual</body></html>")
-        target = output / "webhooks"
-        target.mkdir()
-        (target / "index.html").write_text(
-            '<html><head></head><body><a href="new_event.html">Event</a></body></html>')
-        (target / "new_event.html").write_text("<html><head></head><body>Native event</body></html>")
-        (output / "api").mkdir()
-        (output / "api/openapi.html").write_text("<html><head></head><body>OpenAPI</body></html>")
-
-    def test_future_pages_are_built_and_linked_without_filename_registration(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            site, sources = self.fixture(Path(tmp))
-            with patch.object(pr_preview, "ROOT", sources), \
-                 patch.object(pr_preview, "source_tree", return_value=Path(tmp)), \
-                 patch.object(pr_preview, "run_sphinx", side_effect=self.fake_sphinx):
-                routes = pr_preview.preview_unreleased(site, "https://example.test/pr-7")
-            self.assertIn("/_review/16/developer_manual/webhooks/new_event.html", routes)
-            self.assertEqual((site / "_review/16/developer_manual/api/openapi.json")
-                             .read_text(), "{}")
-            self.assertIn("new_event.html", (site / "_review/preview-comment.md").read_text())
-            self.assertIn("Preview-only documentation", (site / "_review/index.html").read_text())
-            self.assertFalse((site / "16/developer_manual/index.html").exists())
-            self.assertNotIn('"slug": "16"', (site / "versions.json").read_text())
+        }))
+        return site
 
-    def test_invalid_overlay_page_cannot_be_silently_omitted(self):
+    def test_development_preview_uses_single_source(self):
         with tempfile.TemporaryDirectory() as tmp:
-            site, sources = self.fixture(Path(tmp))
-            def incomplete(source, output, entry, catalog, *, review_only=False):
-                self.fake_sphinx(source, output, entry, catalog, review_only=review_only)
-                (output / "webhooks/new_event.html").unlink()
-            with patch.object(pr_preview, "ROOT", sources), \
-                 patch.object(pr_preview, "source_tree", return_value=Path(tmp)), \
-                 patch.object(pr_preview, "run_sphinx", side_effect=incomplete):
-                with self.assertRaisesRegex(ValueError, "did not render"):
-                    pr_preview.preview_unreleased(site, "https://example.test/pr-7")
-
-    def test_broken_links_in_review_are_detected(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            site, sources = self.fixture(Path(tmp))
-            def broken(source, output, entry, catalog, *, review_only=False):
-                self.fake_sphinx(source, output, entry, catalog, review_only=review_only)
-                (output / "webhooks/index.html").write_text(
-                    '<a href="absent.html">Missing</a>')
-            with patch.object(pr_preview, "ROOT", sources), \
-                 patch.object(pr_preview, "source_tree", return_value=Path(tmp)), \
-                 patch.object(pr_preview, "run_sphinx", side_effect=broken):
-                with self.assertRaisesRegex(ValueError, "Broken unreleased-preview links"):
-                    pr_preview.preview_unreleased(site, "https://example.test/pr-7")
-
-    def test_released_major_uses_normal_version_and_no_synthetic_copy(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            site, sources = self.fixture(Path(tmp), released=True)
-            with patch.object(pr_preview, "ROOT", sources), \
-                 patch.object(pr_preview, "run_sphinx") as sphinx:
-                routes = pr_preview.preview_unreleased(site, "https://example.test/pr-7")
-            sphinx.assert_not_called()
-            self.assertNotIn("/_review/16/developer_manual/index.html", routes)
-            self.assertTrue((site / "_review/index.html").is_file())
+            site = self.fixture(Path(tmp))
+            routes = preview_unreleased(site, "https://example.test/pr-130")
+            self.assertIn("/main/developer_manual/", routes)
+            self.assertIn("LibreSign 16", (site / "_review/index.html").read_text())
             self.assertFalse((site / "_review/16").exists())
+            self.assertIn("/main/developer_manual/",
+                          (site / "_review/preview-comment.md").read_text())
 
-    def test_review_404_assets_use_review_path_not_a_fake_stable_url(self):
-        with patch.dict("os.environ", {
-            "LIBRESIGN_DOC_BASE_PATH": "/site-preview/docs-preview/pr-127",
-            "LIBRESIGN_DOC_VERSION": "16",
-            "LIBRESIGN_DOC_MANUAL": "developer_manual",
-            "LIBRESIGN_DOC_REVIEW_PREFIX": "/_review",
-        }):
-            config = {}
-            configure(config)
-        self.assertEqual(
-            config["notfound_urls_prefix"],
-            "/site-preview/docs-preview/pr-127/_review/16/developer_manual/",
-        )
-        self.assertEqual(
-            config["html_context"]["libresign_site_root"],
-            "/site-preview/docs-preview/pr-127",
-        )
+    def test_missing_preview_source_fails(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            site = self.fixture(Path(tmp))
+            (site / "main/developer_manual/index.html").unlink()
+            with self.assertRaisesRegex(ValueError, "Missing source"):
+                preview_unreleased(site, "https://example.test/pr-130")
 
-    def test_reject_non_https_preview_links(self):
+    def test_preview_requires_https(self):
         with tempfile.TemporaryDirectory() as tmp:
-            site, _ = self.fixture(Path(tmp))
+            site = self.fixture(Path(tmp))
             with self.assertRaisesRegex(ValueError, "HTTPS"):
-                pr_preview.preview_unreleased(site, "http://example.test")
+                preview_unreleased(site, "http://example.test")
 
 
 if __name__ == "__main__":
diff --git a/tests/test_seo.py b/tests/test_seo.py
index 6a2ab3b9..7402925a 100644
--- a/tests/test_seo.py
+++ b/tests/test_seo.py
@@ -107,9 +107,9 @@ def test_preview_content_is_not_indexable(self):
 
     def test_unsafe_and_generic_legacy_destinations_are_rejected(self):
         source = self.root / "src"
-        (source / "versioned").mkdir(parents=True)
+        (source / "versioning").mkdir(parents=True)
         for bad in ("15/user_manual/index.html", "../../private.html"):
-            (source / "versioned/legacy-routes.json").write_text(json.dumps({
+            (source / "versioning/legacy-routes.json").write_text(json.dumps({
                 "user_manual/functionality.html": bad
             }))
             with self.assertRaises(ValueError):
diff --git a/tests/test_shared_sources.py b/tests/test_shared_sources.py
deleted file mode 100644
index 1b0d5506..00000000
--- a/tests/test_shared_sources.py
+++ /dev/null
@@ -1,78 +0,0 @@
-"""Shared documentation sections are copied without per-page build code."""
-
-import json
-import tempfile
-import unittest
-from pathlib import Path
-from unittest.mock import patch
-
-from versioning import build
-
-
-class SharedSourceTests(unittest.TestCase):
-    def fixture(self, root: Path) -> None:
-        (root / "developer_manual/integration").mkdir(parents=True)
-        (root / "developer_manual/integration/index.rst").write_text("Architecture")
-        (root / "developer_manual/integration/new-guide.rst").write_text("New guide")
-        (root / "developer_manual/integration/_native-webhooks.inc").write_text(
-            "Development completion event"
-        )
-        (root / "developer_manual/api").mkdir()
-        (root / "developer_manual/api/openapi.rst").write_text("OpenAPI")
-        (root / "developer_manual/html").mkdir()
-        (root / "developer_manual/index.rst").write_text("Development manual")
-        base = root / "versioned/base/developer_manual"
-        (base / "integration").mkdir(parents=True)
-        (base / "index.rst").write_text("Stable manual")
-        (base / "integration/_native-webhooks.inc").write_text("Only polling")
-        overlay = root / "versioned/16/developer_manual/integration"
-        overlay.mkdir(parents=True)
-        (overlay / "_native-webhooks.inc").write_text("Native event")
-        (root / "versioned/shared.json").write_text(
-            json.dumps({"developer_manual": ["integration"]})
-        )
-
-    def test_new_rst_is_shared_without_editing_python(self):
-        with tempfile.TemporaryDirectory() as temp:
-            root = Path(temp)
-            self.fixture(root)
-            with patch.object(build, "ROOT", root):
-                stage = root / "build"
-                stable = build.source_tree(stage, "15", "developer_manual")
-                upcoming = build.source_tree(stage, "16", "developer_manual")
-                dev = build.source_tree(stage, "main", "developer_manual")
-            for source in (stable, upcoming, dev):
-                self.assertTrue((source / "integration/new-guide.rst").is_file())
-            self.assertEqual(
-                (stable / "integration/_native-webhooks.inc").read_text(), "Only polling")
-            self.assertEqual(
-                (upcoming / "integration/_native-webhooks.inc").read_text(), "Native event")
-            self.assertEqual((dev / "integration/_native-webhooks.inc").read_text(),
-                             "Development completion event")
-            self.assertFalse((stable / "integration/source-only.rst").exists())
-
-    def test_unlisted_development_section_is_not_leaked(self):
-        with tempfile.TemporaryDirectory() as temp:
-            root = Path(temp)
-            self.fixture(root)
-            (root / "developer_manual/experimental").mkdir()
-            (root / "developer_manual/experimental/new.rst").write_text("Unreleased")
-            with patch.object(build, "ROOT", root):
-                stable = build.source_tree(root / "stage", "15", "developer_manual")
-            self.assertFalse((stable / "experimental/new.rst").exists())
-
-    def test_traversal_and_missing_sources_fail(self):
-        for section in (".", "./", "../secrets", "/etc", "missing"):
-            with self.subTest(section=section), tempfile.TemporaryDirectory() as temp:
-                root = Path(temp)
-                self.fixture(root)
-                (root / "versioned/shared.json").write_text(
-                    json.dumps({"developer_manual": [section]})
-                )
-                with patch.object(build, "ROOT", root):
-                    with self.assertRaises(ValueError):
-                        build.source_tree(root / "stage", "15", "developer_manual")
-
-
-if __name__ == "__main__":
-    unittest.main()

From de18322a5289984841a757c6244ffc7aa8d4e956 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Tue, 10 Nov 2026 15:02:36 +0000
Subject: [PATCH 4/5] docs: explain the per-release branch contribution
 workflow

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 AGENTS.md                      |  34 +++---
 CONTRIBUTING.md                | 165 +++++++++----------------
 README.md                      |  52 ++++----
 README.rst                     | 157 +-----------------------
 docs/maintainers/versioning.md | 217 ++++++++++++++-------------------
 5 files changed, 207 insertions(+), 418 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 05eb7664..e6d5cd4b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -42,17 +42,18 @@ configuration instruction, rendered example, or troubleshooting step:
    Check nested required request fields, types/enums, responses, authentication,
    feature availability, signing state and error cases. OpenAPI shape alone
    does not prove runtime behavior; the presence of a test is not proof it ran.
-3. **Choose the source scope deliberately.** `developer_manual/` is the
-   development line. `versioned/base/` is for behavior verified in **every**
-   published stable line; `versioned/<major>/` overrides it when any stable
-   behavior differs. The `main/` directory contains site navigation, not the
-   development developer manual. Never copy development-only claims into the
-   stable base, or assume newer features were backported. For an unverified
-   release, omit or explicitly qualify the claim rather than invent support.
+3. **Choose the release branch deliberately.** The `main` branch is
+   development; `stableNN` contains the complete documentation for LibreSign
+   major NN. Do not mix Nextcloud major numbers with LibreSign major numbers.
+   Changes to multiple versions require explicit backports and verification
+   against the corresponding application contract.
 4. **Verify executable examples per release.** Use the correct version-specific
    fixtures and checks; never make older guides silently use a newer payload.
-   Add regression coverage for incompatibilities, including negative cases.
-   Do not weaken a contract check just to keep inherited prose passing.
+   For ordinary RST pages, do not add Python tests that enumerate page paths,
+   assert editorial wording or mirror the documentation tree. The existing
+   Sphinx, link, OpenAPI and multiversion build checks validate those changes.
+   Add focused regression coverage only when executable contracts or the
+   documentation tooling itself change. Do not weaken existing contract checks.
 5. **Review versioned links and surrounding pages.** Avoid silently linking
    older manuals to `/main/`, `/latest/`, or moving source-branch URLs when
    claiming version-specific support. Inspect related pages across all three
@@ -65,14 +66,13 @@ configuration instruction, rendered example, or troubleshooting step:
    scenarios, and behaviors are verified versus untested. Green Sphinx/CI
    checks are not proof of real signing, SMTP, policies, or file permissions.
 
-This repository builds stable versions from `versioned/base/` plus overlays,
-not from separate documentation branches as Nextcloud does. Directory scopes
-shared from the development manual into stable builds are declared in
-`versioned/shared.json`, never hardcoded per page in build scripts. Preserve the
-existing dynamic discovery and build infrastructure. For authoring details
-and the external-email-signers fixture conventions, read
-[CONTRIBUTING.md](CONTRIBUTING.md). Application behavior and API contract
-changes belong in `LibreSign/libresign` and require a separate change there.
+Each release branch contains complete `main/`, `user_manual/`, `admin_manual/`
+and `developer_manual/` source directories. There is no `versioned/base` or
+per-file overlay mechanism. The central publishing tool checks out the exact
+documentation branch and pins the application OpenAPI separately. A missing
+stable documentation branch must fail rather than inherit development prose.
+For authoring instructions read [CONTRIBUTING.md](CONTRIBUTING.md).
+Application source and API changes belong to `LibreSign/libresign`.
 
 ## Quality gates
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 80155077..ea28304c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,117 +1,72 @@
-<!--
-SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
-SPDX-License-Identifier: CC-BY-3.0
--->
+<!-- SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+     SPDX-License-Identifier: CC-BY-3.0 -->
 
 # Contributing to LibreSign documentation
 
-This repository contains LibreSign's public user, administrator, and developer
-documentation. Choose the manual for your reader: `user_manual/`,
-`admin_manual/`, or `developer_manual/`. The `main/` directory provides
-top-level navigation. Follow the existing manual structure and write about the
-product or procedure, not the history of implementing a change. Explain concepts
-before advanced details, link to existing explanations instead of duplicating
-them, verify internal links and cross-references, and use examples without real
-personal or customer data.
+You can edit the documentation without knowing Python or the site generator.
 
-## Build and review your change
+## Select a version
 
-From the repository root, install Python 3.13 and the dependencies from the root
-`requirements.txt` in a virtual environment. For example:
+The branch **is** the LibreSign documentation version:
+
+| Branch | Documentation |
+| --- | --- |
+| `main` | Next LibreSign release (development) |
+| `stable15` | LibreSign 15 |
+| `stable14` | LibreSign 14 |
+| `stable13` | LibreSign 13 |
+
+New releases follow `stableNN`, where `NN` is the **LibreSign** major, not
+Nextcloud's major. The published version selector and **Edit on GitHub** links
+should take you to the matching branch automatically.
+
+## Edit one page
+
+1. Open the version and manual you want to change at https://docs.libresign.coop.
+2. Select **Edit on GitHub** or browse the corresponding branch.
+3. Edit the RST file under `user_manual/`, `admin_manual/` or `developer_manual/`.
+4. For a new page, add its name to the section `index.rst` (`.. toctree::`).
+5. Create a pull request targeting the **same** branch.
+6. Review the HTML preview and fix any Sphinx warnings or broken links.
+
+**No Python test, manual file manifest, or generator change is needed to add a
+page.** The CI builds the manual and checks internal links automatically.
+
+## Make a fix available in multiple versions
+
+Correct the newest applicable version first. Backport the same change to each
+older `stableNN` branch that needs it (one PR per target branch). Do not assume
+that an API operation or configuration option is available in an older release.
+
+API examples must match the pinned application OpenAPI and implementation for
+the intended LibreSign version. The documentation builds use the application
+manifest and the exact application commit; a Nextcloud version or an OCS
+`/api/v1` URL does not establish feature compatibility.
+
+## Preview locally
+
+Install Python and the dependencies in a virtual environment, then run:
 
 ```sh
-python -m venv .venv
-# Activate .venv for your shell, then:
 python -m pip install -r requirements.txt
+sphinx-build -n -W developer_manual _build/developer_manual
 ```
 
-Build every manual whose rendered pages you changed before opening a pull
-request. The root `Makefile` provides `make main`, `make user`, `make admin`,
-`make dev`, and `make all`. If `make` is unavailable, use the same Sphinx commands
-as the [Documentation CI workflow](.github/workflows/docs.yml):
+Replace `developer_manual` with the manual you changed. The PR workflow also
+validates all published releases, API provenance, SEO and links.
 
-```sh
-sphinx-build main _build/main
-sphinx-build user_manual _build/user_manual
-sphinx-build admin_manual _build/admin_manual
-sphinx-build -W developer_manual _build/developer_manual
-```
+Do not rename published pages without preserving their URLs with redirects.
+Never put credentials or real customer data into examples.
+
+## New stable LibreSign release
+
+The maintainers create `stableNN` from the approved development (`main`) manual
+when the LibreSign application releases that major. Public versions are
+discovered from the application manifest, not a hardcoded list in the site.
+The branch must exist before the documentation build can publish that release.
+
+## Commit policy
 
-Run the affected command(s), not necessarily all four; CI builds every
-version. For stable or cross-version edits, run
-`python -m versioning.build --output _build` when network access is available;
-it uses pinned application contracts. The developer manual is built with
-warnings treated as errors. The PR workflow publishes a navigable preview
-for visual checking of headings, code blocks, links and layout. No
-screenshot attachment or Python change is required to add an RST page.
-
-## Version-scoped integration documentation
-
-The published version selector does not by itself make prose compatible with
-an older LibreSign release. The build discovers application releases from
-`appinfo/info.xml`, pins each source commit and publishes that commit's
-`openapi.json`. The exact LibreSign/Nextcloud versions are available in
-Sphinx as `|LibreSignRelease|` and `|NextcloudRelease|`.
-
-The source layout deliberately has three different scopes:
-
-- `developer_manual/` describes the development (`main`) application.
-- `versioned/base/` contains only claims verified across the published
-  stable releases. Do not copy development-only behavior into this base.
-- `versioned/<major>/` overrides stable content when a release differs.
-- `versioned/shared.json` lists **directory scopes**, not individual pages,
-  that are already verified as release-safe and can be copied from the
-  development manual into stable builds. New RST files inside a declared
-  section are included automatically. Add a new directory to this small
-  declarative file only when all relevant stable releases support its content.
-  Keep development-only pages outside shared scopes.
-
-Use `.. toctree::` in your RST section index so Sphinx can discover the
-new page. No Python file needs modification to add a page, section or
-version-specific override; keep release discovery dynamic.
-
-For the external-email-signers guide, each supported application line has
-a reviewed `examples/external-email-signers/request-<slug>.json` and a
-`_external-email-signers-release.inc` in its own source directory.
-The Sphinx include extension `.inc` prevents these snippets from being
-treated as additional standalone manual pages. The CLI clients refuse
-to choose a fixture implicitly: `LIBRESIGN_DOC_LINE` selects a reviewed
-release explicitly. When a new release is discovered, add its reviewed
-fixture and overlay rather than inheriting an older identity schema.
-
-The Documentation CI gate validates the actual nested request fields
-and example JSON against **that version's pinned OpenAPI**, checks
-guarded controller and Playwright source files from the **same pinned
-application commit**, and rejects unknown/new releases without reviewed
-examples. It does not assert that browser signing, SMTP or certificate
-verification passed in a live environment. Record those executions
-separately when performed. Changes to an API contract must be made in
-the LibreSign application repository and regenerated there; do not
-modify the pinned JSON inside the documentation repository.
-
-## Pull request preview and evidence
-
-Link the relevant issue and describe the affected versions. The workflow
-publishes the complete multiversion HTML preview on an isolated origin and
-checks its public URLs. Review the rendered result by opening its links:
-navigation, responsive layout, dark mode, code blocks and cross-references
-are easier to verify there than in static screenshots. No screenshots are
-required, and you do not need to edit Python for ordinary RST contributions.
-
-Documentation for an unreleased application major is rendered into a separate
-`/_review/` preview area, with direct links in a PR comment. It does not
-appear in production Pages or the published version selector. Future-release
-content uses development application metadata for preview, not an invented
-stable OpenAPI. Contributor fork previews use the same isolated static HTML
-site, deployed by a privileged workflow that does not execute fork code.
-
-Keep each pull request focused. Report the tests actually run and any known
-runtime coverage gaps; never include secrets, private documents or real
-customer data in examples or previews.
-
-## Developer Certificate of Origin
-
-Sign off each commit to certify the [Developer Certificate of Origin](https://developercertificate.org/).
-With your Git name and email configured, use `git commit -s -m "Your message"`.
-The resulting `Signed-off-by: Name <email>` trailer must identify you; use an
-email associated with your GitHub account if you want GitHub to attribute it.
+Sign off every commit according to the
+[Developer Certificate of Origin](https://developercertificate.org/).
+A GitHub verified signature is also required when enforced by the repository.
diff --git a/README.md b/README.md
index 2f054799..fe602065 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,33 @@
-<!--
-SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
-SPDX-License-Identifier: CC-BY-3.0
--->
+<!-- SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+     SPDX-License-Identifier: CC-BY-3.0 -->
 
 # LibreSign documentation
 
-Source for the [LibreSign public documentation](https://docs.libresign.coop/),
-built with Sphinx. The site provides separate manuals for stable LibreSign
-majors (`/13/`, `/14/`, `/15/`) and development (`/main/`).
-
-- **Edit content:** use RST in `developer_manual/`, `user_manual/` or
-  `admin_manual/`. The `versioned/base/` directory holds stable foundations;
-  `versioned/<major>/` holds overrides. Shared development-to-stable sections
-  are listed in `versioned/shared.json`. Adding a page never requires editing
-  Python build or screenshot scripts.
-- **Contribute:** open a PR. CI checks Sphinx, links, OpenAPI provenance and
-  version isolation. Review the navigable preview, including any unpublished
-  release pages under `/_review/`; screenshots are not required.
-- **Maintain releases:** see the
-  [maintainer guide](docs/maintainers/versioning.md) for local builds,
-  deployment, previews, backports and lifecycle metadata.
-
-Canonical release history and API sources remain in
-[LibreSign/libresign](https://github.com/LibreSign/libresign).
+Public manuals: **https://docs.libresign.coop**.
+
+The documentation follows Nextcloud's **one branch per version** pattern:
+
+| Branch | LibreSign documentation |
+| --- | --- |
+| `main` | Next release, in development |
+| `stable15` | LibreSign 15 |
+| `stable14` | LibreSign 14 |
+| `stable13` | LibreSign 13 |
+
+For a new release, use `stableNN`, where NN is the **LibreSign major** (not the
+Nextcloud server major). Each branch contains complete `user_manual/`,
+`admin_manual/` and `developer_manual/` sources. There are no `versioned/`
+source overlays and no per-page Python tests to update.
+
+**To edit a page:** choose the LibreSign version on the website, select
+**Edit on GitHub**, update the RST file and open a PR to the **same branch**.
+For a new page, add it to the section's `index.rst` (`.. toctree::`).
+For changes applying to multiple versions, backport explicitly.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for everyday editing and
+[docs/maintainers/versioning.md](docs/maintainers/versioning.md) for the
+publication process, API contracts and new releases.
+
+The build dynamically discovers released LibreSign majors and pins their
+OpenAPI contracts to their exact application commits. Releases are never
+inferred from a documentation branch alone.
diff --git a/README.rst b/README.rst
index fe6622ff..23da1590 100644
--- a/README.rst
+++ b/README.rst
@@ -2,156 +2,11 @@
 LibreSign Documentation
 =======================
 
-Documentation is published on `<https://docs.libresign.coop>`_.
-To edit it yourself, you need to tinker a bit with Git and Sphinx.
-See the `Style Guide <https://github.com/nextcloud/documentation/blob/master/style_guide.rst>`_ for formatting and style conventions.
+Public manuals are available at https://docs.libresign.coop.
 
-Manuals
--------
+See `README.md <https://github.com/LibreSign/documentation#readme>`_ for the
+version-to-branch mapping and `CONTRIBUTING.md
+<https://github.com/LibreSign/documentation/blob/main/CONTRIBUTING.md>`_
+for the editing guide.
 
-This repository hosts three manuals:
-
-* **Users' Manual**
-* **Administration Manual**
-* **Developers Manual**
-
-Please wrap lines at 80 characters.
-
-Spelling and Capitalization Conventions
----------------------------------------
-
-* Nextcloud
-* LibreSign
-
-License
--------
-
-All documentation in this repository is licensed under the Creative Commons
-Attribution 3.0 Unported license (`CC BY 3.0`_).
-
-.. _CC BY 3.0: https://creativecommons.org/licenses/by/3.0/deed.en_US
-
-Style
------
-
-Source files are written using the `Sphinx Documentation Generator
-<https://www.sphinx-doc.org/en/master/>`_. The syntax follows the `reStructuredText
-<http://docutils.sourceforge.net/rst.html>`_ style, and can also be edited
-from GitHub.
-
-Structure
----------
-
-Of course, think about structure. Keep in mind that we try NOT to move or rename
-pages once they are created! Lots of external sources link to our documentation,
-including the indexing by search engines of course. So once you create a page with a certain
-name, it has to stay in that location and with that name. Think of it as API stability
-- we have to ensure things stay as they are as much as possible. Renaming or moving
-is only allowed in exceptional circumstances and only when a redirect is put in place.
-
-Editing
--------
-
-Contributing to the documentation requires a GitHub account.
-
-To edit a document, you can edit the .rst files on your local system, or work
-directly on GitHub. The latter is only suitable for small fixes and improvements
-because substantial editing efforts can better be controlled on your local PC.
-
-The best way is to install a complete Sphinx build environment and work on your
-local PC or using the docker-compose that stay at home folder of this repository.
-You will be able to make your own local builds, which is the fastest
-and best way to preview for errors. Sphinx will report syntax errors, missing
-images, and formatting errors. The GitHub preview is not complete and misses
-many mistakes. Create a new branch against the main, make your edits, then push
-your new branch to GitHub and open a new PR.
-
-To edit on GitHub, fork the repository (see top-right of the screen, under
-your username). You will then be able to make changes easily. Once done,
-you can create a pull request and get the changes reviewed and back into
-the official repository.
-
-When editing either on your own local PC or on GitHub, be sure to sign of
-commits, to certify adherence to the Developer Certificate of Origin,
-see https://github.com/probot/dco . Your commit messages need to have,
-the name and email address of the contributor.
-
-  Signed-off-by: Awesome Contributor <awesome.contributor@reach.me>
-
-If using the command line and your name and email are configured, you can use
-
-  git commit -s -m 'Commit message'
-
-In both settings be sure that your email address matches that in your GitHub profile,
-which if you have privacy enabled will be github.username@users.noreply.github.com
-
-
-Building
---------
-
-Building HTML
-=============
-
-Using pipenv
-^^^^^^^^^^^^
-
-1. Install ``pipenv`` - https://pipenv.readthedocs.io/en/latest/
-2. Change into the environment: ``pipenv shell``
-3. Install the dependencies ``pip install -r docs/requirements.txt``
-4. Now you can use ``make ...`` to build all the stuff - for example ``make html`` to build the HTML flavor of all manuals
-   The build assets will be put into the individual documentation subdirectories like ``developer_manual/_build/html/com``
-
-To change into this environment you need to run ``pipenv shell`` to launch the shell and to exit you can use either ``exit`` or ``Ctrl`` + ``D``.
-
-Using venv
-^^^^^^^^^^
-
-1. Install ``python3-venv``
-2. Only once: Create a venv (typically inside this repository): ``python -m venv venv``
-3. Activate the environment (inside this repository): ``source venv/bin/activate``
-4. Install the dependencies ``pip install -r docs/requirements.txt``
-5. Now you can use ``make ...`` to build all the stuff - for example ``make html`` to build the HTML flavor of all manuals
-   The build assets will be put into the individual documentation subdirectories like ``developer_manual/_build/html/com``
-
-Autobuilding
-^^^^^^^^^^^^
-
-When editing the documentation installing ``sphinx-autobuild`` though pip can be helpful. This will watch file changes and automatically reload the html preview:
-
-1. Install ``pip install sphinx-autobuild``
-2. Enter the documentation section ``cd user_manual``
-3. Watch for file changes ``make SPHINXBUILD=sphinx-autobuild html``
-4. Open http://127.0.0.1:8000 in the browser and start editing
-
-Using the VSCode DevContainer
-=============================
-
-This repository contains a full-featured `VSCode DevContainer <https://code.visualstudio.com/docs/devcontainers/containers>`_.
-You can use it in your local development environment or via `GitHub Codespaces <https://github.com/features/codespaces>`_.
-Just open the container an use one of the commands from above to build the project. For example ``make`` to build the full
-documentation. You can also use ``make SPHINXBUILD=sphinx-autobuild html``
-in combination with `port forwarding <https://code.visualstudio.com/docs/devcontainers/containers#_forwarding-or-publishing-a-port>`_
-to  watch file changes and automatically reload the html preview.
-
-Usign docker
-============
-You can also use the `docker-compose.yml` file to build the documentation using
-Docker. This is useful if you want to avoid installing Python and its
-dependencies on your local machine.
-
-1. Make sure you have Docker and Docker Compose installed.
-2. Open a terminal and navigate to the root directory of the repository.
-3. Run the following command to build the documentation:
-
-   ``docker-compose up``
-
-   This will build the HTML documentation and place it in the `volumes/html` directory.
-   And also will start a HTTP server and you can access the documentation at `http://localhost:8000`.
-
-4. To stop the server, press `Ctrl+C` in the terminal.
-
-
-.. _CC BY 3.0: https://creativecommons.org/licenses/by/3.0/deed.en_US
-.. _`Xcode command line tools`: https://stackoverflow.com/questions/9329243/xcode-install-command-line-tools
-
-This README was based on the `Nextcloud documentation <https://github.com/nextcloud/documentation/blob/master/README.rst>`_.
\ No newline at end of file
+All documentation is licensed under Creative Commons Attribution 3.0 Unported.
diff --git a/docs/maintainers/versioning.md b/docs/maintainers/versioning.md
index 5731ac1b..2af7685c 100644
--- a/docs/maintainers/versioning.md
+++ b/docs/maintainers/versioning.md
@@ -1,133 +1,104 @@
-<!--
-SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
-SPDX-License-Identifier: CC-BY-3.0
--->
-
-# Versioning, previews and publication
-
-This guide is intended for contributors and release maintainers, not as
-public API documentation. The root [README](../../README.md) is deliberately
-short. Product release histories remain canonical in
-[LibreSign/libresign](https://github.com/LibreSign/libresign/releases).
-
-## Source of truth and release boundaries
-
-Each build resolves the application branches to **immutable commit SHAs** and
-fetches `appinfo/info.xml` and `openapi.json` from each resolved SHA.
-Stable lines are discovered from the manifest, and incompatible Nextcloud
-dependencies cause the build to fail. A stable line must never load an API
-contract from `main`. Every generated API reference has accompanying
-`openapi.json` and `openapi.provenance.json` files.
-
-Maintain `main/` as top-level navigation and `developer_manual/` as
-development documentation. Use `versioned/base/` for the release-safe
-foundation and `versioned/<major>/` for release overrides. Directories
-verified as shared across development and stable lines are declared in
-`versioned/shared.json`; the build copies their RST automatically, without
-a per-page script change. Do not expose unreviewed development-only flows in
-stable manuals. The Sphinx theme and configuration are shared.
-
-The documentation homepage (the root URL) lists versions from latest stable
-to oldest stable and development `main` last. Within the Sphinx manuals,
-the version chooser is collapsed in the bottom-left corner, following the
-Nextcloud Server documentation pattern. It preserves the current page when
-that page exists in the target version, otherwise opening the target
-manual index. The selector marks `main` as development, the latest supported
-stable line as current, and earlier stable lines as previous. The homepage uses
-`assets/home-theme.js` with the same `localStorage.theme` preference as
-`sphinx_rtd_dark_mode` on internal pages. Theme changes must persist when
-navigating between these pages. EOL status and dates are explicit entries in
-`versioning/lifecycle.json`. Never infer an EOL commitment or commercial
-support guarantee from branch existence.
-
-## Local build and checks
-
-Use Python 3.13 (as in CI) and install `requirements.txt` plus
-`openapi-spec-validator==0.7.2`. Run:
+<!-- SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+     SPDX-License-Identifier: CC-BY-3.0 -->
+
+# Versioning and publication of LibreSign documentation
+
+The public source is deliberately simple: **one complete documentation branch
+per LibreSign major**, following the Nextcloud documentation convention.
+
+## Where to edit
+
+| Target | Git branch | Source path |
+| --- | --- | --- |
+| Next LibreSign version | `main` | `user_manual/`, `admin_manual/`, `developer_manual/` |
+| LibreSign 15 | `stable15` | Same paths |
+| LibreSign 14 | `stable14` | Same paths |
+| LibreSign 13 | `stable13` | Same paths |
+
+For a future stable release `NN`, create `stableNN`. The documentation branch
+name is the **LibreSign major**, not the Nextcloud major; the application
+repository uses a different naming convention (`stable35` for LibreSign 15).
+Each source branch contains its complete manual, without shared-directory
+inheritance or `versioned/base` overlays. **Edit on GitHub** links to the
+matching branch and file, not to a generated or inherited source.
+
+Ordinary RST contributions do not require Python changes. Add a page to the
+section's `index.rst` toctree, build with Sphinx and open a PR against the
+right branch. Backport changes explicitly when they apply to older releases.
+
+## What the central build does
+
+`main` contains the publishing tool and site-wide assets. It:
+
+1. Discovers released application branches and the development branch from
+   `LibreSign/libresign`, verifying `appinfo/info.xml` compatibility.
+2. Pins the application commit and OpenAPI SHA for **each** released version.
+3. Fetches the matching documentation `stableNN` branch and pins its Git SHA.
+   Missing branches cause an error; the build never substitutes development
+   documentation for a stable release.
+4. Builds each branch's manuals using the current common Sphinx theme and
+   navigation. The published URLs remain `/13/`, `/14/`, `/15/`, `/main/` etc.
+5. Validates links, API provenance, signing examples, redirects and the output
+   of all other versions before deploying atomically to Pages.
+
+Stable application releases are discovered dynamically, not maintained in a
+fixed list. EOL dates and policy remain in `versioning/lifecycle.json`.
+The API version is always taken from the application manifest, not from the
+Nextcloud release number or a guessed API URL.
+
+## Validate a change locally
+
+On the branch containing the publishing tool (`main`):
 
 ```sh
+python -m pip install -r requirements.txt openapi-spec-validator==0.7.2
 python -m unittest discover -s tests -v
 node --test tests/js/*.test.mjs
 python -m versioning.build --output _build
 python -m versioning.verify --output _build
 python -m versioning.publish --built _build --destination _publish
 python -m versioning.verify --output _publish
-python -m http.server 8765 --directory _publish
-```
-
-The build needs read-only network access to application Git refs and files.
-It fails rather than substituting an outdated or development-branch contract.
-Sphinx is compiled with warnings as errors, OpenAPI provenance and links are
-checked, and the PR preview is tested at the public preview origin. Screenshots
-are not generated or required. Version numbers and documentation pages are
-not maintained in capture scripts.
-
-## Pull request previews
-
-The `Documentation PR Preview` workflow builds the full multiversion
-candidate without changing production Pages. The URL pattern is:
-
-```text
-https://libresign.github.io/site-preview/docs-preview/pr-<number>/
 ```
 
-The preview lives on the **isolated preview origin**, in the
-`LibreSign/site-preview` repository, under its own `docs-preview/`
-namespace. The production domain `docs.libresign.coop` is never used for
-unreviewed HTML. A preview banner identifies the PR, and all version
-selection, redirects and links stay within the preview prefix.
-
-The workflow authenticates to the preview repository through the existing
-organization GitHub App `librecode-workflow-automation`. It requires
-`vars.LIBRECODE_WORKFLOW_APP_ID` and
-`secrets.LIBRECODE_WORKFLOW_APP_PRIVATE_KEY` (the organization already
-distributes these to its repositories). The app token is short-lived and
-restricted to `LibreSign/site-preview`; no personal PAT needs copying.
-
-For PRs originating in this repository, the workflow publishes the full
-navigable preview, verifies the publicly hosted routes, and posts a sticky
-comment containing direct links. When the development major has unreleased
-release-specific overlays (for example, an event reference before a stable
-branch exists), they are built under `/_review/<major>/` with the
-development application's contract. A dedicated `/_review/` landing page
-links to every rendered overlay page. None of those pages is inserted into
-`versions.json`, the version selector or production Pages.
-
-For forks, the unprivileged workflow only uploads an HTML artifact; the
-trusted `workflow_run` consumer checks its static files, publishes it and
-verifies its public URLs without executing fork code while possessing the
-deployment token. The existing preview action posts the PR link; the preview
-homepage also links to `/_review/`, so no second comment script is needed.
-Upon closing the PR, the trusted cleanup workflow removes the preview.
-
-The preview action and organization App do not publish stable documentation.
-Successful preview CI is **not authorization to merge**.
-
-## Releases and backports
-
-1. Confirm the application release/backport and its manifest and OpenAPI.
-2. Review changes to `versioned/<major>/`; keep the stable content bounded
-   by the branch's actual capabilities.
-3. Open a documentation PR, inspect the navigable preview (including
-   `/_review/` when relevant), and wait for CI checks.
-4. After approval and merge, the `Deploy Sphinx Docs` workflow deploys
-   the complete site. For a targeted update, dispatch with
-   `version: <major>` or `version: main`. The application release
-   tooling may send `repository_dispatch` events named
-   `libresign-documentation-release` or
-   `libresign-documentation-backport` with
-   `client_payload.version`.
-5. The daily scheduled workflow also discovers new stable application
-   branches and captures subsequent backports. Each line is built from a
-   pinned commit of its application branch.
-6. Partial releases first check out the existing `gh-pages` site and
-   **replace only the selected version**; they fail if the old catalog
-   or another previously published version is missing. Full releases must
-   build every version before deployment.
-7. Test each published major/manual URL and its corresponding
-   `openapi.provenance.json`. The root URL lists every available version
-   (latest stable first); legacy, unversioned manual URLs redirect to the
-   current stable line.
-
-Pages deployments are serialized by workflow concurrency. Their output must
-never erase sibling stable versions.
+The build requires read-only Git access to the LibreSign application and
+this documentation repository. All released application versions must have
+an existing documentation source branch before CI can publish them.
+
+When editing a `stableNN` documentation branch, the CI builds its local
+manuals with Sphinx warnings treated as errors. It does **not** regenerate
+all public releases; the publication workflow on `main` does that.
+
+## PR previews
+
+The main-branch PR workflow builds a complete isolated candidate on
+`https://libresign.github.io/site-preview/docs-preview/pr-<number>/`.
+Development documentation already exists at `/main/`; it is not duplicated
+in a fake stable version under `/_review/NN/`. The `/_review/` index links to
+the actual development manual and its preview. The separate preview origin is
+never the production domain. PRs from forks are deployed only by the
+privileged workflow after static-artifact inspection.
+
+The sticky preview comment includes stable and development entry links.
+A successful preview does not authorize a merge.
+
+## Release procedure
+
+1. Review and approve the application release manifest and its OpenAPI.
+2. Freeze approved documentation for the release in `main`.
+3. Create a DCO-signed documentation branch `stableNN` from that snapshot,
+   **before** publishing the application's newly released major in the site.
+4. Update the `main` documentation for the next development cycle as needed.
+5. Run the central build and verify its HTML pages, exact API provenance,
+   correct GitHub edit links, and version selector.
+6. Deploy via `Deploy Sphinx Docs` after review.
+
+To fix an older release, backport the documentation change to its `stableNN`
+branch. The central scheduled workflow sees both application and documentation
+updates; for faster updates, run `workflow_dispatch` with `version: NN`.
+Partial publication replaces only the selected release and preserves all
+others. Full publication validates every version before deployment. Existing
+unversioned URLs remain pinned through `versioning/legacy-routes.json`;
+they must not be redirected silently to a newer API or a different release.
+
+GitHub Pages deployments are serialized. Publishing unreleased material to
+`docs.libresign.coop` requires an explicitly authorized release process.

From ee220f129ba1e4981a6d9670a2679170d8aa592d Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Tue, 10 Nov 2026 15:14:37 +0000
Subject: [PATCH 5/5] ci(docs): wait for published preview revision before
 checking routes

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .github/workflows/preview.yml | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml
index e9f1459d..1cc135f6 100644
--- a/.github/workflows/preview.yml
+++ b/.github/workflows/preview.yml
@@ -96,6 +96,29 @@ jobs:
           qr-code: false
           token: ${{ steps.preview-token.outputs.token }}
 
+      - name: Wait until GitHub Pages serves this exact preview revision
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        env:
+          PREVIEW_ROOT: https://libresign.github.io/site-preview/docs-preview/pr-${{ github.event.pull_request.number }}
+        run: |
+          # The deploy action pushes gh-pages, but Pages publishes it
+          # asynchronously. Byte equality of versions.json proves the
+          # exact documentation revision has reached the public origin.
+          for attempt in $(seq 1 108); do
+            if curl -fsSL --max-time 15 -H 'Cache-Control: no-cache' \
+              -o /tmp/libresign-live-versions.json \
+              "$PREVIEW_ROOT/versions.json?run=$GITHUB_RUN_ID&attempt=$attempt" &&
+              cmp -s _publish/versions.json /tmp/libresign-live-versions.json; then
+              echo "GitHub Pages serves the expected documentation revision"
+              break
+            fi
+            if [ "$attempt" -eq 108 ]; then
+              echo "::error::GitHub Pages did not publish this preview revision" >&2
+              exit 1
+            fi
+            sleep 10
+          done
+
       - name: Check every navigable preview route on the public origin
         if: github.event.pull_request.head.repo.full_name == github.repository
         env:
@@ -121,7 +144,7 @@ jobs:
             fi
             url="$PREVIEW_ROOT$route"
             success=false
-            for attempt in $(seq 1 24); do
+            for attempt in $(seq 1 4); do
               if curl -fsSL --max-time 15 -H 'Cache-Control: no-cache' \
                 -o /tmp/libresign-preview-page.html \
                 "$url?run=$GITHUB_RUN_ID&attempt=$attempt" &&