docs: correct unsafe deployment and recovery guidance (emdash-cms#3029)

* docs: correct unsafe deployment and recovery guidance

* docs: clarify safety guidance

* docs: trim repeated safety guidance

Author: ascorbic

docs/src/content/docs/deployment/cloudflare.mdx

@@ -454,29 +454,22 @@ the provider under **Settings → Email**.
 
 ## Environment Variables
 
-### Recommended: encryption key
+### Encryption key validation
 
-`EMDASH_ENCRYPTION_KEY` is the key for encrypting plugin secrets at
-rest (webhook tokens, Turnstile keys, etc.). The key is validated on
-startup; plugin secret encryption uses it once enabled. Set it on
-every deployment so secrets are protected without a later config
-change.
+`EMDASH_ENCRYPTION_KEY` does not currently encrypt plugin secrets. If the variable is set, EmDash
+checks its format during startup, but plugin secret values remain unencrypted in the database.
 
-The key is provided by you and never stored in the database; only
-encrypted ciphertext is. Losing it means losing every secret encrypted
-with it.
-
-Generate a key and store it as a Worker secret with the following commands:
+If you set the variable, generate a valid value and store it as a Worker secret with the following
+commands:
 
 ```bash
 npx emdash secrets generate
 wrangler secret put EMDASH_ENCRYPTION_KEY
 ```
 
 <Aside type="caution">
-Never commit the encryption key to your repository, and back it up
-somewhere durable (a password manager, KMS, or your team's secret
-store). The plain text value lives only in your environment.
+	Treat the database and its backups as sensitive because they contain plaintext plugin secrets.
+	Never commit secret values to your repository.
 </Aside>
 
 ### Optional: stable-value overrides
@@ -493,7 +486,9 @@ needs to share the secret with your main site.
 | `EMDASH_IP_SALT` | Override for the auto-generated commenter-IP hash salt. |
 | `EMDASH_AUTH_SECRET` | Optional. If set, it is used as the IP-salt source (unless `EMDASH_IP_SALT` is also set, which takes precedence), keeping commenter-IP hashes stable for installs that already rely on it. Leave it unset for a new deployment. |
 
-Access environment variables in your configuration using `import.meta.env` or the Cloudflare `env` binding.
+Read EmDash secrets from `process.env` at runtime. Read Worker bindings from `env`, imported from
+`cloudflare:workers`. Never read secrets through `import.meta.env`: Vite replaces those values at
+build time and can write them into the server bundle.
 
 For the complete inventory of every secret EmDash uses — including storage locations, rotation steps, and what breaks when a key is lost — see [Secrets & Key Management](/deployment/secrets/).
 

docs/src/content/docs/deployment/nodejs.mdx

@@ -170,23 +170,20 @@ docker compose up -d
 
 ## Environment Variables
 
-### Recommended: encryption key
+### Encryption key validation
 
-`EMDASH_ENCRYPTION_KEY` is the key for encrypting plugin secrets at
-rest. The key is validated on startup; plugin secret encryption uses
-it once enabled. Set it on every deployment so secrets are protected
-without a later config change.
+`EMDASH_ENCRYPTION_KEY` does not currently encrypt plugin secrets. If the variable is set, EmDash
+checks its format during startup, but plugin secret values remain unencrypted in the database.
 
-Generate a key and add the result to your environment:
+If you set the variable, generate a valid value and add the result to your environment:
 
 ```bash
 npx emdash secrets generate  # add the result to your environment
 ```
 
-The key is provided by you and never stored in the database; only
-encrypted ciphertext is. Back it up somewhere durable (a password
-manager, KMS, or your team's secret store) — losing it means losing
-every secret encrypted with it.
+The value is operator-provided and is not stored in the database. Losing it has no current
+data-recovery impact because no stored data depends on it. Treat the database and its backups as
+sensitive because they contain plaintext plugin secrets.
 
 ### Optional: stable-value overrides
 

docs/src/content/docs/deployment/secrets.mdx

@@ -11,7 +11,7 @@ EmDash uses a small set of secrets across previews, comments, authentication, st
 
 | Secret                                             | Source                            | Stored in                                | Lost key impact                                 |
 | -------------------------------------------------- | --------------------------------- | ---------------------------------------- | ----------------------------------------------- |
-| [`EMDASH_ENCRYPTION_KEY`](#the-encryption-key)     | Operator (`emdash secrets generate`) | Environment / Worker secret only         | Encrypted plugin secrets become unrecoverable (once encryption at rest ships) |
+| [`EMDASH_ENCRYPTION_KEY`](#the-encryption-key)     | Operator (`emdash secrets generate`) | Environment / Worker secret only         | No current data impact; EmDash only checks its format |
 | [Preview secret](#preview-secret)                  | Auto-generated (env override)     | `options` table (`emdash:preview_secret`) | Outstanding preview links stop working; new ones are fine |
 | [IP salt](#ip-salt)                                | Auto-generated (env override)     | `options` table (`emdash:ip_salt`)        | Past comment rate-limit continuity resets       |
 | [Session & API tokens](#session-and-api-tokens)    | Generated per session/token       | Session store / database (hashes only)   | Nothing — plaintext is never stored             |
@@ -24,9 +24,12 @@ EmDash uses a small set of secrets across previews, comments, authentication, st
 
 ## The encryption key
 
-`EMDASH_ENCRYPTION_KEY` is the site's key for encrypting plugin secrets at rest. It is **operator-provided and never stored in the database** — the database only ever holds ciphertext, so a leaked database backup does not expose the key.
+`EMDASH_ENCRYPTION_KEY` does not currently encrypt plugin secrets or any other stored data. If the
+variable is set, EmDash checks its format during startup. A malformed value produces an
+operator-facing log message, but the site continues to handle requests.
 
-Generate one and set it as an environment variable (or Worker secret):
+The following command generates a correctly formatted value. Store it in the runtime environment
+or as a Worker secret if your deployment uses this variable.
 
 ```bash
 npx emdash secrets generate
@@ -36,23 +39,11 @@ npx emdash secrets generate
 wrangler secret put EMDASH_ENCRYPTION_KEY
 ```
 
-The format is `emdash_enc_v1_` followed by 32 random bytes as unpadded base64url. The key is validated at runtime startup; a malformed value logs an operator-facing error without taking down request paths.
+The format is `emdash_enc_v1_` followed by 32 random bytes as unpadded base64url. The value is operator-provided and is not stored in the database. Losing it has no current data-recovery impact because no stored data depends on it.
 
 <Aside type="caution">
-	Back the key up somewhere durable (password manager, KMS, your team's secret store). Losing it
-	means losing every secret encrypted with it — the ciphertext in the database cannot be recovered.
-</Aside>
-
-### Rotation
-
-The variable accepts a comma-separated list of keys. The **first** entry is the primary and is used for new writes; all entries are tried for decryption. Every encrypted value is tagged with an 8-character key fingerprint (the _kid_, printable via `emdash secrets fingerprint <key>`), so the runtime picks the right key automatically.
-
-To rotate: generate a new key, prepend it to the list (`EMDASH_ENCRYPTION_KEY="new,old"`), redeploy, and drop the old key once existing values have been re-encrypted.
-
-<Aside type="note">
-	The encryption layer that consumes this key is not active yet — today the key is validated but
-	inert, and [plugin secrets](#plugin-secrets) are stored unencrypted. Set the key now so your
-	deployment is ready the moment plugin-secret encryption ships, without a config scramble.
+	Plugin secret values are stored as plaintext in the database. Setting
+	`EMDASH_ENCRYPTION_KEY` does not protect them. Restrict access to the database and its backups.
 </Aside>
 
 ## Generated site secrets
@@ -106,8 +97,7 @@ Settings a plugin declares with `type: "secret"` (API keys for email providers,
 <Aside type="caution">
 	Plugin secrets are currently stored **unencrypted** in the database. Anyone with database access
 	(including backups) can read them. Prefer scoped, revocable API keys, and treat database backups
-	as sensitive. Encryption at rest using [`EMDASH_ENCRYPTION_KEY`](#the-encryption-key) is planned;
-	setting the key today requires no migration later.
+	as sensitive.
 </Aside>
 
 - **Rotation:** rotate the key at the provider and paste the new value into the plugin's settings page. Takes effect immediately.
@@ -134,7 +124,6 @@ The separate `emdash-plugin` CLI (package `@emdash-cms/plugin-cli`) targets the
 
 | I want to…                              | Do this                                                                        |
 | --------------------------------------- | ------------------------------------------------------------------------------ |
-| Rotate the encryption key               | Prepend a new key: `EMDASH_ENCRYPTION_KEY="new,old"`, redeploy, drop old later |
 | Invalidate all preview links            | Delete the `emdash:preview_secret` option row (or change the env override)    |
 | Reset comment rate-limit hashing        | Change `EMDASH_IP_SALT` (or delete the `emdash:ip_salt` option row)           |
 | Revoke a leaked API token               | Admin → Users → API tokens → revoke, then create a replacement                |

docs/src/content/docs/guides/backups.mdx

@@ -5,32 +5,43 @@ description: Download site backups, schedule automatic backups to storage, and r
 
 import { Aside, Steps } from "@astrojs/starlight/components";
 
-EmDash gives you three layers of protection for your content, from zero-config point-in-time recovery on Cloudflare to downloadable archives you keep yourself.
+Use a JSON backup when you need an offline copy of selected content data. Use a raw database backup
+or point-in-time recovery when you need to restore the site.
 
 ## What's in a backup
 
-A backup contains everything needed to reconstruct your site's content:
+A JSON backup includes:
 
 - All content entries, including drafts, scheduled posts, and trashed items
-- Collection and field definitions (your content model)
-- Taxonomies and term assignments
-- Menus, widgets, sections, and SEO settings
-- Revisions and media metadata
-- Site settings (title, tagline, display preferences)
-
-Backups deliberately **exclude**:
-
-- User accounts, sessions, passkeys, and API tokens — auth data is neither portable nor safe in a downloadable file
-- Secrets (preview signing secret, plugin configuration)
-- Media binaries — the actual files live in your storage bucket (R2, S3, or local); a backup carries their metadata so references stay intact
+- Collection and field definitions that make up the content model
+- Taxonomy definitions, terms, and the terms assigned to each entry
+- Menus and menu items, sections, widget areas and widgets, SEO records, revision history, media
+  metadata, and database migration history
+- Site settings such as the title, tagline, URL, locale, logo, display preferences, social profiles,
+  and SEO defaults. These come from the `site:`, `emdash:site_`, and `emdash:locale` setting groups.
+
+It omits all other database tables, including:
+
+- User accounts, sessions, passkeys, OAuth data, API tokens, and other authentication data
+- Plugin storage and plugin settings, including plugin secrets
+- Comments and reactions, redirects and 404 logs, bylines, content relations and references, audit logs, rate limits, and scheduled-task state
+- Media folders, records of where media is used, incomplete or in-progress uploads, and the media
+  files themselves
+- Other site options, including the preview signing secret and backup schedule
 
 Backups are JSON files in the same snapshot format used by EmDash's preview system, versioned with the EmDash release that created them.
 
+<Aside type="caution">
+	EmDash does not implement restoring this JSON format. Do not rely on a JSON export as a recovery
+	point before a destructive operation. Use a raw database backup or point-in-time recovery instead.
+</Aside>
+
 ## One-click download
 
 Under **Settings → Backups** in the admin, the **Download backup** button generates a fresh backup and downloads it as a JSON file. Requires the admin role.
 
-This is the right tool before risky operations: bulk imports, schema changes, or major upgrades.
+The download is for inspection or custom migration tooling. Before bulk imports, schema changes, or
+major upgrades, create a restorable database backup using one of the options below.
 
 ## Automatic backups to storage
 
@@ -78,12 +89,6 @@ Time Travel keeps 30 days of history on the paid plan (7 days on free) with minu
 
 See the [D1 Time Travel documentation](https://developers.cloudflare.com/d1/reference/time-travel/) for details.
 
-<Aside type="tip">
-	Time Travel and EmDash backups complement each other: Time Travel is your disaster-recovery net
-	for the last 30 days; downloaded backups are user-holdable archives with no expiry that survive
-	account or database deletion.
-</Aside>
-
 ## Offsite database dumps
 
 For a complete SQL dump of the raw database (including users and auth tables), use Wrangler:
@@ -92,12 +97,15 @@ For a complete SQL dump of the raw database (including users and auth tables), u
 npx wrangler d1 export my-database --remote --output=backup.sql
 ```
 
-On Node deployments, the database is a single SQLite file — copy it while the server is stopped, or use `sqlite3 emdash.db ".backup backup.db"` for a consistent online copy.
+Restore that raw SQL dump with the following command:
+
+```bash
+npx wrangler d1 execute my-database --remote --file=backup.sql
+```
 
-## Restoring a backup
+On Node deployments, the database is a single SQLite file — copy it while the server is stopped, or use `sqlite3 emdash.db ".backup backup.db"` for a consistent online copy.
 
-Restoring from a backup JSON is intentionally not exposed as a one-click admin action yet — overwriting a live database deserves more friction than a button. Current options:
+## JSON restore
 
-- **Cloudflare:** use D1 Time Travel (above) for point-in-time restore.
-- **Full dumps:** import a `wrangler d1 export` dump with `npx wrangler d1 execute my-database --remote --file=backup.sql`.
-- **Backup JSON:** the format matches EmDash's snapshot format; a guided CLI restore is planned. Track [Discussion #142](https://github.com/emdash-cms/emdash/discussions/142).
+EmDash has no admin action, API endpoint, or CLI command for JSON restore. Use D1 Time Travel, a raw
+D1 SQL dump, or a copy of the SQLite database as described above.

docs/src/content/docs/guides/working-with-content.mdx

@@ -211,7 +211,7 @@ Perform actions on multiple entries at once:
 3. Select an action:
    - **Publish** - Set all selected to published
    - **Archive** - Set all selected to archived
-   - **Delete** - Permanently remove selected
+   - **Delete** - Move selected entries to Trash
 
 4. Confirm the action
 
@@ -254,7 +254,7 @@ When the publication date arrives, the content automatically becomes published.
 
 ## Deleting Content
 
-Delete content from the edit screen or content list:
+Delete content from the edit screen or content list to move it to Trash:
 
 ### From the Editor
 
@@ -272,9 +272,19 @@ Delete content from the edit screen or content list:
 
 3. Confirm the deletion
 
+### Restore from Trash
+
+1. Open the collection that contained the entry.
+
+2. Select the **Trash** tab above the content list.
+
+3. Find the entry and select its **Restore** action.
+
+The entry returns to the collection with its previous content and status.
+
 <Aside type="caution">
-	Deleted content is permanently removed and cannot be recovered. Consider archiving instead if you
-	might need the content later.
+	Administrators also see a separate **Permanently delete** action in Trash. Permanent deletion
+	cannot be undone.
 </Aside>
 
 ## Content API
@@ -291,37 +301,65 @@ Content-Type: application/json
 Authorization: Bearer YOUR_API_TOKEN
 
 {
-  "title": "My New Post",
+  "data": {
+    "title": "My New Post",
+    "content": [
+      {
+        "_type": "block",
+        "style": "normal",
+        "children": [{ "_type": "span", "text": "Post content goes here." }]
+      }
+    ]
+  },
   "slug": "my-new-post",
-  "content": "<p>Post content here</p>",
   "status": "draft"
 }
 ```
 
 ### Update Content
 
-The following request updates an existing post and publishes it:
+The following request updates an existing post. Put collection fields inside `data`. Pass the
+opaque `_rev` from the latest GET response to reject the write if the entry changed in the
+meantime:
 
 ```bash
 PUT /_emdash/api/content/posts/my-new-post
 Content-Type: application/json
 Authorization: Bearer YOUR_API_TOKEN
 
 {
-  "title": "Updated Title",
-  "status": "published"
+  "data": {
+    "title": "Updated Title"
+  },
+  "_rev": "REVISION_TOKEN"
+}
+```
+
+Updating content saves a draft revision. Publish that revision with the publish endpoint, using the
+new `_rev` returned by the update response:
+
+```bash
+POST /_emdash/api/content/posts/my-new-post/publish
+Content-Type: application/json
+Authorization: Bearer YOUR_API_TOKEN
+
+{
+  "_rev": "UPDATED_REVISION_TOKEN"
 }
 ```
 
 ### Delete Content
 
-The following request permanently deletes a post:
+The following request moves a post to Trash:
 
 ```bash
 DELETE /_emdash/api/content/posts/my-new-post
 Authorization: Bearer YOUR_API_TOKEN
 ```
 
+Restore it with `POST /_emdash/api/content/posts/my-new-post/restore`. Administrators can
+permanently delete it with `DELETE /_emdash/api/content/posts/my-new-post/permanent`.
+
 ## Translating Content
 
 When [i18n is enabled](/guides/internationalization/), you can create translations of any content entry.

docs/src/content/docs/plugins/creating-plugins/api-routes.mdx

@@ -114,7 +114,7 @@ routes: {
 
 Private routes require the `X-EmDash-Request: 1` CSRF header for cookie-authenticated requests. The admin UI sends it automatically; token-authenticated requests are exempt.
 
-To opt a route out of auth and CSRF, mark it `public: true`:
+To opt a route out of authentication, mark it `public: true`:
 
 ```typescript
 routes: {
@@ -130,7 +130,11 @@ routes: {
 ```
 
 <Aside type="caution">
-	Public routes skip authentication, scope, and CSRF entirely. Anyone on the internet can call them. Use `public: true` only for endpoints that need to accept external traffic — webhooks, public-facing search endpoints — and validate the input carefully.
+	A public route skips authentication and token scope checks, but not protection against cross-origin
+	browser requests. For requests that can change data, EmDash accepts a matching site `Origin` or the
+	`X-EmDash-Request: 1` header; a different or malformed `Origin` returns 403. Webhooks and other
+	non-browser clients usually omit `Origin` and remain allowed, so anyone can call a public route.
+	Validate all input and verify the service's signature or token when available.
 </Aside>
 
 ### The authenticated caller