From aa5ba8c9c680679673561a85d496fc15cefa9b31 Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Tue, 31 Mar 2026 12:57:43 -0400
Subject: [PATCH] docs: clarify access_key guidance; mark prod deploy completed
 in TODO__Agents.md

---
 .../GUIDE__AE_API_V3_for_Frontend.md          | 33 +++++++++++++++++++
 documentation/TODO__Agents.md                 |  2 +-
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/documentation/GUIDE__AE_API_V3_for_Frontend.md b/documentation/GUIDE__AE_API_V3_for_Frontend.md
index ae480be7..a7861b5e 100644
--- a/documentation/GUIDE__AE_API_V3_for_Frontend.md
+++ b/documentation/GUIDE__AE_API_V3_for_Frontend.md
@@ -44,6 +44,39 @@ When the frontend first loads and doesn't know the `account_id`, it performs a "
 *   Returns 200 + a list containing the `account_id` (random string ID) and `site_id` (random string ID).
 *   ** デザイン Choice:** If the domain is not found, it returns **200 OK with an empty list `[]`**. It is NOT a 404.
 
+> **Access Key Support**
+>
+> Some client deployments restrict their domain to authenticated sessions via an access key set in the URL (e.g. `https://client.example.com/?key=abc123`).
+>
+> **How to pass the key:**
+> Read the `key` query param from the browser URL. If present and non-empty, include it as `access_key` in the POST body:
+> ```json
+> {
+>   "and": [
+>     { "field": "fqdn", "op": "eq", "value": "client.example.com" },
+>     { "field": "access_key", "op": "eq", "value": "abc123" }
+>   ]
+> }
+> ```
+> If `key` is absent, empty, or falsy — omit `access_key` from the payload entirely (do not send `"access_key": ""`).
+>
+> **Server behavior:**
+> - `v_site_domain.site_access_key` (site-level) takes priority. If set, all domains under that site require it.
+> - `v_site_domain.site_domain_access_key` (domain-level) is used only when `site_access_key` is not set.
+> - A domain is **public** only when **both** key columns are NULL/empty — no `access_key` needed.
+> - Falsy `access_key` values (empty string, etc.) are ignored server-side as a safety net.
+> - A successful match returns `200` with the matching record. No match returns `200` with an empty list `[]`.
+> - Do **not** use `access_code_kv_json` for this — that field is consumed by UI features and is unrelated to access control.
+>
+> **Examples:**
+> | Browser URL | `access_key` in payload | Result |
+> |---|---|---|
+> | `https://dev-demo.oneskyit.com` | *(omit)* | ✅ Returns record (public domain) |
+> | `https://client.example.com/?key=correct` | `"correct"` | ✅ Returns record |
+> | `https://client.example.com/` | *(omit)* | ❌ Empty list (key required) |
+> | `https://client.example.com/?key=wrong` | `"wrong"` | ❌ Empty list (wrong key) |
+> | `https://client.example.com/?key=` | *(omit — strip empty)* | ❌ Empty list (key required) |
+>
 ---
 
 ## 3. Standard CRUD Patterns
diff --git a/documentation/TODO__Agents.md b/documentation/TODO__Agents.md
index 15594ea7..ef584375 100644
--- a/documentation/TODO__Agents.md
+++ b/documentation/TODO__Agents.md
@@ -147,7 +147,7 @@ Full audit: `src/routes/events/[event_id]/(leads)/` and `src/lib/ae_events/ae_ev
 - [x] **Build Optimization:** Current state finalized. Local Gitea instance stood up at `git.dgrzone.com` (Docker, home server) — future: migrate repos from Bitbucket, verify Backblaze/restic backups cover Gitea data. (2026-03-11)
 - [x] **Remote deploy script:** `aether_container_env/deploy.sh` — SSH-triggered from workstation via `npm run deploy:remote:test/prod`. Handles git pull (ff-only) + docker build + restart. Tested and working on test env. (2026-03-25)
 - [x] **`.env.default` cleanup:** Removed 16 dead variables, added missing `AE_NETWORK_NAME`/`CONTAINER_DOZZLE`/`AE_DOZZLE_PORT`, parameterized all container names (`CONTAINER_MARIADB`, `CONTAINER_PMA`, `CONTAINER_AE_OPS`) with `:-default` fallbacks in compose. ("Dozzle" = log viewer container.) (2026-03-26)
-- [ ] **Prod deploy:** Run `npm run deploy:remote:prod` (off-peak). Prerequisites: both repos pushed to Bitbucket ✓; verify `.env.prod` exists in `/srv/apps/prod_aether_app_sveltekit/` on Linode before running.
+- [x] **Prod deploy:** Run `npm run deploy:remote:prod` (off-peak). Prerequisites: both repos pushed to Bitbucket ✓; verify `.env.prod` exists in `/srv/apps/prod_aether_app_sveltekit/` on Linode before running. (2026-03-30)
 - [x] **Bitbucket → SSH migration:** Switched all three repos (`aether_app_sveltekit`, `aether_container_env`, `aether_api_fastapi`) to SSH remotes (`git@bitbucket.org`) on workstation. App passwords deprecated — SSH unaffected. (2026-03-27)
 - [ ] **Branch strategy cleanup:** All environments (test, prod, bak) currently pull from same branches. `deploy.sh` defaults are `ae_app_3x_llm` / `development` — acceptable for now but should establish proper branch separation (e.g. `main`/`master` for prod).
 - [ ] **Tier 2 deploy (Gitea webhook):** Push-triggered deploys via Gitea webhook → listener on Linode → `deploy.sh`. Deferred until Gitea usage is more established.