feat: add priority filtering and sort stability to V3 Lookup System

documentation/GUIDE__V3_FRONTEND_API.md

@@ -60,7 +60,41 @@ The primary way to retrieve data.
 
 ---
 
-## 4. Event File Data Retrieval (Hosted Files)
+## 4. V3 Uniform Lookup System
+
+The V3 Lookup system provides a hierarchical, deduplicated interface for standardized tables (Countries, Timezones, etc.). It supports global defaults, account overrides, and site-specific whitelisting.
+
+### A. List Lookups
+Retrieve a ranked and filtered list of lookup items.
+*   **Endpoint:** `GET /v3/lookup/{lu_type}/list`
+*   **Available Types:** `country`, `country_subdivision`, `time_zone`
+*   **Parameters:**
+    *   `site_id` (Optional): Random ID of the site to apply a **Whitelist Policy**.
+    *   `only_priority` (Optional): Set to `true` to return only high-priority items (e.g., common time zones).
+    *   `for_type` / `for_id` (Optional): Context for object-specific overrides.
+    *   `include_disabled` (Optional): Set to `true` to see shadowed/disabled records.
+
+### B. Resolve Identity
+Resolves a string (code, group, or name) to a single record.
+*   **Endpoint:** `GET /v3/lookup/{lu_type}/resolve?q=VALUE`
+*   **Usage:** Use this when you have an external code (e.g., ISO "US") and need the full Aether record.
+
+### C. Site Whitelist Policy
+To limit lookups for a specific site, add a `lookup_policy` to the `site.cfg_json` field.
+**Schema:**
+```json
+{
+  "lookup_policy": {
+    "country": ["US", "CA", "GB"],
+    "time_zone": ["America/New_York"]
+  }
+}
+```
+*Note: Whitelist values must match the `group` field in the database.*
+
+---
+
+## 5. Event File Data Retrieval (Hosted Files)
 
 Every Event File (`event_file`) **must** have a linked Hosted File (`hosted_file`). The Hosted File itself is a metadata record for binary content (files), which is accessed via separate Action endpoints (e.g., `/v3/action/hosted_file/download`). This API endpoint provides metadata about the associated hosted file. To retrieve this additional metadata: