From 13620a63d033838e422da81ddef6e1cef5ba57dd Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Tue, 6 Jan 2026 19:36:58 -0500
Subject: [PATCH] Save notes and documentation updates

---
 .../Aether_Svelte_API_TS_code_samples.md      | 50 +++++++++++++++++
 documentation/V3_FRONTEND_API_GUIDE.md        | 55 ++++++++++++++++++-
 2 files changed, 104 insertions(+), 1 deletion(-)

diff --git a/documentation/Aether_Svelte_API_TS_code_samples.md b/documentation/Aether_Svelte_API_TS_code_samples.md
index 52809ad..a0d50e9 100644
--- a/documentation/Aether_Svelte_API_TS_code_samples.md
+++ b/documentation/Aether_Svelte_API_TS_code_samples.md
@@ -295,3 +295,53 @@ export async function get_ae_obj_li_for_obj_id_crud_v2({
     }
 }
 ```
+
+```ts
+/**
+ * Aether V3 Search (POST)
+ * Standardized search with recursive logical grouping and wildcard support.
+ */
+export async function search_ae_obj_v3({
+    api_cfg,
+    obj_type,
+    search_query, // Example: { q: "%", and: [{ field: "enable", op: "eq", value: true }] }
+    view = 'default',
+    limit = 100,
+    offset = 0,
+    log_lvl = 0
+}) {
+    const endpoint = `/v3/crud/${obj_type}/search`;
+    const params = { view, limit, offset };
+
+    return await post_object({ 
+        api_cfg, 
+        endpoint, 
+        params, 
+        data: search_query,
+        log_lvl
+    });
+}
+
+/**
+ * Aether V3 Schema Discovery (GET)
+ * Returns database and Pydantic model metadata for an object.
+ */
+export async function get_obj_schema_v3({ api_cfg, obj_type, view = 'default' }) {
+    const endpoint = `/v3/crud/${obj_type}/schema`;
+    const params = { view };
+
+    return await get_object({ api_cfg, endpoint, params });
+}
+
+/**
+ * Initial Site/Domain Resolution (Legacy V1/V2 Public Route)
+ * Used to bootstrap the app context (resolve account_id) from the current FQDN.
+ */
+export async function resolve_site_context({ api_cfg, fqdn }) {
+    // This specific path bypasses X-Account-ID requirement
+    const endpoint = `/crud/site/domain/${fqdn}`;
+    const params = { use_alt_table: true, use_alt_base: true };
+
+    return await get_object({ api_cfg, endpoint, params });
+}
+```
diff --git a/documentation/V3_FRONTEND_API_GUIDE.md b/documentation/V3_FRONTEND_API_GUIDE.md
index 5bb0b85..14f597b 100644
--- a/documentation/V3_FRONTEND_API_GUIDE.md
+++ b/documentation/V3_FRONTEND_API_GUIDE.md
@@ -149,7 +149,60 @@ export async function delete_ae_obj_v3({ api_cfg, obj_type, obj_id }) {
 
 ---
 
-## 4. Authentication in V3
+## 4. Specialized & Context Endpoints
+
+### A. Initial Context Resolution (FQDN)
+**Path**: `GET /crud/site/domain/{fqdn}?use_alt_table=true&use_alt_base=true`
+
+This is a **critical public endpoint** used by the Svelte frontend during initial load. 
+- **Requirement**: Does NOT require `X-Account-ID` header (it resolves it).
+- **Purpose**: Returns the `account_id` and site configuration associated with the current URL.
+- **Backend**: Currently routed via legacy V1/V2 `api_crud.py` for maximum compatibility.
+
+```ts
+// Example: resolve context from current location
+const fqdn = window.location.host;
+const endpoint = `/crud/site/domain/${fqdn}`;
+const context = await get_object({ 
+    api_cfg, 
+    endpoint, 
+    params: { use_alt_table: true, use_alt_base: true } 
+});
+// result includes account_id and account_id_random
+```
+
+### B. Schema Discovery
+**Path**: `GET /v3/crud/{obj_type}/schema`
+
+Used for developer tools or dynamic UI builders to understand the structure of an AE object. Returns:
+- Database column names and SQL types.
+- Pydantic model field names, aliases, and TypeScript-compatible types.
+
+```ts
+// GET /v3/crud/account/schema
+export async function get_obj_schema_v3({ api_cfg, obj_type }) {
+    const endpoint = `/v3/crud/${obj_type}/schema`;
+    return await get_object({ api_cfg, endpoint });
+}
+```
+
+---
+
+## 5. Advanced Search Logic
+
+### A. Standardized Global Search (`q`)
+Use the `q` property in your search body for a keyword search.
+- **Wildcard Support**: Setting `q: "%"` will bypass all text filtering and return all records (respecting only logical filters like `enable`).
+- **Fallback**: If the table lacks a `default_qry_str` column, the API automatically performs a `LIKE` search across all searchable fields.
+
+```json
+{
+  "q": "%",
+  "and": [{ "field": "enable", "op": "eq", "value": true }]
+}
+```
+
+## 6. Authentication in V3
 
 V3 supports multiple authentication methods. The backend resolves these automatically.