docs/DEPLOY.md

@@ -176,11 +176,30 @@ registry is orphaned and nothing reads it.
    variable, and set `UNLEASH_URL` to `http://<UNLEASH_IP>:4242/api`.
 5. Redeploy the application stacks.
 
+### Adding a flag to Unleash
+
+**Unleash does not create flags by itself.** The SDK reads definitions from the
+server and never registers anything, and metrics for a flag the server has
+never heard of are discarded. So a flag declared in `backend/flags.py` will be
+evaluated on every request, stay `False` forever, and never appear in the UI
+until someone creates it there by hand.
+
+For each flag in the registry, create one in Unleash with:
+
+- **Name** — character for character what `backend/flags.py` declares.
+  snake_case, no hyphens or spaces. A typo produces a flag that looks correct
+  in the UI and is read by nothing.
+- **Type** — Release. No strategies, constraints or variants: these are plain
+  on/off switches, by design.
+
 ### Turning a feature on
 
-Toggle the flag in the environment you want. Flags appear in the Unleash UI
-after the backend has evaluated them once, so a newly declared flag shows up
-shortly after the deploy that introduced it.
+Toggle the flag in the environment matching the stack you mean: **development**
+for staging, **production** for prod. The token in each stack is scoped to one
+environment, so toggling the other one has no visible effect.
+
+The SDK refreshes every 15 seconds, so the API reflects the change almost at
+once; the pages follow on their own schedule, below.
 
 A flip reaches school pages within about five minutes and place pages within
 the hour. Next's ISR does the propagating — it revalidates a route at the