Fix bin/publish: copy docs.dist from project root

Fix bin/publish: use correct .env path for rspade_system
Fix bin/publish script: prevent grep exit code 1 from terminating script

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

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

app/RSpade/Upstream/CLAUDE.md

@@ -0,0 +1,85 @@
+# Upstream Refactor Tracking System
+
+## Purpose
+
+This system tracks framework refactoring operations (class renames, method renames) performed on files in `/app/RSpade` so that when users update their framework copy, these refactors can be automatically applied to their RSX application code.
+
+## How It Works
+
+### Recording Refactors (Current Implementation)
+
+When framework developers execute refactoring commands that modify files in `/app/RSpade`:
+
+- `rsx:refactor:rename_php_class OldClass NewClass`
+- `rsx:refactor:rename_php_class_function ClassName old_method new_method`
+
+The command calls `UpstreamRefactorLog::log_refactor()` which:
+
+1. Records the full command to a `refactor.list` file in the same directory as the refactored file
+2. Includes timestamp for tracking when the refactor was performed
+3. Only logs refactors for files in `app/RSpade/` (framework code, not user code)
+
+Example `refactor.list` file in `/app/RSpade/Core/`:
+```
+[2025-10-07 02:00:00] rsx:refactor:rename_php_class Old_Manifest New_Manifest
+[2025-10-07 02:15:30] rsx:refactor:rename_php_class_function Rsx get_route get_current_route
+```
+
+### Applying Refactors (Future Implementation)
+
+**Command**: `php artisan rsx:refactor:apply_upstream_refactors`
+
+This command will:
+
+1. **Scan all `refactor.list` files** in `/app/RSpade` directories
+2. **Read previously applied refactors** from `/rsx/.upstream_refactors.list`
+3. **Diff the operations** to find new refactors that haven't been applied yet
+4. **Execute each new refactor** with a special `--rsx-only` flag that:
+   - Only modifies files in `/rsx/` directory (user application code)
+   - Does NOT modify the source class in `/app/RSpade/`
+   - Does NOT modify other framework files
+5. **Record executed refactors** to `/rsx/.upstream_refactors.list`
+6. **Commit to git** so changes persist across framework updates
+
+### Example Workflow
+
+**Framework Developer** (working in `/app/RSpade`):
+```bash
+# Rename a core framework class
+php artisan rsx:refactor:rename_php_class Old_Controller New_Controller
+
+# This automatically logs to /app/RSpade/Core/Controller/refactor.list:
+# [2025-10-07 02:00:00] rsx:refactor:rename_php_class Old_Controller New_Controller
+```
+
+**End User** (after pulling framework update):
+```bash
+# Apply all new framework refactors to their application
+php artisan rsx:refactor:apply_upstream_refactors
+
+# Command finds new refactor operations in app/RSpade/*/refactor.list
+# Applies them ONLY to files in /rsx/ directory
+# Records applied operations to /rsx/.upstream_refactors.list
+```
+
+## File Locations
+
+- **Refactor logs**: `/app/RSpade/{directory}/refactor.list` (distributed with framework)
+- **Applied refactors**: `/rsx/.upstream_refactors.list` (user-specific, committed to user's git)
+- **Implementation**: `/app/RSpade/UpstreamRefactorLog.php`
+
+## Benefits
+
+1. **Seamless framework updates** - Users automatically get class/method renames applied to their code
+2. **No breaking changes** - Refactors are applied incrementally as users update
+3. **Trackable history** - Both framework and user have logs of what was refactored
+4. **Git-friendly** - Applied refactors are committed, preventing re-application
+5. **Safe isolation** - Framework refactors never touch user code until explicitly applied
+
+## Future Enhancements
+
+- `--dry-run` flag to preview refactors before applying
+- `--skip` flag to skip specific refactors
+- `--force` flag to re-apply already-applied refactors
+- Conflict detection when user has customized framework classes
+- Rollback capability for problematic refactors

app/RSpade/Upstream/RefactorLog.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace App\RSpade\Upstream;
+
+/**
+ * Tracks framework refactoring operations for future migration to user projects
+ *
+ * When framework developers rename classes or methods in /app/RSpade, these operations
+ * are logged to refactor.list files. Future rsx:refactor:apply_upstream_refactors
+ * command will replay these on user projects when they update the framework.
+ */
+class RefactorLog
+{
+    /**
+     * Log a refactor operation to the refactor.list file
+     *
+     * @param string $command The artisan command that was executed
+     * @param string $source_file The framework file that was refactored (relative to /var/www/html)
+     */
+    public static function log_refactor(string $command, string $source_file): void
+    {
+        $base_path = base_path();
+
+        // Ensure source file is relative to base path
+        if (str_starts_with($source_file, $base_path)) {
+            $source_file = substr($source_file, strlen($base_path) + 1);
+        }
+
+        // Only log refactors for files in app/RSpade
+        if (!str_starts_with($source_file, 'app/RSpade/')) {
+            return;
+        }
+
+        // Get directory of the refactored file
+        $dir = dirname($base_path . '/' . $source_file);
+        $refactor_list_file = $dir . '/refactor.list';
+
+        // Create log entry with timestamp
+        $timestamp = date('Y-m-d H:i:s');
+        $log_entry = "[$timestamp] $command\n";
+
+        // Append to refactor.list file
+        file_put_contents($refactor_list_file, $log_entry, FILE_APPEND);
+    }
+
+    /**
+     * Check if a file has been tracked for refactoring
+     *
+     * @param string $file_path Path to check
+     * @return bool
+     */
+    public static function has_refactor_log(string $file_path): bool
+    {
+        $dir = dirname($file_path);
+        return file_exists($dir . '/refactor.list');
+    }
+
+    /**
+     * Get all refactor operations for a directory
+     *
+     * @param string $directory_path Directory to check
+     * @return array Array of refactor commands
+     */
+    public static function get_refactor_operations(string $directory_path): array
+    {
+        $refactor_list_file = rtrim($directory_path, '/') . '/refactor.list';
+
+        if (!file_exists($refactor_list_file)) {
+            return [];
+        }
+
+        $contents = file_get_contents($refactor_list_file);
+        $lines = explode("\n", trim($contents));
+
+        $operations = [];
+        foreach ($lines as $line) {
+            if (empty($line)) {
+                continue;
+            }
+
+            // Parse: [2025-10-07 02:00:00] command here
+            if (preg_match('/^\[(.*?)\]\s+(.+)$/', $line, $matches)) {
+                $operations[] = [
+                    'timestamp' => $matches[1],
+                    'command' => $matches[2],
+                ];
+            }
+        }
+
+        return $operations;
+    }
+}