Prepare ForgeFlow for public release

docs/DEPLOYMENT_MIGRATION_EXAMPLE.md

@@ -0,0 +1,63 @@
+# Deployment migration example
+
+This example shows how to bring an existing Git-backed Docker or Unraid application under ForgeFlow control without exposing or overwriting runtime data.
+
+Use synthetic names and values while testing. Replace them with your own repository, server and paths only in ForgeFlow's local configuration; do not commit credentials or environment-specific diagnostics.
+
+## 1. Establish the authoritative repository
+
+Before deploying, verify that the server checkout and Gitea repository represent the same application:
+
+- compare the complete 40-character commit SHA;
+- confirm the configured remote belongs to the intended Gitea origin and repository;
+- preserve the root `.git` directory for exact-SHA verification and rollback;
+- resolve any remote URL mismatch explicitly instead of silently rewriting it.
+
+ForgeFlow blocks deployment when the existing origin conflicts with the selected repository unless the user explicitly approves alignment.
+
+## 2. Protect runtime data
+
+Typical persistent paths include:
+
+```text
+.env
+appdata/
+config/
+data/
+logs/
+compose.override.yml
+```
+
+Keep those paths outside the tracked deployment payload and add runtime-only directories to `.dockerignore` when they are not build inputs. ForgeFlow uses a controlled Git reset without `git clean`, but the repository's own Compose and ignore rules remain authoritative.
+
+## 3. Reuse the maintained Compose definition
+
+Prefer the repository's existing `compose.yml` or `docker-compose.yml` when it already defines ports, volumes, device mappings, labels and health checks. These application-specific settings should be reviewed and versioned with the application rather than regenerated during deployment.
+
+## 4. Handle nested repositories separately
+
+A historical checkout such as `source/` may contain another `.git` directory. Treat this as a migration warning:
+
+1. verify that the root Compose file builds from the intended root;
+2. back up the application folder;
+3. stop modifying the nested checkout;
+4. rename it temporarily;
+5. rebuild and verify the application from the root checkout;
+6. remove the legacy copy only after rollback has also been tested.
+
+ForgeFlow reports nested repositories but does not delete them automatically.
+
+## 5. Recommended profile
+
+```text
+Provider:       SSH / Unraid
+Server folder:  example-app
+Branch:         main
+Compose mode:   Repository/server Compose
+Compose file:   compose.yml
+Clone URL:      a Git URL reachable from the server
+Healthcheck:    the application's existing health endpoint
+Preserve paths: .env, appdata, config, data, logs, compose.override.yml
+```
+
+Complete a preflight first, deploy one exact commit, verify both the live SHA and runtime health, and test rollback before treating the migration as production-ready.