Update documentation for git structure and special directories

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/CLAUDE.dist.md

@@ -133,27 +133,25 @@ This keeps code simple and straightforward - the Visual Basic philosophy.
 
 ## GIT WORKFLOW
 
-### 🔴 CRITICAL: Framework Repository is READ-ONLY
+### 🔴 CRITICAL: Framework Code is READ-ONLY
 
-**AI AGENTS: You must NEVER modify files in `/var/www/html` or commit to `/var/www/html/.git`**
+**AI AGENTS: You must NEVER modify files in `/var/www/html/system/` or commit to the framework submodule**
 
-The framework repository is equivalent to the Linux kernel or node_modules - it's external code managed by upstream developers. Just as you wouldn't commit to the Linux kernel when asked "what file
+The framework code in `/var/www/html/system/` is managed by the RSpade team. It's equivalent to the Linux kernel or node_modules - external code that you don't modify directly.
-is this?", you must never commit to the framework repo.
 
-**Forbidden actions in `/var/www/html`:**
+**Forbidden actions in `/var/www/html/system/`:**
-- ❌ NEVER edit files (except `/var/www/html/rsx/*`)
+- ❌ NEVER edit framework files
-- ❌ NEVER run `git add`, `git commit`, `git rm`
+- ❌ NEVER commit framework changes
-- ❌ NEVER remove files from git tracking
+- ❌ NEVER remove framework files from git tracking
-- ❌ NEVER stage changes
+- ❌ NEVER stage framework changes
 - ❌ NEVER fix issues in framework code (report them instead)
-- ❌ NEVER answer questions by modifying files
 
 **Only exception:** Updating framework via `php artisan rsx:framework:pull` (this is automated and safe)
 
-### Two Git Repositories
+### Git Repository Structure
 
-**Framework repo:** `/var/www/html/.git` (read-only, managed by RSpade team - DO NOT TOUCH)
+**Application repo:** `/var/www/html/.git` (your code, you control)
-**Application repo:** `/var/www/html/rsx/.git` (your code, you control)
+**Framework submodule:** `/var/www/html/system/` (read-only, managed by RSpade team - DO NOT TOUCH)
 
 ### Commit Discipline
 
@@ -161,7 +159,23 @@ is this?", you must never commit to the framework repo.
 
 ### Working Directory Rules
 
-**ALWAYS work from `/var/www/html/rsx` for application code:**
+**All code changes shall be made in `/var/www/html/rsx` for application code.** Do not make any changes outside of `/var/www/html/rsx`.
+
+**Run artisan commands from `/var/www/html`:**
+
+```bash
+cd /var/www/html
+php artisan rsx:check   # ✅ Framework commands run from here
+```
+
+**Commit from `/var/www/html`:**
+
+```bash
+cd /var/www/html    # ✅ CORRECT
+git add -A
+git commit -m "Snapshot: description"
+git push origin master
+```
 
 
 ---
@@ -227,7 +241,9 @@ Enforced automatically by `rsx:check`.
 
 ### Directory Structure
 
-**CRITICAL**: The framework uses a split directory structure:
+**CRITICAL**: The framework uses a split directory structure.
+
+**Important**: The structure shown below is **conventional, not mandatory**. Files in `/rsx/` are path-agnostic (referenced by name, not path) and can be organized however you prefer. The only special directories with framework-enforced behavior are `resource/` and `public/` (explained below).
 
 ```
 /var/www/html/                     # Project root
@@ -264,16 +280,49 @@ Enforced automatically by `rsx:check`.
 
 **DO NOT MODIFY** - Framework runtime that executes your RSX application.
 
-### /resource/ and /vendor/ Directories
+### Special Directory Names - Path-Agnostic Rules
 
-**Excluded from automatic processing:**
+**These rules apply ANYWHERE in `/rsx/`**, not just at specific paths:
 
-- **`/resource/`** - External code not following RSX conventions
+#### `resource/` Directories (Framework-Ignored)
-- **`/vendor/`** - Composer dependencies
 
-Not subject to class uniqueness or filename conventions. Suitable for third-party code.
+**ANY directory named `resource/` is ignored by the framework** - files will not be loaded or processed.
 
-**Note**: Only files in `/rsx/` (excluding `/resource/` and `/vendor/`) and the core framework in `/system/app/RSpade/` are automatically discovered and processed by RSpade.
+Use for:
+- Helper PHP files not following RSX conventions
+- External reference files and documentation
+- Third-party code that doesn't fit RSX patterns
+- Any files you want to store but not execute
+
+Examples:
+- `/rsx/resource/` - Project-level resources
+- `/rsx/app/module/resource/` - Module-specific resources
+- `/rsx/resource/config/` - Configuration overrides (exception: config files ARE processed)
+
+**Exception**: `/rsx/resource/config/` files ARE processed for configuration overrides.
+
+#### `public/` Directories (Web-Accessible)
+
+**ANY directory named `public/` is:**
+- Ignored by framework (files not loaded/processed)
+- Exposed via HTTP (downloadable by browsers)
+- Served with caching headers (5min default, 30 days with `?v=` query string)
+
+Use for:
+- Static files (images, PDFs, downloads)
+- Uploaded user content
+- Any files that need direct HTTP access
+
+Examples:
+- `/rsx/public/` - Project-level static files (accessible at `/filename`)
+- `/rsx/app/module/public/` - Module-specific static files
+- `/rsx/public/public_ignore.json` - Patterns blocked from HTTP access
+
+**Security**: Use `public_ignore.json` to block sensitive files like README.md from HTTP access.
+
+#### `vendor/` Directory
+
+**`/vendor/` is for Composer dependencies only** - excluded from automatic processing.
 
 ---