feat: team + operator + seed + health endpoints

cloud/SUPABASE-SETUP.md

@@ -114,3 +114,35 @@ SELECT * FROM pg_trigger WHERE tgname LIKE '%handle_new_user%';
 ```
 
 Should return at least one row. If missing, re-run the relevant migration.
+
+## 7. Demo seed on signup (migration 004)
+
+Migration `004_seed_demo_brain.sql` seeds a fully-populated demo brain when a new user signs up. Sims (S101–S103) showed users abandon when day-1 dashboards are empty.
+
+**What gets created:** 1 brain (`metadata.is_demo = true`), 8 lessons across the 6-dim taxonomy, 25 corrections in a Wozniak decay shape, 4 meta-rules, 6 events.
+
+**How users clear it:**
+
+```
+POST /api/v1/brains/{brain_id}/clear-demo
+```
+
+Response: `{ deleted: int, by_table: {...} }`. Only rows with `is_demo` flag are removed; real lessons are never touched.
+
+**Test signup → seed locally:**
+
+```sql
+SELECT handle_new_user_test(
+  '00000000-0000-0000-0000-000000000001'::uuid,
+  'Local Dev'
+);
+SELECT count(*) FROM lessons WHERE brain_id = '<returned uuid>';      -- expect 8
+SELECT count(*) FROM corrections WHERE brain_id = '<returned uuid>';  -- expect 25
+```
+
+**Tear down:**
+
+```sql
+DELETE FROM brains WHERE id = '<returned uuid>';
+-- ON DELETE CASCADE removes child rows.
+```

cloud/app/auth.py

@@ -19,6 +19,9 @@
 # Cache JWKS so we don't fetch on every request
 _jwks_cache: dict | None = None
 
+# Operator allowlist — god-mode admin access
+OPERATOR_DOMAINS = {"gradata.ai", "sprites.ai"}
+
 
 async def _get_jwks() -> dict:
     """Fetch and cache the Supabase JWKS for ES256 verification."""
@@ -47,8 +50,8 @@ async def verify_api_key(key: str) -> dict:
     return rows[0]
 
 
-async def verify_jwt(signed_jwt: str) -> str:
-    """Verify a Supabase JWT (ES256 or HS256) and return the user_id."""
+async def verify_jwt_claims(signed_jwt: str) -> dict:
+    """Verify a Supabase JWT (ES256 or HS256) and return the full claims dict."""
     settings = get_settings()
 
     # Try ES256 with JWKS first (modern Supabase projects)
@@ -67,10 +70,9 @@ async def verify_jwt(signed_jwt: str) -> str:
                 algorithms=["ES256"],
                 options={"verify_aud": False},
             )
-            user_id = claims.get("sub")
-            if not user_id:
+            if not claims.get("sub"):
                 raise HTTPException(status_code=401, detail="Invalid JWT: no sub claim")
-            return user_id
+            return claims
     except JWTError:
         pass  # Fall through to HS256
 
@@ -82,14 +84,19 @@ async def verify_jwt(signed_jwt: str) -> str:
             algorithms=["HS256"],
             options={"verify_aud": False},
         )
-        user_id = claims.get("sub")
-        if not user_id:
+        if not claims.get("sub"):
             raise HTTPException(status_code=401, detail="Invalid JWT: no sub claim")
-        return user_id
+        return claims
     except JWTError as e:
         raise HTTPException(status_code=401, detail=f"Invalid JWT: {e}") from e
 
 
+async def verify_jwt(signed_jwt: str) -> str:
+    """Verify a Supabase JWT and return just the user_id."""
+    claims = await verify_jwt_claims(signed_jwt)
+    return claims["sub"]
+
+
 async def get_current_brain(
     credentials: HTTPAuthorizationCredentials = Security(_bearer),
 ) -> dict:
@@ -144,3 +151,45 @@ async def get_brain_for_request(
 
     user_id = await verify_jwt(cred)
     return await verify_brain_ownership(brain_id, user_id)
+
+
+async def _resolve_user_email(user_id: str, claims: dict) -> str | None:
+    """Resolve the caller's email — prefer JWT claim, fall back to auth.users lookup."""
+    email = claims.get("email")
+    if email:
+        return email
+
+    # Fallback: query auth.users via the Supabase service-role client.
+    # Supabase exposes auth users through the admin REST endpoint, not PostgREST.
+    # If your db wrapper doesn't expose that, the JWT claim path is the primary route.
+    try:
+        db = get_db()
+        rows = await db.select("users", columns="email", filters={"id": user_id})
+        if rows:
+            return rows[0].get("email")
+    except Exception as exc:  # pragma: no cover - defensive
+        _log.warning("Failed to resolve email for user=%s: %s", user_id, exc)
+    return None
+
+
+async def require_operator(
+    credentials: HTTPAuthorizationCredentials = Security(_bearer),
+) -> str:
+    """Require the caller's email domain to be in OPERATOR_DOMAINS.
+
+    Resolves email from the JWT's ``email`` claim when present; otherwise falls
+    back to a ``users`` table lookup by ``user_id``. Raises 403 otherwise.
+    Returns the user_id for downstream use.
+    """
+    claims = await verify_jwt_claims(credentials.credentials)
+    user_id = claims["sub"]
+
+    email = await _resolve_user_email(user_id, claims)
+    if not email:
+        raise HTTPException(status_code=403, detail="Operator access requires a verified email")
+
+    domain = email.split("@", 1)[1].lower() if "@" in email else ""
+    if domain not in OPERATOR_DOMAINS:
+        raise HTTPException(status_code=403, detail="Operator access denied")
+
+    return user_id

cloud/app/db.py

@@ -66,6 +66,21 @@ async def update(
         resp.raise_for_status()
         return resp.json()
 
+    async def delete(
+        self, table: str, filters: dict[str, Any] | None = None,
+    ) -> list[dict]:
+        """DELETE rows matching eq filters. Returns deleted rows when PostgREST sends them back."""
+        params: dict[str, str] = {}
+        if filters:
+            for key, val in filters.items():
+                params[key] = f"eq.{val}"
+        resp = await self._http.delete(f"/{table}", params=params)
+        resp.raise_for_status()
+        try:
+            return resp.json()
+        except ValueError:
+            return []
+
     async def close(self):
         await self._http.aclose()
 

cloud/app/models.py

@@ -5,7 +5,7 @@
 from enum import Enum
 from typing import Any
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, EmailStr, Field, field_validator
 
 
 class Severity(str, Enum):
@@ -240,3 +240,86 @@ class SubscriptionResponse(BaseModel):
     status: str | None = None
     current_period_end: str | None = None
     usage: SubscriptionUsage = Field(default_factory=SubscriptionUsage)
+
+
+# ---------------------------------------------------------------------------
+# Team / workspace member models
+# ---------------------------------------------------------------------------
+
+
+class MemberRole(str, Enum):
+    owner = "owner"
+    admin = "admin"
+    member = "member"
+
+
+class InviteRole(str, Enum):
+    admin = "admin"
+    member = "member"
+
+
+class MemberResponse(BaseModel):
+    user_id: str
+    email: str | None = None
+    display_name: str | None = None
+    role: str
+    joined_at: str | None = None
+    last_sync_at: str | None = None
+
+
+class InviteRequest(BaseModel):
+    email: EmailStr
+    role: InviteRole = InviteRole.member
+
+
+class InviteResponse(BaseModel):
+    id: str
+    email: str
+    role: str
+    token: str
+    accept_url: str
+    expires_at: str | None = None
+
+
+class UpdateRoleRequest(BaseModel):
+    role: InviteRole  # owner cannot be assigned through this endpoint
+
+
+# ---------------------------------------------------------------------------
+# Operator / admin models (god-mode panel)
+# ---------------------------------------------------------------------------
+
+
+class GlobalKpis(BaseModel):
+    """Aggregate KPIs across all workspaces. All monetary amounts in USD (dollars)."""
+
+    mrr_usd: float = 0.0
+    arr_usd: float = 0.0
+    mrr_delta_pct: float = 0.0  # month-over-month new-workspace growth %
+    customers_total: int = 0
+    customers_active: int = 0  # any brain synced within 14 days
+    churn_rate: float = 0.0  # workspaces deleted in last 30d / total at period start
+    net_revenue_retention: float = 1.0  # TODO: placeholder until sub-history tracked
+
+
+class AdminCustomer(BaseModel):
+    """One workspace row for the operator customer list."""
+
+    id: str
+    company: str
+    plan: str
+    mrr_usd: float = 0.0
+    active_users: int = 0
+    brains: int = 0
+    last_active: str | None = None  # ISO timestamp
+    health: str = "healthy"  # healthy | at-risk | churning
+
+
+class AdminAlert(BaseModel):
+    """A derived operational alert for the operator panel."""
+
+    id: str
+    kind: str  # churn-risk | failed-payment | usage-spike
+    customer: str
+    detail: str
+    created_at: str  # ISO timestamp

cloud/app/routes/__init__.py

@@ -12,8 +12,10 @@
 from app.routes.corrections import router as corrections_router
 from app.routes.lessons import router as lessons_router
 from app.routes.meta_rules import router as meta_rules_router
+from app.routes.operator import router as operator_router
 from app.routes.rule_patches import router as rule_patches_router
 from app.routes.sync import router as sync_router
+from app.routes.team import router as team_router
 from app.routes.users import router as users_router
 
 router = APIRouter()
@@ -28,3 +30,5 @@
 router.include_router(activity_router, tags=["activity"])
 router.include_router(rule_patches_router, tags=["rule-patches"])
 router.include_router(billing_router, tags=["billing"])
+router.include_router(team_router, tags=["team"])
+router.include_router(operator_router, tags=["operator"])

cloud/app/routes/brains.py

@@ -141,3 +141,69 @@ async def delete_brain(
     now = datetime.now(timezone.utc).isoformat()
     await db.update("brains", data={"deleted_at": now}, filters={"id": brain_id})
     _log.info("Soft-deleted brain=%s", brain_id)
+
+
+class ClearDemoResponse(BaseModel):
+    deleted: int
+    by_table: dict[str, int]
+
+
+@router.post("/brains/{brain_id}/clear-demo", response_model=ClearDemoResponse)
+async def clear_demo(
+    brain_id: str,
+    request: Request,
+    credentials: HTTPAuthorizationCredentials = Depends(_bearer),
+) -> ClearDemoResponse:
+    """Delete all demo rows (is_demo=true) scoped to this brain.
+
+    Auth: caller must own the brain. Returns per-table delete counts and a total.
+    """
+    await get_brain_for_request(brain_id, credentials)
+    db = get_db()
+
+    by_table: dict[str, int] = {}
+    total = 0
+
+    # Children first (FK order doesn't strictly matter here, but we delete
+    # narrowest-to-widest so counts are readable).
+    for table in ("corrections", "lessons", "meta_rules", "events"):
+        deleted = await _delete_demo_rows(db, table, brain_id)
+        by_table[table] = deleted
+        total += deleted
+
+    # Finally the brain itself — only if it was flagged is_demo in metadata.
+    brain_rows = await db.select(
+        "brains", columns="id,metadata", filters={"id": brain_id}
+    )
+    if brain_rows and _is_demo_metadata(brain_rows[0].get("metadata")):
+        await db.delete("brains", filters={"id": brain_id})
+        by_table["brains"] = 1
+        total += 1
+    else:
+        by_table["brains"] = 0
+
+    _log.info("Cleared demo data for brain=%s (deleted=%d)", brain_id, total)
+    return ClearDemoResponse(deleted=total, by_table=by_table)
+
+
+async def _delete_demo_rows(db, table: str, brain_id: str) -> int:
+    """Fetch rows for the brain, filter by is_demo marker, delete those ids."""
+    rows = await db.select(table, columns="id,data", filters={"brain_id": brain_id})
+    demo_rows = [r for r in rows if _is_demo_data(r.get("data"))]
+    if not demo_rows:
+        return 0
+    for row in demo_rows:
+        await db.delete(table, filters={"id": row["id"]})
+    return len(demo_rows)
+
+
+def _is_demo_data(data) -> bool:
+    if not data:
+        return False
+    if isinstance(data, dict):
+        return bool(data.get("is_demo"))
+    return False
+
+
+def _is_demo_metadata(metadata) -> bool:
+    return _is_demo_data(metadata)