From f217c4b3b0a84b660b897638dc1969a0988d2ed1 Mon Sep 17 00:00:00 2001
From: SandObserver <260779319+SandObserver@users.noreply.github.com>
Date: Sat, 10 Oct 2026 16:52:52 -0400
Subject: [PATCH] Describe settings restore, the export filename and the import
 fixes

---
 .../docs/docs/import-export/backup-and-restore.md    | 10 ++++++++--
 src/content/docs/docs/import-export/migrating.md     | 12 ++++++++++--
 src/content/docs/docs/troubleshooting.md             |  4 +++-
 3 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/src/content/docs/docs/import-export/backup-and-restore.md b/src/content/docs/docs/import-export/backup-and-restore.md
index 802f507..e23b1d6 100644
--- a/src/content/docs/docs/import-export/backup-and-restore.md
+++ b/src/content/docs/docs/import-export/backup-and-restore.md
@@ -9,7 +9,7 @@ Stackyard's whole configuration is one JSON file. <span class="sy-btn sy-btn--gh
 
 ## Export
 
-Downloads your configuration as `dashboard-apps.json`, containing apps, folders, widgets, badges, and settings. Use it as a backup, or to move an install to another machine.
+Downloads your configuration as `stackyard-config.json`, containing apps, folders, widgets, badges, and settings. Use it as a backup, or to move an install to another machine.
 
 :::caution
 Stored secrets are never included in an export. API keys, tokens and passwords must be entered again after importing.
@@ -17,7 +17,13 @@ Stored secrets are never included in an export. API keys, tokens and passwords m
 
 ## Import
 
-Reads a file produced by Export. Stackyard shows how many items will be added, updated and deleted, and asks you to confirm before writing anything. A file matching your current configuration changes nothing and says so.
+Reads a file produced by Export. Stackyard shows how many items will be added, updated and deleted, says when settings will be replaced too, and asks you to confirm before writing anything. A file matching your current configuration changes nothing and says so.
+
+An import replaces apps, folders, widgets, badges and settings. The password is never replaced. An export from an older release is upgraded as it is imported.
+
+If the file names an uploaded wallpaper that this install does not hold, the current background stays.
+
+After an import that replaces settings, reload the page before you change any settings. Until then, Settings shows the values from before the import.
 
 ## What the volumes hold
 
diff --git a/src/content/docs/docs/import-export/migrating.md b/src/content/docs/docs/import-export/migrating.md
index f11717e..5fd2edb 100644
--- a/src/content/docs/docs/import-export/migrating.md
+++ b/src/content/docs/docs/import-export/migrating.md
@@ -11,6 +11,12 @@ Stackyard reads gethomepage and Dashy configuration files, so you do not have to
 
 Links and folders. An app in the source becomes an app tile, and a group or section becomes a folder.
 
+A link written as a host and port, such as `plex.lan:32400`, is imported with `http://` in front.
+
+Icons come across when they are a [dashboard-icons](https://github.com/homarr-labs/dashboard-icons) name or an icon link on `cdn.jsdelivr.net`.
+
+A Homepage `siteMonitor` or a Dashy status check becomes the app's health check. A Dashy check that allows insecure certificates is imported with certificate checking on, unless you tick **Allow self-signed certificate** in the import preview.
+
 :::note
 This is one way. It does not keep the two in sync, and it writes nothing back.
 :::
@@ -19,13 +25,15 @@ This is one way. It does not keep the two in sync, and it writes nothing back.
 
 A widget in the source becomes a plain app tile, never a Stackyard widget. The two projects model widgets differently, so there is nothing to translate.
 
-Descriptions, abbreviations, tags, and per-item colours are dropped. Icons are not carried over either, because Stackyard resolves icons by name. See [Apps and folders](/docs/apps-and-folders/).
+Descriptions, abbreviations, tags, and per-item colours are dropped. Icon fonts, emoji, other icon links and paths into the other dashboard's files are dropped too. See [Apps and folders](/docs/apps-and-folders/).
+
+A health-check address that is only a path, or that the other dashboard resolves from its own environment, is dropped. The app imports without that check.
 
 ## What is skipped
 
 An entry is skipped when it has no label, has no link, or its link is not safe to follow. Relative links are skipped, because they have no meaning outside the dashboard that wrote them, as are values the other dashboard resolves from its own environment.
 
-A file with more than 5,000 entries is refused, and nothing is imported.
+A file with more than 5,000 entries is refused, and nothing is imported. So is a file whose YAML merge keys (`<<`) expand too far.
 
 Stackyard reports how many apps and folders were imported, and lists what it could not import and why.
 
diff --git a/src/content/docs/docs/troubleshooting.md b/src/content/docs/docs/troubleshooting.md
index 6036165..ce4a8ad 100644
--- a/src/content/docs/docs/troubleshooting.md
+++ b/src/content/docs/docs/troubleshooting.md
@@ -290,6 +290,7 @@ Messages shown in the admin, and what each one means.
 | `Wallpaper failed: <reason>` | The image was not stored. The link was unreachable, the file is not a JPEG, PNG, WebP, AVIF or GIF, or it is over 16 MB. |
 | `Set a password before turning authentication on.` | Authentication needs a password to exist first. |
 | `Some items in the folder <id> are not in the file.` | A folder in the imported config lists apps that are not in the same file. Usually a hand-edited or partly merged export. |
+| `Stackyard cannot read the list of items in the folder <id>.` | A folder in the imported config lists its contents as something other than a list of item ids. Nothing was saved. |
 | `Two items share the id <id>. Each item needs its own id.` | The imported config has two entries with the same id. Nothing was saved. |
 | `The item <id> has a link that is not allowed. Links must use http or https.` | A link in the imported config uses a scheme such as `javascript:` or `data:`. Nothing was saved. |
 | `That file is not a Stackyard export.` | The imported file is not JSON, or has no `items` list. |
@@ -301,9 +302,10 @@ Messages shown in the admin, and what each one means.
 | `Something answered there, but it is not a Docker socket proxy.` | The address answered, but not with a Docker API version. |
 | `Saving is turned off in the live demo.` | The public demo is read-only. |
 | `Nothing to import. The file matches your current config.` | The imported file is identical to what is already stored. |
+| `Settings restored. Reload the page before changing any settings.` | An import replaced settings. Settings still shows the values from before it until the page reloads. |
 | `Icon catalogues could not be reached` | No catalogue answered while searching. The field still takes a full URL or an upload. |
 | `<file> is not a gethomepage or Dashy config.` | Only those two formats are recognised. See [Import](/docs/import-export/migrating/). |
-| `<file> has too many entries to import.` | The file has more than 5,000 entries. Nothing was imported. See [Import](/docs/import-export/migrating/#what-is-skipped). |
+| `<file> has too many entries to import.` | The file has more than 5,000 entries, or its merge keys expand too far. Nothing was imported. See [Import](/docs/import-export/migrating/#what-is-skipped). |
 | `(may be out of date)` | A stale reading. The last poll failed and the previous value is shown. |
 
 ## Not actually broken