From 0e19c811e3bab938450fdbbb3b63d75ecf3235a2 Mon Sep 17 00:00:00 2001
From: root <root@rspade.framework.dev.hanson.xyz>
Date: Thu, 20 Nov 2025 00:30:33 +0000
Subject: [PATCH] Fix Ajax endpoint documentation - remove incorrect success
 wrapper pattern
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/CLAUDE.dist.md | 62 ++++++++++++++++++++++-----------------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/docs/CLAUDE.dist.md b/docs/CLAUDE.dist.md
index bf415c920..2e10d0cff 100644
--- a/docs/CLAUDE.dist.md
+++ b/docs/CLAUDE.dist.md
@@ -963,47 +963,47 @@ Details: `php artisan rsx:man file_upload`
 
 ## AJAX ENDPOINTS
 
+**Return data directly - framework auto-wraps as `{success: true, data: ...}`**
+
 ```php
 #[Ajax_Endpoint]
-public static function get_data(Request $request, array $params = [])
-{
-    return ['success' => true, 'data' => ...];
+public static function fetch_client(Request $request, array $params = []) {
+    $client = Client_Model::find($params['id']);
+    if (!$client) throw new \Exception('Not found');
+    return $client;  // ✅ Return data directly
 }
 ```
 
-```javascript
-const result = await Demo_Controller.get_data({user_id: 123});
+**❌ NEVER**: `return ['success' => true, 'data' => $client]` - framework adds this
+
+**Special returns** (bypass auto-wrap):
+- `['errors' => [...]]` - Form validation errors
+- `['redirect' => '/path']` - Client-side navigation
+- `['error' => 'msg']` - Operation failure
+
+```php
+// Form validation
+if (empty($params['name'])) {
+    return ['errors' => ['name' => 'Required']];
+}
+
+// Success with redirect
+Flash_Alert::success('Saved');
+return ['redirect' => Rsx::Route('View_Action', $id)];
+
+// Permission error
+if (!can_delete()) {
+    return ['error' => 'Permission denied'];
+}
 ```
 
+---
+
 ### Flash Alerts in Ajax Endpoints
 
-**Server-side: Use success alerts ONLY when providing a redirect.**
+Use server-side success alerts ONLY with redirects (no on-screen element to show message).
 
-When the Ajax response includes a redirect, there's no on-screen element from the previous page to display the success message. Flash alerts persist across navigation to show the result.
-
-```php
-#[Ajax_Endpoint]
-public static function save(Request $request, array $params = []): array {
-    // Validation errors - return for client to handle
-    if (empty($params['name'])) {
-        return ['success' => false, 'errors' => ['name' => 'Required']];
-    }
-
-    $client->save();
-
-    // Success with redirect - use flash alert
-    Flash_Alert::success('Client saved successfully');
-
-    return [
-        'client_id' => $client->id,
-        'redirect' => Rsx::Route('Clients_View_Action', $client->id),
-    ];
-}
-```
-
-**Server pattern:** Success alerts with redirect only. Client handles errors by updating on-screen UI.
-
-**Client-side:** Flash alerts are a UI choice. Use `Flash_Alert.error()`, `Flash_Alert.warning()`, etc. on case-by-case basis (e.g., "Failed to add item to cart - item not available").
+**Client-side**: Use `Flash_Alert.error()`, `Flash_Alert.warning()` on case-by-case basis.
 
 ---