diff --git a/docs/DUAL_AUDIENCE_DEVELOPMENT_GUIDE.md b/docs/DUAL_AUDIENCE_DEVELOPMENT_GUIDE.md
new file mode 100644
index 0000000..b6f58b7
--- /dev/null
+++ b/docs/DUAL_AUDIENCE_DEVELOPMENT_GUIDE.md
@@ -0,0 +1,144 @@
+# Dual-Audience Development Guide: Agent-First APIs & Mobile-First SSR UI
+
+This guide outlines the architectural blueprint and best practices for building modern services within the **Auth-Yes Zero-Trust Ecosystem**.
+
+---
+
+## 1. The Core Philosophy: Dual-Audience Architecture
+
+Every modern application should be built for **two primary audiences**:
+1. **🤖 AI Agents & Workloads (Primary Data Consumer):**
+   - Headless execution via **Model Context Protocol (MCP)**, REST APIs, or ConnectRPC.
+   - Machine-readable, high-density JSON/RPC responses with zero HTML/CSS clutter.
+   - Authentication via **Delegated Bearer Tokens (`ay_sess_...`)** or mTLS SPIFFE workload identities.
+2. **📱 Humans on Mobile Devices (Primary UI Consumer):**
+   - Ultra-fast, zero-friction **Server-Side Rendered (SSR) JSX** touch cards.
+   - Passkey (WebAuthn) biometric authentication.
+   - Single Sign-On (SSO) entry via the **Auth-Yes Application Launchpad**.
+
+---
+
+## 2. Architectural Blueprint for Subsidiary Apps (e.g. `ed-droid`)
+
+```
+                               +---------------------------------------+
+                               |         Traefik Edge Ingress          |
+                               +---------------------------------------+
+                                                   |
+                             ForwardAuth Check     |  (Injects X-Forwarded-*)
+                          +------------------------+------------------------+
+                          |                                                 |
+                          v                                                 v
+              +-----------------------+                         +-----------------------+
+              |   Auth-Yes Service    |                         |    Subsidiary App     |
+              | (Validates Session /  |                         |   (e.g., ed-droid)    |
+              |  Bearer Token)        |                         +-----------------------+
+              +-----------------------+                                     |
+                                                                            |
+                                               +----------------------------+----------------------------+
+                                               |                                                         |
+                                               v                                                         v
+                                    [ /api/* JSON Endpoints ]                                 [ SSR HTML Mobile Cards ]
+                                    - Served for AI Agents & MCP                              - Served for Human Browsers
+                                    - Filtered by Scopes / Roles                              - Clean, high-contrast UI
+```
+
+---
+
+## 3. How to Build an "Agent-First" Subsidiary App
+
+### Step 1: Ingress Protection via ForwardAuth
+In your Traefik/Compose configuration, protect your service domain with Auth-Yes ForwardAuth middleware:
+```yaml
+labels:
+  - "traefik.http.routers.ed-droid.middlewares=auth-yes-forwardauth@docker"
+```
+When requests arrive:
+* Traefik queries `http://auth-api:8000/api/forward-auth`.
+* Auth-Yes validates either the browser's `session_id` cookie **or** the incoming `Authorization: Bearer ay_sess_...` token.
+* If authorized, Traefik injects:
+  - `X-Forwarded-User: <username>`
+  - `X-Forwarded-User-Id: <uuid>`
+  - `X-Forwarded-Scopes: <scope1,scope2>`
+  - `X-Forwarded-App-Id: <app_id>`
+
+### Step 2: Implement Clean JSON API Routes
+Provide standard JSON endpoints for all core operations:
+```typescript
+import { Hono } from "jsr:@hono/hono";
+
+const app = new Hono();
+
+// AI Agents & APIs consume JSON directly:
+app.get("/api/fleet", (c) => {
+  const user = c.req.header("X-Forwarded-User");
+  const fleetData = getFleetForUser(user);
+  return c.json({ fleet: fleetData });
+});
+```
+
+### Step 3: Progressive Content Negotiation (Optional)
+If a route serves both humans and AI agents without separate `/api` prefixes, inspect the `Accept` header or `?format=json` query:
+```typescript
+app.get("/ships/:id", (c) => {
+  const ship = getShip(c.req.param("id"));
+  
+  // If requested by an agent or CLI:
+  if (c.req.header("Accept")?.includes("application/json") || c.req.query("format") === "json") {
+    return c.json(ship);
+  }
+  
+  // If requested by a human browser:
+  return c.html(ShipCardView({ ship }));
+});
+```
+
+---
+
+## 4. Connecting AI Agents via Model Context Protocol (MCP)
+
+To expose your subsidiary applications to AI assistants (Antigravity, Jules, Claude Desktop):
+
+1. **Mint a Delegated Session in Auth-Yes:**
+   - Go to `https://auth.atyg.org/dashboard/sessions` $\rightarrow$ Click **`+ Delegate Agent Session`**.
+   - Set Label: `"Antigravity Assistant"`, Lifespan: `12 Hours`, Scope: `ed-droid`.
+   - Copy the CLI export string.
+
+2. **Configure the MCP Server:**
+   ```json
+   {
+     "mcpServers": {
+       "ed-droid": {
+         "command": "deno",
+         "args": ["run", "-A", "https://git.atyg.org/tylerg/ed-droid/raw/branch/main/mcp/server.ts"],
+         "env": {
+           "AUTH_YES_TOKEN": "ay_sess_8de186f564d7..."
+         }
+       }
+     }
+   }
+   ```
+
+3. **Tool Call Execution:**
+   The MCP server attaches `Authorization: Bearer $AUTH_YES_TOKEN` to all internal fetch calls, gaining instant authorized access to fleet telemetry and data with full Merkle audit attribution!
+
+---
+
+## 5. Ephemeral Guest & Support Passes (Magic 1-Click Links)
+
+In addition to Agent Bearer Tokens, Auth-Yes supports **Ephemeral Magic Passes** for friends and external support technicians:
+
+### The Flow:
+1. **Spawn Pass:** Under Sessions, click **`+ Spawn Guest / Support Pass`**:
+   - **Label:** *"Friend Demo - Elite Dangerous Fleet"*
+   - **Lifespan:** *2 Hours* (auto-expires)
+   - **Target App:** `ed-droid.atyg.org`
+2. **Share 1-Click Link:**
+   `https://auth.atyg.org/pass?token=ay_pass_9f8a7b6c...`
+3. **Instant Redemption:**
+   - When opened in any browser, Auth-Yes automatically sets the `.atyg.org` session cookie with restricted scopes.
+   - The browser is immediately redirected to `https://ed-droid.atyg.org`.
+   - **Zero friction:** No passkeys to register, no passwords, no email confirmation.
+4. **Security & Control:**
+   - The guest only has access to the specified target app.
+   - The pass is visible on your Sessions dashboard in real time with an instant **`[Revoke]`** button.