From 5fbbfc32b422dcef8675b8e7e05c04f5b063345f Mon Sep 17 00:00:00 2001
From: Alexander Don <alexdon20022@gmail.com>
Date: Mon, 30 Mar 2026 22:18:45 +0300
Subject: [PATCH] Document extra_applications requirement for external modules

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 AGENTS.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 16ff86d97..91bcdb26d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -170,6 +170,18 @@ Built-in Dashboard Features
 
 ## Guidelines
 
+### External Module Auto-Discovery
+
+When extracting modules to standalone packages, the package's `mix.exs` **must** include `:phoenix_kit` in `extra_applications`:
+
+```elixir
+def application do
+  [extra_applications: [:logger, :phoenix_kit]]
+end
+```
+
+Without this, `PhoenixKit.ModuleDiscovery` won't find the module and routes will return 404. See `phoenix_kit_hello_world` for the template.
+
 ### PhoenixKit Layout Guidelines
 
 PhoenixKit uses its own layout wrapper component instead of the standard Phoenix `Layouts.app`: