Docs: Update V3 Frontend Guide to reflect ID Vision and Permissive Mode

documentation/V3_FRONTEND_API_GUIDE.md

@@ -191,7 +191,69 @@ const downloadUrl = `${BASE_URL}/v3/crud/hosted_file/${fileId}/?jwt=${jwtToken}`
 
 ---
 
-## 7. Best Practices for V3
+
+
+## 7. The "ID Vision" Standard (2026 Refactor)
+
+
+
+V3 has moved to a **String-Only ID Vision**. In this paradigm, the frontend (SvelteKit) and external agents NEVER handle or store internal database integers. 
+
+
+
+### A. Automatic ID Mapping (Output)
+
+All V3 endpoints now automatically rename internal `id_random` fields to clean, short names in the JSON response.
+
+- **`id`**: The unique random identifier for the primary record.
+
+- **`account_id`**: The unique random identifier for the parent account.
+
+- **`site_id`, `person_id`, etc**: All related IDs follow this clean naming.
+
+
+
+**Example Response:**
+
+```json
+
+{
+
+  "id": "OGQK-02-04-94",
+
+  "name": "Scott's Journal",
+
+  "account_id": "nqOzejLCDXM"
+
+}
+
+```
+
+
+
+### B. Intelligent Mapping (Input/Search)
+
+The backend is now "Vision Aware." You can send string IDs back to the API using the same clean names.
+
+- **Search Filters**: You can filter by `account_id` using the random string value. The API handles the mapping to the DB integer automatically.
+
+- **Create/Update**: You can send `account_id: "nqOzejLCDXM"` in a payload. The `sanitize_payload` logic resolves this to the correct integer before saving.
+
+
+
+**Preferred Filter Pattern:**
+
+```json
+
+{
+
+  "and": [{ "field": "account_id", "op": "eq", "value": "nqOzejLCDXM" }]
+
+}
+
+```
+
+
 
 ---
 
@@ -201,63 +263,25 @@ const downloadUrl = `${BASE_URL}/v3/crud/hosted_file/${fileId}/?jwt=${jwtToken}`
 
 
 
-To ensure stability across the Aether mesh, all frontend components must adhere to these established patterns.
+### A. Permissive Update Mode (Upcoming)
+
+**Status:** In Development.
 
 
 
-### A. The "Whitelist" Standard for Saves
-
-**Problem:** Sending the entire object returned by a GET request back to a PATCH endpoint will cause a `400 Bad Request`. This happens because the object contains technical metadata (like `journal_id`, `created_on`, `for_type`) that the API cannot "SET".
+To simplify frontend state management, V3 is introducing a **Permissive Update Mode**. When enabled, the backend will **ignore** extra fields in your `PATCH` payload (like `_processed_at` or `created_on`) instead of returning a `400 Bad Request`.
 
 
 
-**Standard:** When preparing a save payload, explicitly whitelist ONLY the user-editable fields.
+- **Header:** `x-ae-ignore-extra-fields: true`
 
 
 
-```ts
-
-// ✅ CORRECT: Whitelist only editable fields
-
-const data_kv = {
-
-    name: tmp_obj.name,
-
-    content: tmp_obj.content,
-
-    tags: tmp_obj.tags,
-
-    category_code: tmp_obj.category_code
-
-};
+This allows you to send back larger chunks of the object without meticulously whitelisting every field, though whitelisting remains a best practice for performance.
 
 
 
-// ❌ WRONG: Passing the whole object or just blacklisting a few
-
-const data_kv = { ...tmp_obj }; 
-
-delete data_kv.id; // Still contains other computed columns!
-
-```
-
-
-
-### B. The Triple-ID Save Pattern
-
-**Standard:** When sending an ID in a POST/PATCH payload (e.g. creating a child object), use the random string version with the `_id_random` suffix.
-
-*   **Property:** `[obj_type]_id_random`
-
-*   **Value:** A string (e.g., `qpgvOh5nOYI`)
-
-
-
-**Warning:** Sending a string value under an integer key (e.g. `journal_id: "qpgvOh5nOYI"`) will trigger a Pydantic validation error on the backend.
-
-
-
-### C. Handle 'NULL' vs '0' for Booleans
+### B. Handle 'NULL' vs '0' for Booleans
 
 **Pitfall:** Fields like `hide` or `priority` can be `NULL` in the database.