From 885d26e595daf55441816fb57bbc42c3fca3f5a3 Mon Sep 17 00:00:00 2001
From: Tyler Gillispie <mrteye@gmail.com>
Date: Mon, 24 Aug 2026 11:34:44 -0700
Subject: [PATCH] docs: add Use Case 11 (Guest Trial Sandboxes & In-Flight
 Upgrade) and quick links in README.md

---
 README.md                    | 21 +++++++++++++++++++
 docs/USE_CASES_AND_EFFORT.md | 39 +++++++++++++++++++++++++++++++++++-
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index db7c06d..6052b71 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,27 @@ workload identity.
 
 ---
 
+## ⚡ Quick Navigation & Practical Integration Playbooks
+
+- 📘
+  **[Practical Playbook & 11 High-ROI Use Cases](docs/USE_CASES_AND_EFFORT.md):**
+  Step-by-step guides for Appliance Setup, Traefik ForwardAuth, SSR Hydration,
+  Live WebSockets, Ephemeral Trial/Guest Tokens, and SSS Recovery.
+  - _Raw Gitea Mirror:_
+    `https://git.atyg.org/tylerg/auth-yes/raw/branch/main/docs/USE_CASES_AND_EFFORT.md`
+- ⚡ **[The Ghost Cockpit Protocol Spec](docs/GHOST_COCKPIT_SPEC.md):**
+  Specification and client snippet for non-destructive WebSocket telemetry
+  freezes and in-flight WebAuthn re-auth.
+  - _Raw Gitea Mirror:_
+    `https://git.atyg.org/tylerg/auth-yes/raw/branch/main/docs/GHOST_COCKPIT_SPEC.md`
+- 🛡️ **[Cryptographic Standards & Verification Dossier](docs/VERIFY.md):** Full
+  mathematical and specification audits (W3C WebAuthn Level 3, RFC 9421, RFC
+  7638, RFC 6962, RFC 9106).
+- 📦 **[Raw SDK Module Distribution](sdk/mod.ts):**
+  `https://git.atyg.org/tylerg/auth-yes/raw/branch/main/sdk/mod.ts`
+
+---
+
 ## 2. Core Security Architecture & Defense-in-Depth Layering
 
 Auth-Yes implements a strict multi-layered defense model ensuring that neither
diff --git a/docs/USE_CASES_AND_EFFORT.md b/docs/USE_CASES_AND_EFFORT.md
index 8fc2f89..a9e4e09 100644
--- a/docs/USE_CASES_AND_EFFORT.md
+++ b/docs/USE_CASES_AND_EFFORT.md
@@ -12,7 +12,7 @@ deployment, integration, and administrative scenarios.\
 
 Auth-Yes is engineered to eliminate the operational friction of legacy IAM
 systems (e.g. Keycloak, Okta, Auth0) while delivering mathematical zero-trust
-guarantees. Below is a comprehensive assessment of the **10 core high-ROI
+guarantees. Below is a comprehensive assessment of the **11 core high-ROI
 operational and integration scenarios**.
 
 ```
@@ -31,6 +31,7 @@ operational and integration scenarios**.
 │ 8  │ Incident Response & Fleet-Wide Revocation       │ Low              │ 1-Click / < 30µs Mesh  │
 │ 9  │ Multi-App RBAC & Scope Provisioning             │ Low              │ Simple Web UI Form     │
 │ 10 │ Cryptographic Compliance & Audit Verification   │ Zero             │ Automated Merkle Logs  │
+│ 11 │ Ephemeral Guest Sandboxes & Open Trial Access   │ Minimal          │ 1-Click / Zero Passkey │
 └────┴─────────────────────────────────────────────────┴──────────────────┴────────────────────────┘
 ```
 
@@ -239,3 +240,39 @@ operational and integration scenarios**.
   - Produces Signed Tree Heads (STHs) and mathematical inclusion proofs. Even an
     adversary with direct `root` access to the PostgreSQL database cannot alter
     past audit logs without cryptographic detection.
+
+---
+
+### Use Case 11: Ephemeral Guest Sandboxes & Open Trial Access (Zero-Friction Demo to In-Flight Passkey Upgrade)
+
+- **Difficulty Level:** **Minimal (1-Click Guest Issuance / Zero Passkey
+  Required Upfront)**
+- **What you actually have to do:**
+  - **Option A (1-Click Guest Sandbox Access):** When a visitor clicks "Try
+    Demo", issue a scoped ephemeral session:
+    ```typescript
+    // In ed-droid or host app:
+    const res = await fetch("https://auth.atyg.org/api/guest/session", {
+      method: "POST",
+      body: JSON.stringify({ appId: "ed-droid", ttlSeconds: 7200 }),
+    });
+    // Sets wildcard session cookie on .atyg.org with scopes: ["guest", "trial"]
+    ```
+  - **Option B (Route Handler Trial Scoping):** Check the injected grant header:
+    ```typescript
+    app.get("/workspace", (c) => {
+      const scopes = c.req.header("x-forwarded-scopes")?.split(",") || [];
+      const isGuest = scopes.includes("guest") || scopes.includes("trial");
+
+      return c.html(<Workspace isGuest={isGuest} />);
+    });
+    ```
+  - **Option C (In-Flight Upgrade to Permanent Passkey):** When the guest clicks
+    "Save Workspace", trigger ambient WebAuthn passkey registration on the spot
+    without reloading the page or losing active session state.
+- **Why it's painless:**
+  - Eliminates the drop-off barrier of forcing passkey enrollment before users
+    experience your product.
+  - ForwardAuth transparently sets `X-Forwarded-Scopes: guest,trial` downstream.
+  - Upgrades convert the ephemeral guest ID to a permanent passkey account
+    seamlessly in memory.