From 93ed2b864be2a9bb014f4737782227745a7a636d Mon Sep 17 00:00:00 2001
From: Evgenii Alekseev <i@arcanis.me>
Date: Sun, 22 Mar 2026 14:19:45 +0200
Subject: [PATCH] docs: describe rollback procedure in docs

---
 docs/architecture.rst | 12 ++++++++++++
 docs/faq/backup.rst   | 25 +++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/docs/architecture.rst b/docs/architecture.rst
index 28ba46fd..88cff60c 100644
--- a/docs/architecture.rst
+++ b/docs/architecture.rst
@@ -235,6 +235,18 @@ Remove packages
 
 This flow removes package from filesystem, updates repository database and also runs synchronization and reporting methods.
 
+Rollback packages
+^^^^^^^^^^^^^^^^^
+
+This flow restores a package to a previously built version:
+
+#. Load the current package definition from the repository database.
+#. Replace its version with the requested rollback target.
+#. Search the archive directory for built artifacts (packages and signatures) matching the target version.
+#. Add the found artifacts to the repository via the same path as ``package-add`` with ``PackageSource.Archive``.
+#. Trigger an immediate update to process the added packages.
+#. If ``--hold`` is enabled (the default), mark the package as held in the database to prevent automatic updates from overriding the rollback.
+
 Check outdated packages
 ^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/faq/backup.rst b/docs/faq/backup.rst
index 1b74e6b8..98156d6e 100644
--- a/docs/faq/backup.rst
+++ b/docs/faq/backup.rst
@@ -33,3 +33,28 @@ The service provides several commands aim to do easy repository backup and resto
    .. code-block:: shell
 
       sudo -u ahriman ahriman repo-rebuild --from-database
+
+Package rollback
+================
+
+If the ``archive.keep_built_packages`` option is enabled, the service keeps previously built package files in the archive directory. These archives can be used to rollback a package to a previous successfully built version.
+
+#.
+   List available archive versions for a package:
+
+   .. code-block:: shell
+
+      ahriman package-archives ahriman
+
+#.
+   Rollback the package to the desired version:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman package-rollback ahriman 2.19.0-1
+
+   By default, the ``--hold`` flag is enabled, which prevents the package from being automatically updated on subsequent ``repo-update`` runs. To rollback without holding the package use:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman package-rollback ahriman 2.19.0-1 --no-hold