docs: Configuration Snapshots guide

docs/configuration-snapshots/_category_.yml

@@ -0,0 +1,2 @@
+label: Configuration Snapshots
+position: 21

docs/configuration-snapshots/intro.md

@@ -0,0 +1,78 @@
+---
+title: Configuration Snapshots
+sidebar_position: 1
+description: "Configuration Snapshots are point-in-time backups of your epilot configuration. Learn how daily, manual and pre-install snapshots work and what they cover."
+---
+
+# Configuration Snapshots
+
+[[API Docs](/api/snapshot)]
+
+A **Configuration Snapshot** is a point-in-time backup of your organization's configuration: journeys, automations, schemas, templates, products and more. You can restore a snapshot to put captured resources back to the state they had when the snapshot was taken.
+
+:::warning
+Snapshots back up **configuration only**. They do not contain customer data, secrets or (in some cases) file content. Read [What is not supported](./limitations.md) before relying on snapshots for disaster recovery.
+:::
+
+## Types of snapshots
+
+| Type | When it is created | Who triggers it |
+|---|---|---|
+| **Daily snapshot** | Automatically, once per day, for organizations enrolled in the daily schedule | epilot |
+| **Manual snapshot** | When you capture the organization (or a selection of resources) on demand | You |
+| **Pre-install snapshot** | Automatically, right before a Blueprint install overwrites existing resources | The Blueprint install |
+
+### Daily snapshots
+
+Each enrolled organization is captured once per day, at a fixed time inside a window between **00:00 and 05:00 Europe/Berlin**. The exact minute is derived from your organization ID, so it stays the same every day. Daily snapshots are kept for **90 days** by default.
+
+You can read the schedule of your organization with `GET /v1/org-snapshot-schedule`. It returns the status of the last run.
+
+### Manual snapshots
+
+Use a manual snapshot before a risky change, for example a large refactoring of automations. You can capture the whole organization (`POST /v1/snapshots:capture-org`) or a specific set of resources (`POST /v1/snapshots`).
+
+### Pre-install snapshots
+
+When you install or update a [Blueprint](../blueprints/intro.md), epilot first works out which existing resources the install would **update**. If there are any, a snapshot of exactly those resources is taken before anything is written. If the install only creates new resources, no snapshot is taken, because nothing is overwritten.
+
+This snapshot is what makes it possible to [revert a Blueprint install](./restoring-and-reverting.md#reverting-a-blueprint-install).
+
+## What a snapshot covers
+
+The table shows what is captured and restored per resource type. Types not listed here are not covered.
+
+| Resource | Captured | Restorable | Notes |
+|---|---|---|---|
+| Journeys | Yes | Yes | Designs are separate resources and are captured on their own. |
+| Datasources | Only as a dependency | Yes | Captured only when another captured resource (for example a journey) depends on it. |
+| Automations (flows) | Yes | Yes | |
+| Flow templates, workflow definitions, closing reasons | Yes | Yes | A deleted resource is recreated with a new ID. |
+| Entity schemas, attributes, groups, headlines, capabilities | Yes | Yes | Configuration only, never entity data. |
+| Taxonomies and classifications (purposes, labels) | Yes | Yes | Restore does not merge labels and clears label fields that are absent from the snapshot. |
+| Portal configurations | Yes | Partial | Restore merges. Pages are never removed. |
+| Webhooks | Yes | Partial | Authentication secrets are restored as a placeholder. |
+| Environment variables | No | No | Secrets are never captured. |
+| Access tokens | No | No | Secrets are never captured. |
+| Files | Only as a dependency | Depends on content | Content is archived only when your organization uses the new file handling. |
+| Document templates | Yes (metadata) | Only with archived content | Templates whose file content cannot be identified are skipped. At most 1,000 templates per organization. |
+| Email templates, email signatures, shared inboxes, custom variables | Yes | Yes | Attachments are files, see above. |
+| Products, prices, taxes, coupons, product recommendations, notification templates | Yes | Yes | |
+| Entity mappings, validation rules, targets, apps, integrations | Yes | Yes | |
+| Saved views, designs | Yes | Yes | |
+| Roles, user groups | Yes | Yes | System roles that match by slug are skipped on restore. |
+| Dashboards, kanban boards, insights | Yes | Yes | Resources the snapshot user cannot access are skipped. |
+| Customer entity data (contacts, orders, opportunities, ...) | No | No | Out of scope by design. |
+| Workflow executions, users, permission grants, email domains | No | No | No coverage. |
+
+## Required permissions
+
+| Action | Required grant |
+|---|---|
+| Create a manual snapshot, change the daily schedule | `configuration_hub:snapshot:create` |
+| Restore a snapshot | `configuration_hub:snapshot:restore` |
+| Delete a snapshot | `configuration_hub:snapshot:delete` |
+| Browse snapshots and their resources | `configuration_hub:view` |
+| Create, read and restore the pre-install snapshot of a Blueprint install | `blueprint:install` (see below) |
+
+The `blueprint:install` grant covers the pre-install snapshot of that install: creating and reading it, and restoring it to revert that one Blueprint. A restore under this grant must name the Blueprint instance the snapshot belongs to. It does not allow restoring other snapshots.

docs/configuration-snapshots/limitations.md

@@ -0,0 +1,54 @@
+---
+title: What is not supported
+sidebar_position: 3
+description: "Limitations of Configuration Snapshots: what is never captured, what restores only partially and what a restore or revert does not do."
+---
+
+# What is not supported
+
+Configuration Snapshots are a safety net for configuration changes. They are **not** a full backup of your organization. Review this page before you rely on them.
+
+## Never captured
+
+| Not captured | Why | What to do |
+|---|---|---|
+| **Environment variables** and **access tokens** | They hold secrets. Secret values are never written to a snapshot and are never restored. | Keep your own record of secret values. Re-create them after a loss. |
+| **Customer entity data** (contacts, accounts, orders, opportunities and other business records) | Snapshots capture configuration only. Entity **schemas** are captured, entity **records** are not. | Use your regular data export or backup process. |
+| **Workflow executions, users, permission grants, email domains** | No snapshot coverage for these. | Not applicable. |
+
+## Captured only in some cases
+
+- **Datasources and standalone files** are captured only as dependencies of other resources (for example the datasource of a journey, or a file attached to an email template). They are not included in a daily snapshot on their own.
+- **File content** is archived only for organizations that use the new file handling. Otherwise files and document templates are skipped, so they cannot be restored.
+- **Document templates** need an identifiable file content to be captured. Templates whose content cannot be identified are skipped. Templates created before July 2026 may be affected. At most **1,000 document templates** per organization are considered.
+- **Dashboards, kanban boards and insights** that the snapshot user cannot access are skipped. The snapshot is still reported as successful, so check the skipped resources if you rely on them.
+- **Resources that belong to another organization** are skipped.
+
+A snapshot can have the status partial when some resources were skipped. Partial does not mean the snapshot is unusable.
+
+## Restores partially
+
+- **Webhooks:** authentication secrets are restored as a placeholder (`EPILOT_PLACEHOLDER`). Re-enter URL credentials and secrets after the restore.
+- **Portals:** a restore merges the captured configuration into the current one. Pages are matched by slug and are **never removed**, so pages created after the snapshot remain.
+- **Taxonomies:** a restore does not merge labels and clears label fields that are absent from the snapshot.
+- **Roles:** system roles that match by slug are skipped.
+
+## What a restore does not do
+
+- A restore **never deletes** resources that were created after the snapshot was taken. Delete them manually if you need the exact earlier state.
+- A deleted resource is **recreated with a new ID**. External systems that stored the old ID need to be updated.
+
+A [Blueprint revert](./restoring-and-reverting.md#reverting-a-blueprint-install) differs: it also deletes the resources the install created, except secrets, files and document templates.
+
+## Schedule and retention
+
+- Daily snapshots run inside a window between **00:00 and 05:00 Europe/Berlin**. You cannot choose the time.
+- If a daily snapshot fails, it is retried once on the same day.
+- Default retention is **90 days**, maximum **744 days**. After that the snapshot is deleted.
+- Daily snapshots are available for organizations enrolled in the schedule.
+
+## Pre-install snapshots
+
+- A pre-install snapshot is only taken if the install **updates** existing resources. Installs that only create resources have nothing to revert.
+- Files, document templates, environment variables and access tokens that the install updates cannot be reverted.
+- Reverting an install requires the `blueprint:install` grant. See [required permissions](./intro.md#required-permissions).

docs/configuration-snapshots/restoring-and-reverting.md

@@ -0,0 +1,45 @@
+---
+title: Restoring and reverting
+sidebar_position: 2
+description: "Restore a configuration snapshot to bring back captured resources, or revert a Blueprint install to its pre-install state."
+---
+
+# Restoring and reverting
+
+## Restoring a snapshot
+
+Restoring a snapshot re-applies the captured resources to your organization (`POST /v1/snapshots/{id}:restore`). You can restore the whole snapshot or select individual resources. Progress is available from `GET /v1/snapshots/{id}/restores/{index}`.
+
+A restore **only writes**:
+
+- Resources that still exist are overwritten with the captured version.
+- Resources that were deleted since the snapshot are recreated, **with a new ID**.
+- Resources that were **created after** the snapshot are left untouched. A restore never deletes anything.
+
+If another restore is already running for your organization, the request is rejected with a conflict and you can retry later.
+
+:::info
+Check the [limitations](./limitations.md) before restoring. Secrets, customer data and some file content are not part of a snapshot, and some resource types restore only partially.
+:::
+
+## Reverting a Blueprint install
+
+After a Blueprint install, the install overview offers a revert when the install changed something that can be reverted. A revert does two things:
+
+1. **Restores the pre-install snapshot.** Resources the install updated go back to their previous state.
+2. **Deletes the resources the install created.** These are found through the install record, so resources you created yourself are not affected.
+
+A revert preview shows what would be restored, deleted or skipped before you confirm.
+
+### What a revert does not touch
+
+These resource types are never deleted by a revert, even if the install created them, because their previous state is not in the snapshot:
+
+- Environment variables and access tokens (secrets are never captured)
+- Files and document templates
+
+They are reported as skipped in the preview. An install that only touches these types has nothing to revert.
+
+## Retention
+
+Snapshots expire automatically. The default retention is 90 days. Retention can be set up to 744 days (24 months) on the daily schedule and on manual org captures. Expired snapshots are deleted, including their stored content.

sidebars.js

@@ -135,6 +135,13 @@ module.exports = {
       collapsed: true,
       items: [{ type: 'autogenerated', dirName: 'blueprints' }],
     },
+    {
+      type: 'category',
+      label: 'Configuration Snapshots',
+      collapsible: true,
+      collapsed: true,
+      items: [{ type: 'autogenerated', dirName: 'configuration-snapshots' }],
+    },
     {
       type: 'category',
       label: 'Pricing',