diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index caedbdd..e67ccec 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -170,6 +170,15 @@ is a dev-only escape hatch.
 ## Conventions
 
 - **Versioning:** semver in `VERSION`. Bump before building; `latest.json` carries it.
+- **App tools are self-contained** (preferred): put the declaration in
+  `containers/<app>/tools/<app>.tools.json` and each function in
+  `containers/<app>/tools/<app>_<tool_id>.sh` (function `app<App><PascalToolId>`).
+  Both are picked up automatically — the container scan live-sources the `.sh`, and
+  `webui_tools.sh` auto-merges the `.tools.json`. No central edits, no array regen →
+  the app is a true drop-in. (The legacy central style — an entry in the
+  `webui_tools.sh` heredoc + the function under `scripts/app/containers/<app>/` —
+  still works; both coexist, so apps migrate one at a time. Only *declared tools*
+  move; shared logic helpers like `<app>_auth.sh` stay in `scripts/app/`.)
 - **New runtime script?** Add it under `scripts/<area>/…` and run
   `scripts/source/files/generate_arrays.sh run` so it's sourced (build/standalone
   tooling under `scripts/release` and `scripts/system` is intentionally excluded).