diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..b3478cda9
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,43 @@
+# Project-Specific Documentation
+
+**PURPOSE**: This file is for your application-specific documentation, development notes, and project context that AI/LLM assistants should be aware of when working on your codebase.
+
+## Framework Documentation Location
+
+RSpade framework documentation for AI/LLM assistants is located at:
+- **`~/.claude/CLAUDE.md`** - Framework documentation (updated with `php artisan rsx:framework:pull`)
+- **`./docs/CLAUDE.dist.md`** - Same content, read-only, replaced during framework updates
+
+**DO NOT modify `./docs/CLAUDE.dist.md`** - it will be replaced during framework updates.
+
+## This File (CLAUDE.md)
+
+Use this file to document:
+- **Project-specific context** - Business domain, purpose, architectural decisions
+- **Custom conventions** - Team-specific patterns, naming conventions, coding standards
+- **Development notes** - Setup instructions, deployment procedures, known issues
+- **Module documentation** - Descriptions of your custom modules and their purposes
+- **API integrations** - Third-party services, authentication details, endpoints
+- **Database schema notes** - Important relationships, migration strategies, data models
+
+This file is **NOT managed by the framework** and will persist across framework updates.
+
+---
+
+## Example Documentation Structure
+
+### Project Overview
+[Describe what this application does and who it's for]
+
+### Architecture Decisions
+[Document key architectural choices and why they were made]
+
+### Custom Modules
+[List and describe your RSX modules in /rsx/app/]
+
+### Development Workflow
+[Team-specific practices, git workflow, deployment process]
+
+### Environment Setup
+[Project-specific setup requirements beyond standard RSpade installation]
+
diff --git a/bin/framework-pull-upstream.sh b/bin/framework-pull-upstream.sh
index 81d2d9269..5416d8c23 100755
--- a/bin/framework-pull-upstream.sh
+++ b/bin/framework-pull-upstream.sh
@@ -111,6 +111,12 @@ fi
 echo "Branch: $CURRENT_BRANCH → $UPSTREAM_BRANCH"
 echo ""
 
+# Remove read-only attribute from CLAUDE.dist.md before update
+if [ -f "docs/CLAUDE.dist.md" ]; then
+    echo "→ Removing read-only attribute from docs/CLAUDE.dist.md..."
+    chmod u+w docs/CLAUDE.dist.md 2>/dev/null || true
+fi
+
 # Fetch updates first (before verifying branch exists)
 echo "Fetching updates from rspade_upstream..."
 if ! git fetch rspade_upstream 2>&1; then
@@ -391,6 +397,14 @@ else
     echo ""
 fi
 
+# Set read-only attribute on CLAUDE.dist.md after successful update
+if [ -f "docs/CLAUDE.dist.md" ]; then
+    echo "→ Setting read-only attribute on docs/CLAUDE.dist.md..."
+    chmod u-w docs/CLAUDE.dist.md 2>/dev/null || true
+    echo "  ✓ Framework documentation marked read-only"
+    echo ""
+fi
+
 echo "✅ Framework update complete"
 echo ""
 
diff --git a/docs/CLAUDE.dist.md b/docs/CLAUDE.dist.md
old mode 100755
new mode 100644
index 67c3937a7..ecfe96120
--- a/docs/CLAUDE.dist.md
+++ b/docs/CLAUDE.dist.md
@@ -1,3 +1,27 @@
+<!--
+═══════════════════════════════════════════════════════════════════════════
+⚠️  READ-ONLY FRAMEWORK DOCUMENTATION
+═══════════════════════════════════════════════════════════════════════════
+
+This file contains RSpade framework documentation for AI/LLM assistants and is
+maintained by the framework developers. It is marked read-only and will be
+REPLACED during framework updates via `php artisan rsx:framework:pull`.
+
+DO NOT modify this file directly. Any changes you make will be lost during the
+next framework update.
+
+For application-specific documentation and project context:
+→ Edit the CLAUDE.md file in your project root
+→ That file is NOT managed by the framework and persists across updates
+
+This separation ensures:
+• Framework documentation stays current with updates
+• Your project-specific documentation is preserved
+• AI assistants have access to both framework and application context
+
+═══════════════════════════════════════════════════════════════════════════
+-->
+
 # RSpade Framework - AI/LLM Development Guide
 
 **PURPOSE**: This document provides comprehensive directives for AI/LLM assistants developing RSX applications with the RSpade framework.
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 84de598f5..8e890532c 100755
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -25,10 +25,10 @@ The `--recurse-submodules` flag automatically initializes and clones the `system
 
 1. **Copy environment configuration:**
    ```bash
-   cp system/.env.dist system/.env
+   cp .env.dist .env
    ```
 
-2. **Configure your database** in `system/.env`:
+2. **Configure your database** in `.env`:
    ```
    DB_CONNECTION=mysql
    DB_HOST=127.0.0.1