From 97e7b59910392592d976f0e7ad3bc6ae3c6a5c6c Mon Sep 17 00:00:00 2001
From: eding <edin.grech@gmail.com>
Date: Wed, 16 Sep 2026 08:56:28 +0200
Subject: [PATCH] docs: explain legacy app registration migration

---
 docs/operations.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/operations.md b/docs/operations.md
index 36c9c4c..eef58cf 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -63,6 +63,10 @@ registration PR. The registration is stored in
 `base/tekton/apps/<app>.yaml`; Flux loads the source-owned `.tekton` path and
 the generic EventListener dispatches by Forgejo repository name.
 
+Existing registrations are never overwritten. Move a legacy source registration
+to its canonical source in a separate reviewed cluster-repository PR before
+onboarding that application.
+
 After Flux reports the app Kustomization Ready, use Forgejo's hook test endpoint
 against a non-`main` ref and inspect the resulting PipelineRun. The command and
 read-only checks are in [Webhook Smoke Test](#webhook-smoke-test).