docs: add docs for hooks + extensions (#16073)

docs/hooks/index.md

@@ -46,6 +46,11 @@ project hook (identified by its name and command), but it is **your
 responsibility** to review these hooks (and any installed extensions) before
 trusting them.
 
+> [!NOTE] Extension hooks are subject to a mandatory security warning and
+> consent flow during extension installation or update if hooks are detected.
+> You must explicitly approve the installation or update of any extension that
+> contains hooks.
+
 See [Security Considerations](best-practices.md#using-hooks-securely) for a
 detailed threat model and mitigation strategies.
 
@@ -444,7 +449,8 @@ numbers run first):
 2.  **User settings:** `~/.gemini/settings.json`
 3.  **System settings:** `/etc/gemini-cli/settings.json`
 4.  **Extensions:** Internal hooks defined by installed extensions (lowest
-    priority)
+    priority). See [Extensions documentation](../extensions/index.md#hooks) for
+    details on how extensions define and configure hooks.
 
 #### Deduplication and shadowing
 

docs/hooks/writing-hooks.md

@@ -1018,6 +1018,24 @@ const SECRET_PATTERNS = [
 ];
 ```
 
+## Packaging as an extension
+
+While project-level hooks are great for specific repositories, you might want to
+share your hooks across multiple projects or with other users. You can do this
+by packaging your hooks as a [Gemini CLI extension](../extensions/index.md).
+
+Packaging as an extension provides:
+
+- **Easy distribution:** Share hooks via a git repository or GitHub release.
+- **Centralized management:** Install, update, and disable hooks using
+  `gemini extensions` commands.
+- **Version control:** Manage hook versions separately from your project code.
+- **Variable substitution:** Use `${extensionPath}` and `${process.execPath}`
+  for portable, cross-platform scripts.
+
+To package hooks as an extension, follow the
+[extensions hook documentation](../extensions/index.md#hooks).
+
 ## Learn more
 
 - [Hooks Reference](index.md) - Complete API reference and configuration