docs: document site file generation

Author: djalmaaraujo

docs/CLAUDE.md

@@ -0,0 +1,21 @@
+# CLAUDE.md
+
+Guidance for AI agents working inside the `docs/` Rails app.
+
+## LLM and Sitemap Files
+
+The docs app publishes these root files from `public/`:
+
+- `/llms.txt`
+- `/llms-full.txt`
+- `/sitemap.xml`
+
+Their source of truth is `app/lib/site_files.rb`.
+
+Whenever you add, remove, or rename a public route, controller action, or view, check whether it creates or changes a public URL. If it does, update `SiteFiles` and run:
+
+```bash
+bin/rails site_files:generate
+```
+
+Before finishing, review the diff for `public/llms.txt`, `public/llms-full.txt`, and `public/sitemap.xml`. These generated files should be committed with the route/controller/view change so deployed apps expose the updated root files without a manual step.

docs/README.md

@@ -27,12 +27,19 @@ This workflow allows you to iterate quickly on components while maintaining the
 
 ## Site Files
 
-The docs app serves `/llms.txt`, `/llms-full.txt`, and `/sitemap.xml` through Rails routes backed by `SiteFiles`.
+The docs app serves `/llms.txt`, `/llms-full.txt`, and `/sitemap.xml` from `public/`.
+Those files are generated from `app/lib/site_files.rb`, which is the source of truth for the LLM link map and sitemap URL list.
 
-To refresh static copies in `public/`, run:
+After changing public routes, controllers, or views, update `SiteFiles` if the change adds, removes, or renames a public URL. Then refresh the generated files:
 
 ```bash
 bin/rails site_files:generate
 ```
 
-Set `SITE_FILES_OUTPUT_DIR=tmp/site_files` to generate into a temporary directory instead.
+Review the resulting diff in:
+
+- `public/llms.txt`
+- `public/llms-full.txt`
+- `public/sitemap.xml`
+
+Set `SITE_FILES_OUTPUT_DIR=tmp/site_files` to generate into a temporary directory instead of overwriting `public/`.