loopwind 0.25.6 → 0.25.7

package/plans/PLATFORM.md

@@ -1,12 +1,15 @@
 # Loopwind API Service Design
 
+> **Related docs**:
+> - [SDK.md](./SDK.md) - Local rendering library (no platform needed)
+
 ## Overview
 
 This document outlines the architecture for a cloud-based Loopwind API service that enables:
 - **Publishing templates** via `loopwind publish template-name`
-- **User accounts** at loopwind.dev with authentication
-- **Secure API endpoints** for generating images/videos from published templates
-- **Template marketplace** for sharing and discovering templates
+- **Simple render URLs** - each template gets a unique URL like `api.loopwind.dev/r/x7k9m2p4?title=Hello`
+- **User accounts** at loopwind.dev with organization-based isolation
+- **No SDK required** - just use the URL in `<img>` tags or fetch directly
 
 ---
 
@@ -17,7 +20,7 @@ This document outlines the architecture for a cloud-based Loopwind API service t
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                              loopwind CLI                                │
-│         loopwind publish / loopwind render --remote                      │
+│                          loopwind publish                                │
 └─────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
@@ -112,25 +115,56 @@ DELETE /api/keys/:id
 ### CLI Authentication Flow
 
 ```bash
-# Login via browser (OAuth-style device flow)
 $ loopwind login
-Opening browser for authentication...
-Waiting for confirmation...
-✓ Logged in as user@example.com
 
-# Token stored in ~/.loopwind/credentials
+  Opening browser...
+  https://loopwind.dev/cli/login?session=abc123
+
+  Waiting for authorization...
+
+  ✓ Logged in as tommy (via GitHub)
+  ✓ Organization: my-org
+```
+
+**Flow:**
+1. CLI generates random session ID, opens browser
+2. User clicks "Continue with GitHub"
+3. GitHub OAuth → callback to loopwind.dev
+4. loopwind.dev creates/finds user, links to session
+5. CLI polls, gets token when authorized
+
+**Stored credentials:**
+
+```json
+// ~/.loopwind/credentials.json
 {
-  "token": "jwt...",
-  "refreshToken": "...",
-  "email": "user@example.com",
-  "expiresAt": "2025-01-06T..."
+  "token": "eyJhbG...",
+  "expiresAt": "2025-02-06T12:00:00Z",
+  "user": {
+    "id": "usr_abc123",
+    "email": "tommy@example.com",
+    "username": "tommy"
+  },
+  "organization": {
+    "id": "org_xyz",
+    "name": "my-org"
+  }
 }
+```
 
-# Or use API key directly
-$ export LOOPWIND_API_KEY=lw_live_xxxxxxxxxxxxxxxxxxxx
-$ loopwind publish my-template
+**For CI/CD (no browser):**
+
+```bash
+$ loopwind login --token
+
+  Paste your API key from loopwind.dev/settings/tokens:
+  > lw_xxxxxxxxxxxxx
+
+  ✓ Authenticated
 ```
 
+> **Future:** Add Google OAuth as alternative to GitHub.
+
 ---
 
 ## Template Publishing
@@ -157,11 +191,104 @@ Options:
 └─────────────┘    └──────────────┘    └────────────────┘    └─────────────┘
      │                   │                    │                     │
      ▼                   ▼                    ▼                     ▼
- Check meta.ts      Bundle template     POST files to S3     Update registry
- Validate props     Include assets      Get file URLs        Set version
- Check deps         Compress            Store checksums      Index for search
+ Check meta         Bundle template     POST to org DO      Generate render
+ Validate props     Include assets      Store config         token (random ID)
+ Load config        Include fonts       Store files          Return render URL
+```
+
+**What gets uploaded:**
+- `template.tsx` - source code (entry point)
+- `template.js` - compiled bundle (includes all imports)
+- `config.json` - loopwind.json config (colors, fonts, tokens)
+- `assets/*` - images, fonts from all imported templates
+
+### Template Dependencies
+
+Templates can import other templates (layouts, components). Everything gets bundled:
+
+```tsx
+// .loopwind/og-card/template.tsx
+import { Layout } from '../shared/layout';
+import { Card } from '../components/card';
+import { Avatar } from '../components/avatar';
+
+export default function OGCard({ title, author, tw }) {
+  return (
+    <Layout tw={tw}>
+      <Card tw={tw}>
+        <Avatar src={author.avatar} tw={tw} />
+        <h1 style={tw("text-4xl")}>{title}</h1>
+      </Card>
+    </Layout>
+  );
+}
+```
+
+**Publish bundles everything:**
+
+```bash
+$ loopwind publish og-card
+
+  Bundling...
+    ✓ og-card/template.tsx (entry)
+    ✓ shared/layout.tsx (imported)
+    ✓ components/card.tsx (imported)
+    ✓ components/avatar.tsx (imported)
+
+  ✓ Published og-card v1.0.0
+
+    Included:
+      - template.js (4.2 KB) ← single bundle with all imports
+      - config: 12 colors, 2 fonts
+      - assets: logo.png, avatar-placeholder.png
 ```
 
+The compiled `template.js` is self-contained - no external imports needed at runtime.
+
+### Images in Published Templates
+
+The `image()` helper works with published templates:
+
+**1. Template assets (bundled)**
+
+Assets in the template directory are uploaded with the template:
+
+```tsx
+// Template uses local asset
+<img src={image('logo.svg')} />
+<img src={image('assets/icon.png')} />
+```
+
+These are stored in `template_files` and served from the platform.
+
+**2. External URLs (passed as props)**
+
+Pass image URLs as query params:
+
+```
+GET /r/x7k9m2p4?title=Hello&background=https://example.com/bg.jpg
+```
+
+```tsx
+// Template receives URL in props
+export default function Card({ title, background, tw, image }) {
+  return (
+    <div style={tw('w-full h-full')}>
+      <img src={image('background')} style={tw('absolute inset-0')} />
+      <h1 style={tw('text-6xl')}>{title}</h1>
+    </div>
+  );
+}
+```
+
+**3. What works where:**
+
+| Image Source | CLI (local) | Platform (published) |
+|--------------|-------------|----------------------|
+| Template assets (`image('logo.svg')`) | ✅ | ✅ (bundled) |
+| External URLs (`image('background')` → URL prop) | ✅ | ✅ |
+| Local file paths (`./images/bg.jpg`) | ✅ | ❌ (use URLs) |
+
 ### Publish API Endpoints
 
 ```
@@ -187,11 +314,10 @@ Content-Type: multipart/form-data
 }
 
 → 201 {
-  "id": "tpl_abc123",
+  "id": "tpl_x7k9m2p4",
   "name": "og-card",
   "version": "1.0.0",
-  "author": "username",
-  "url": "https://loopwind.dev/username/og-card",
+  "renderUrl": "https://api.loopwind.dev/r/x7k9m2p4",
   "publishedAt": "2025-01-05T..."
 }
 ```
@@ -200,17 +326,11 @@ Content-Type: multipart/form-data
 
 ```typescript
 interface PublishedTemplate {
-  id: string;                    // tpl_abc123
+  id: string;                    // tpl_x7k9m2p4 (random, used in render URL)
   name: string;                  // og-card
-  slug: string;                  // username/og-card
   version: string;               // 1.0.0
   description: string;
-
-  author: {
-    id: string;
-    username: string;
-    avatar?: string;
-  };
+  renderUrl: string;             // https://api.loopwind.dev/r/x7k9m2p4
 
   meta: {
     type: "image" | "video";
@@ -219,16 +339,8 @@ interface PublishedTemplate {
     props: Record<string, string>;
   };
 
-  files: {
-    path: string;
-    url: string;                 // CDN URL
-    checksum: string;
-  }[];
-
   stats: {
-    downloads: number;
     renders: number;
-    stars: number;
   };
 
   private: boolean;
@@ -244,120 +356,1138 @@ interface PublishedTemplate {
 
 ## Rendering API
 
-### Synchronous Rendering (Images)
+After publishing, each template gets a unique render URL. Two ways to render:
 
-For quick image renders (<5 seconds):
+1. **GET with query params** - Simple, cacheable, works in `<img>` tags
+2. **POST with JSON body** - Complex props, arrays, nested objects
 
-```
-POST /api/render
-Authorization: Bearer <token>
-Content-Type: application/json
+Each template gets a random ID (e.g., `x7k9m2p4`) that's used in the URL. This:
+- Prevents enumeration of organizations/templates
+- Doesn't expose organization or template names
+- Can be revoked/rotated if leaked
 
-{
-  "template": "username/og-card",       // Template slug or ID
-  "version": "latest",                  // Optional, default: latest
-  "props": {
-    "title": "Hello World",
-    "subtitle": "My awesome post"
-  },
-  "format": "png",                      // png, jpg, webp, svg
-  "scale": 2                            // Optional, for retina (default: 1)
-}
+---
+
+### GET - URL-Based Rendering
+
+Best for simple props, OG images, anywhere you need a URL.
+
+```bash
+GET https://api.loopwind.dev/r/x7k9m2p4?title=Hello%20World&subtitle=Welcome
 
 → 200 (binary image data)
 Content-Type: image/png
+Cache-Control: public, max-age=86400
 X-Render-Duration: 234ms
-X-Render-Id: rnd_xyz789
 ```
 
-### Asynchronous Rendering (Videos)
+**Query Parameters:**
+- Template props: `?title=Hello&subtitle=World`
+- Format: `?format=png` (default) / `webp` / `jpg` / `svg`
+- Size override: `?width=800&height=400`
+- Version: `?v=1.0.0` (pin to specific version, default: latest)
 
-For longer video renders:
+**Usage:**
 
+```html
+<!-- Direct in HTML -->
+<img src="https://api.loopwind.dev/r/x7k9m2p4?title=Hello%20World" />
+
+<!-- OG meta tag -->
+<meta property="og:image" content="https://api.loopwind.dev/r/x7k9m2p4?title=My%20Blog%20Post" />
+```
+
+---
+
+### Dynamic OG Images
+
+The main use case: generate unique OG images for each page using just an `<img>` tag or meta tag.
+
+**Template with dynamic title + featured image:**
+
+```tsx
+// .loopwind/blog-og/template.tsx
+export const meta = {
+  name: "blog-og",
+  type: "image",
+  size: { width: 1200, height: 630 },
+  props: {
+    title: "string",
+    image: "string?",      // Optional featured image URL
+    author: "string?",
+    date: "string?",
+  },
+};
+
+export default function BlogOG({ title, image, author, date, tw }) {
+  return (
+    <div style={tw("w-full h-full flex bg-white")}>
+      {/* Featured image (left half) */}
+      {image && (
+        <img
+          src={image}
+          style={tw("w-1/2 h-full object-cover")}
+        />
+      )}
+
+      {/* Content (right half or full if no image) */}
+      <div style={tw(`${image ? 'w-1/2' : 'w-full'} h-full flex flex-col justify-center p-12`)}>
+        <h1 style={tw("text-5xl font-bold text-gray-900 leading-tight")}>
+          {title}
+        </h1>
+        {author && (
+          <p style={tw("text-xl text-gray-600 mt-4")}>
+            {author} {date && `• ${date}`}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+**Use in HTML (static site, any framework):**
+
+```html
+<!-- Pass all props as URL params -->
+<meta
+  property="og:image"
+  content="https://api.loopwind.dev/r/x7k9m2p4?title=How%20to%20Build%20APIs&image=https://example.com/featured.jpg&author=Jane%20Doe"
+/>
+
+<!-- Or just an img tag -->
+<img src="https://api.loopwind.dev/r/x7k9m2p4?title=My%20Post&image=https://cdn.example.com/photo.jpg" />
+```
+
+**Use in Next.js:**
+
+```tsx
+// app/blog/[slug]/page.tsx
+export async function generateMetadata({ params }) {
+  const post = await getPost(params.slug);
+
+  // Build OG image URL with dynamic props
+  const ogUrl = new URL('https://api.loopwind.dev/r/x7k9m2p4');
+  ogUrl.searchParams.set('title', post.title);
+  ogUrl.searchParams.set('author', post.author.name);
+  if (post.featuredImage) {
+    ogUrl.searchParams.set('image', post.featuredImage);
+  }
+
+  return {
+    openGraph: {
+      images: [ogUrl.toString()],
+    },
+  };
+}
 ```
-POST /api/render/async
-Authorization: Bearer <token>
-Content-Type: application/json
 
+**Use in Astro:**
+
+```astro
+---
+// src/pages/blog/[slug].astro
+const { post } = Astro.props;
+
+const ogParams = new URLSearchParams({
+  title: post.title,
+  author: post.author,
+  image: post.featuredImage,
+  date: post.date,
+});
+const ogImage = `https://api.loopwind.dev/r/x7k9m2p4?${ogParams}`;
+---
+
+<head>
+  <meta property="og:image" content={ogImage} />
+</head>
+```
+
+**Use in Hugo/Jekyll (static HTML):**
+
+```html
+<!-- Hugo -->
+<meta property="og:image" content="https://api.loopwind.dev/r/x7k9m2p4?title={{ .Title | urlquery }}&image={{ .Params.featured_image | urlquery }}" />
+
+<!-- Jekyll -->
+<meta property="og:image" content="https://api.loopwind.dev/r/x7k9m2p4?title={{ page.title | url_encode }}&image={{ page.image | url_encode }}" />
+```
+
+**Key points:**
+- Images are passed as URL props (external URLs)
+- Everything URL-encoded automatically by frameworks
+- Cached in R2 - same URL = instant response
+- No server-side code needed - works with static sites
+
+---
+
+### Allowed Hosts (Security)
+
+To prevent SSRF attacks and abuse, external image URLs must match allowed hosts configured by the organization.
+
+**Dashboard UI (Settings → Allowed Hosts):**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Settings › Allowed Hosts                                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  External images in your templates can only be loaded from      │
+│  these domains. Add your CDN, CMS, or image hosting domains.    │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  cdn.mysite.com                                    [×]  │   │
+│  │  images.unsplash.com                               [×]  │   │
+│  │  *.amazonaws.com                                   [×]  │   │
+│  │  res.cloudinary.com                                [×]  │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+│  ┌─────────────────────────────────────────┐  ┌─────────────┐  │
+│  │  Add domain (e.g. cdn.example.com)      │  │  + Add      │  │
+│  └─────────────────────────────────────────┘  └─────────────┘  │
+│                                                                 │
+│  💡 Use wildcards for subdomains: *.example.com                 │
+│                                                                 │
+│  ─────────────────────────────────────────────────────────────  │
+│                                                                 │
+│  Default hosts (always allowed):                                │
+│  • images.unsplash.com                                          │
+│  • cdn.sanity.io                                                │
+│  • res.cloudinary.com                                           │
+│  • *.supabase.co                                                │
+│  • *.githubusercontent.com                                      │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**API endpoint:**
+
+```
+GET /api/organizations/:org_id/allowed-hosts
+→ 200 { "hosts": ["cdn.mysite.com", "*.amazonaws.com"] }
+
+POST /api/organizations/:org_id/allowed-hosts
+{ "host": "cdn.newsite.com" }
+→ 201 { "hosts": [...] }
+
+DELETE /api/organizations/:org_id/allowed-hosts/:host
+→ 204
+```
+
+**How it works:**
+
+```
+GET /r/x7k9m2p4?title=Hello&image=https://cdn.example.com/photo.jpg
+                                         │
+                                         ▼
+                              ┌─────────────────────┐
+                              │  Validate host      │
+                              │                     │
+                              │  cdn.example.com    │
+                              │  in allowedHosts?   │
+                              └──────────┬──────────┘
+                                         │
+                         ┌───────────────┴───────────────┐
+                         │                               │
+                         ▼                               ▼
+                   ┌──────────┐                    ┌──────────┐
+                   │   Yes    │                    │    No    │
+                   │  Fetch   │                    │  Error   │
+                   │  image   │                    │   403    │
+                   └──────────┘                    └──────────┘
+```
+
+**Blocked request:**
+
+```
+GET /r/x7k9m2p4?image=https://evil.com/malware.jpg
+
+→ 403 {
+  "error": "host_not_allowed",
+  "message": "Host 'evil.com' is not in allowed hosts list",
+  "allowedHosts": ["cdn.example.com", "images.unsplash.com"]
+}
+```
+
+**Wildcard patterns:**
+
+| Pattern | Matches |
+|---------|---------|
+| `example.com` | Only `example.com` |
+| `*.example.com` | `cdn.example.com`, `images.example.com` |
+| `*.amazonaws.com` | `s3.amazonaws.com`, `my-bucket.s3.amazonaws.com` |
+
+**Default allowed hosts (all organizations):**
+
+```
+- images.unsplash.com
+- cdn.sanity.io
+- res.cloudinary.com
+- *.supabase.co
+- *.githubusercontent.com
+```
+
+**Private/internal URLs always blocked:**
+
+```
+- localhost, 127.0.0.1, ::1
+- 10.*, 172.16-31.*, 192.168.*
+- *.internal, *.local
+- file://, data:// schemes
+```
+
+**Image size limits:**
+
+When fetching external images, the platform enforces limits to prevent abuse:
+
+| Limit | Value |
+|-------|-------|
+| Max file size | 10 MB |
+| Max dimensions | 4096 x 4096 px |
+| Fetch timeout | 10 seconds |
+| Allowed schemes | `https://` only |
+
+---
+
+### Image Transformations (Cloudflare Images)
+
+External images passed as props can be automatically optimized and transformed using [Cloudflare Images](https://developers.cloudflare.com/images/). This provides:
+
+- **On-the-fly resizing** - Crop/resize images to fit your template
+- **Format conversion** - Automatic WebP/AVIF for smaller files
+- **Global CDN** - Images served from Cloudflare's edge
+- **Caching** - Transformed images cached automatically
+
+**How it works:**
+
+When rendering, external image URLs are proxied through Cloudflare Images:
+
+```
+Original URL (from props):
+https://cdn.example.com/photo.jpg
+
+Transformed URL (internal):
+https://api.loopwind.dev/cdn-cgi/image/width=800,height=600,fit=cover,format=auto/https://cdn.example.com/photo.jpg
+```
+
+**Transform options in templates:**
+
+Templates can specify transform requirements in `meta.json`:
+
+```json
 {
-  "template": "username/promo-video",
   "props": {
-    "title": "Product Launch",
-    "logoUrl": "https://example.com/logo.png"
-  },
-  "format": "mp4",                      // mp4, gif
-  "webhook": "https://myapp.com/hooks/render-complete"  // Optional
+    "avatar": {
+      "type": "image",
+      "transform": {
+        "width": 200,
+        "height": 200,
+        "fit": "cover"
+      }
+    },
+    "background": {
+      "type": "image",
+      "transform": {
+        "width": 1200,
+        "height": 630,
+        "fit": "cover",
+        "format": "auto"
+      }
+    }
+  }
 }
+```
 
-→ 202 {
-  "jobId": "job_abc123",
-  "status": "queued",
-  "estimatedDuration": 15000,           // ms
-  "statusUrl": "/api/render/job_abc123",
-  "createdAt": "2025-01-05T..."
+**Available transform options:**
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `width` | 1-12000 | Target width in pixels |
+| `height` | 1-12000 | Target height in pixels |
+| `fit` | `cover`, `contain`, `scale-down`, `crop`, `pad` | How image fills dimensions |
+| `format` | `auto`, `webp`, `avif`, `jpeg`, `png` | Output format (`auto` = best for browser) |
+| `quality` | 1-100 | Quality for lossy formats (default: 85) |
+
+**Query param overrides:**
+
+Props can override transform settings via URL params:
+
+```
+# Use template default transform
+GET /r/x7k9m2p4?avatar=https://example.com/photo.jpg
+
+# Override width
+GET /r/x7k9m2p4?avatar=https://example.com/photo.jpg&avatar_w=400
+
+# Override multiple
+GET /r/x7k9m2p4?avatar=https://example.com/photo.jpg&avatar_w=400&avatar_h=400&avatar_fit=contain
+```
+
+**Direct image proxy (API):**
+
+For advanced use cases, images can be transformed directly:
+
+```
+GET /img?src=https://example.com/photo.jpg&w=800&h=600&fit=cover&f=webp
+
+→ Returns transformed image with headers:
+   Content-Type: image/webp
+   Cache-Control: public, max-age=31536000
+   CF-Cache-Status: HIT
+```
+
+**Benefits over raw URLs:**
+
+| | Raw URL | With Transform |
+|--|---------|----------------|
+| File size | 2.5 MB | 150 KB (WebP) |
+| Dimensions | 4000x3000 | 800x600 |
+| Load time | 800ms | 50ms |
+| Format | JPEG | WebP/AVIF (auto) |
+| CDN | Origin only | Global edge |
+
+---
+
+### Signed URLs (Private Images)
+
+For private templates or time-limited access, renders can be secured with [Cloudflare signed URLs](https://developers.cloudflare.com/images/manage-images/serve-images/serve-private-images/).
+
+**Use cases:**
+- **Private templates** - Only users with valid signature can view
+- **Time-limited sharing** - URLs expire after set duration
+- **Prevent hotlinking** - Images only work on your domains
+- **Audit trail** - Track who accessed what and when
+
+**How it works:**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Your Server                                                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. User requests private image                                 │
+│  2. Generate signed URL with expiration                         │
+│  3. Return signed URL to user                                   │
+│                                                                 │
+│  const signedUrl = loopwind.signUrl(renderUrl, {                │
+│    expiresIn: 3600  // 1 hour                                   │
+│  });                                                            │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Signed URL                                                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  https://api.loopwind.dev/r/x7k9m2p4                            │
+│    ?title=Hello                                                 │
+│    &exp=1704067200                                              │
+│    &sig=a1b2c3d4e5f6...                                         │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Loopwind API                                                    │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Verify signature (HMAC-SHA256)                              │
+│  2. Check expiration timestamp                                  │
+│  3. If valid → render image                                     │
+│  4. If invalid → 403 Forbidden                                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Generating signed URLs (server-side):**
+
+```typescript
+import crypto from 'crypto';
+
+function signRenderUrl(
+  renderUrl: string,
+  signingKey: string,
+  expiresIn: number = 3600  // seconds
+): string {
+  const url = new URL(renderUrl);
+  const exp = Math.floor(Date.now() / 1000) + expiresIn;
+
+  // Add expiration to URL
+  url.searchParams.set('exp', String(exp));
+
+  // Generate signature from path + query (excluding sig param)
+  const dataToSign = url.pathname + url.search;
+  const sig = crypto
+    .createHmac('sha256', signingKey)
+    .update(dataToSign)
+    .digest('hex');
+
+  url.searchParams.set('sig', sig);
+  return url.toString();
 }
+
+// Usage
+const signingKey = process.env.LOOPWIND_SIGNING_KEY;
+const signedUrl = signRenderUrl(
+  'https://api.loopwind.dev/r/x7k9m2p4?title=Private+Doc',
+  signingKey,
+  3600  // Valid for 1 hour
+);
 ```
 
-### Job Status Polling
+**Dashboard UI (Settings → Signing Keys):**
 
 ```
-GET /api/render/:jobId
-Authorization: Bearer <token>
+┌─────────────────────────────────────────────────────────────────┐
+│  Settings › Signing Keys                                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Use signing keys to generate secure, time-limited URLs for     │
+│  private templates.                                             │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  Production Key                                          │   │
+│  │  sk_live_••••••••••••••••                     [Reveal]   │   │
+│  │  Created: Jan 5, 2025                         [Rotate]   │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+│  ┌───────────────────────────────────────┐                     │
+│  │  + Generate New Key                   │                     │
+│  └───────────────────────────────────────┘                     │
+│                                                                 │
+│  ⚠️  Keep signing keys secret! Never expose in client-side code. │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
 
-→ 200 {
+**API for key management:**
+
+```
+POST /api/organizations/:org_id/signing-keys
+→ 201 { "id": "sk_xxxxx", "key": "sk_live_...", "createdAt": "..." }
+
+GET /api/organizations/:org_id/signing-keys
+→ 200 [{ "id": "sk_xxxxx", "prefix": "sk_live_****", "createdAt": "..." }]
+
+DELETE /api/organizations/:org_id/signing-keys/:id
+→ 204
+```
+
+**Template-level privacy:**
+
+```json
+// meta.json
+{
+  "name": "confidential-report",
+  "private": true,
+  "requireSignature": true,
+  "signatureExpiry": 3600
+}
+```
+
+**Error responses:**
+
+```
+# Missing signature on private template
+GET /r/x7k9m2p4?title=Hello
+→ 403 { "error": "signature_required", "message": "This template requires a signed URL" }
+
+# Expired signature
+GET /r/x7k9m2p4?title=Hello&exp=1704000000&sig=abc123
+→ 403 { "error": "signature_expired", "message": "URL expired at 2024-12-31T12:00:00Z" }
+
+# Invalid signature
+GET /r/x7k9m2p4?title=Hello&exp=1735689600&sig=invalid
+→ 403 { "error": "signature_invalid", "message": "Signature verification failed" }
+```
+
+---
+
+### Version Pinning
+
+By default, render URLs use the latest published version. Pin to a specific version for stability:
+
+```
+# Latest version (default)
+GET /r/x7k9m2p4?title=Hello
+
+# Pinned to v1.0.0
+GET /r/x7k9m2p4?title=Hello&v=1.0.0
+
+# Explicit latest
+GET /r/x7k9m2p4?title=Hello&v=latest
+```
+
+**Why pin versions:**
+- OG images shouldn't change unexpectedly after you share them
+- Production apps need stability
+- Roll back if new version has issues
+
+**Version in POST body:**
+
+```bash
+curl -X POST https://api.loopwind.dev/r/x7k9m2p4 \
+  -H "Content-Type: application/json" \
+  -d '{"props": {"title": "Hello"}, "version": "1.0.0"}'
+```
+
+**Cache behavior:**
+- Different versions = different cache keys
+- Updating template creates new version, doesn't invalidate old version caches
+- Pinned URLs are stable; unpinned URLs update when you publish
+
+---
+
+### Custom Domains
+
+Use your own domain instead of `api.loopwind.dev`:
+
+```
+# Instead of:
+https://api.loopwind.dev/r/x7k9m2p4?title=Hello
+
+# Use:
+https://og.mysite.com/card?title=Hello
+```
+
+**Setup in dashboard (Settings → Custom Domains):**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Settings › Custom Domains                                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Custom domains let you use your own URLs for render requests.  │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  og.mysite.com                              [Verified]  │   │
+│  │    → Routes to: blog-og template                        │   │
+│  │                                                         │   │
+│  │  images.mysite.com                          [Verified]  │   │
+│  │    → Routes to: all templates (use /template-name)      │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+│  ┌─────────────────────────────────┐  ┌───────────────────┐    │
+│  │  Add domain                     │  │  + Add Domain     │    │
+│  └─────────────────────────────────┘  └───────────────────┘    │
+│                                                                 │
+│  To verify, add a CNAME record:                                 │
+│  og.mysite.com → proxy.loopwind.dev                            │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**DNS setup:**
+
+```
+# Add CNAME record in your DNS provider
+og.mysite.com  CNAME  proxy.loopwind.dev
+```
+
+**Routing options:**
+
+| Mode | URL Pattern | Use Case |
+|------|-------------|----------|
+| Single template | `og.mysite.com?title=Hello` | One domain = one template |
+| Multi template | `og.mysite.com/blog-og?title=Hello` | One domain = multiple templates |
+
+**API endpoints:**
+
+```
+POST /api/organizations/:org_id/domains
+{ "domain": "og.mysite.com", "templateId": "tpl_abc" }
+→ 201 { "domain": "og.mysite.com", "verificationRecord": "proxy.loopwind.dev", "verified": false }
+
+GET /api/organizations/:org_id/domains
+→ 200 { "domains": [...] }
+
+DELETE /api/organizations/:org_id/domains/:domain
+→ 204
+```
+
+---
+
+### POST - API-Based Rendering
+
+Best for complex props, arrays, nested objects, programmatic use.
+
+```bash
+curl -X POST https://api.loopwind.dev/r/x7k9m2p4 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "props": {
+      "title": "Hello World",
+      "subtitle": "Welcome to Loopwind",
+      "features": ["Fast", "Simple", "Beautiful"],
+      "author": {
+        "name": "Jane Doe",
+        "avatar": "https://example.com/avatar.jpg"
+      }
+    },
+    "format": "png",
+    "width": 1200,
+    "height": 630
+  }' \
+  --output image.png
+
+→ 200 (binary image data)
+```
+
+**Request Body:**
+
+```typescript
+interface RenderRequest {
+  // Template props (required)
+  props: Record<string, any>;
+
+  // Version pinning (optional, default: "latest")
+  version?: string;  // "1.0.0" | "latest"
+
+  // Output format (optional, default: "png")
+  format?: "png" | "webp" | "jpg" | "svg" | "mp4" | "gif";
+
+  // Size override (optional, uses template defaults)
+  width?: number;
+  height?: number;
+
+  // Video options (only for mp4/gif)
+  fps?: number;
+  duration?: number;
+  crf?: number;
+
+  // Webhook for async video rendering
+  webhook?: string;
+}
+```
+
+**Examples:**
+
+```bash
+# Simple image
+curl -X POST https://api.loopwind.dev/r/x7k9m2p4 \
+  -H "Content-Type: application/json" \
+  -d '{"props": {"title": "Hello"}}' \
+  --output hello.png
+
+# With format and size
+curl -X POST https://api.loopwind.dev/r/x7k9m2p4 \
+  -H "Content-Type: application/json" \
+  -d '{"props": {"title": "Hello"}, "format": "webp", "width": 800}' \
+  --output hello.webp
+
+# Array props (changelog video)
+curl -X POST https://api.loopwind.dev/r/abc123 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "props": {
+      "version": "v2.0.0",
+      "title": "Major Release",
+      "changes": [
+        "New dashboard UI",
+        "Fixed authentication bug",
+        "Improved performance by 50%"
+      ]
+    },
+    "format": "mp4"
+  }'
+```
+
+**JavaScript/TypeScript:**
+
+```typescript
+// POST with complex props
+const response = await fetch('https://api.loopwind.dev/r/x7k9m2p4', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    props: {
+      title: 'My Blog Post',
+      tags: ['tech', 'tutorial', 'react'],
+      author: { name: 'Jane', avatar: 'https://...' }
+    },
+    format: 'webp'
+  })
+});
+
+const image = await response.arrayBuffer();
+```
+
+**Python:**
+
+```python
+import requests
+
+response = requests.post(
+    'https://api.loopwind.dev/r/x7k9m2p4',
+    json={
+        'props': {
+            'title': 'Hello World',
+            'items': ['One', 'Two', 'Three']
+        },
+        'format': 'png'
+    }
+)
+
+with open('output.png', 'wb') as f:
+    f.write(response.content)
+```
+
+---
+
+### GET vs POST
+
+| | GET | POST |
+|---|---|---|
+| Props | Query string | JSON body |
+| Caching | CDN cacheable | Not cacheable by default |
+| Use case | OG images, `<img>` tags | API calls, complex data |
+| Arrays/Objects | URL-encoded (messy) | Native JSON |
+| Max size | ~2KB URL limit | 10MB body |
+
+**When to use GET:**
+- OG meta tags (`<meta property="og:image">`)
+- Direct `<img src="...">` usage
+- Simple string props
+- When caching is important
+
+**When to use POST:**
+- Complex/nested props
+- Arrays (like changelog items)
+- Programmatic rendering (scripts, CI/CD)
+- Large prop values
+
+### Video Rendering (Asynchronous)
+
+Videos require async processing. Add `format=mp4` or `format=gif`:
+
+```
+GET https://api.loopwind.dev/r/x7k9m2p4?title=Launch&format=mp4
+
+→ 202 {
   "jobId": "job_abc123",
-  "status": "processing",               // queued, processing, completed, failed
-  "progress": 0.45,                     // 0-1 for video
-  "currentFrame": 45,
-  "totalFrames": 100,
-  "createdAt": "2025-01-05T...",
-  "startedAt": "2025-01-05T..."
+  "status": "queued",
+  "statusUrl": "https://api.loopwind.dev/jobs/job_abc123",
+  "estimatedDuration": 15000
 }
+```
+
+**Poll for completion:**
+
+```
+GET https://api.loopwind.dev/jobs/job_abc123
 
-// When completed:
 → 200 {
-  "jobId": "job_abc123",
   "status": "completed",
-  "progress": 1,
   "outputUrl": "https://cdn.loopwind.dev/renders/job_abc123.mp4",
-  "expiresAt": "2025-01-06T...",        // URL expires in 24h
-  "duration": 12500,                    // Render time in ms
-  "completedAt": "2025-01-05T..."
+  "expiresAt": "2025-01-06T..."
 }
 ```
 
-### Webhook Payload
+### Webhook (Optional)
 
+Add a webhook query param to get notified when video is ready:
+
+```
+GET https://api.loopwind.dev/r/x7k9m2p4?title=Launch&format=mp4&webhook=https://myapp.com/hooks/render
 ```
-POST https://myapp.com/hooks/render-complete
-Content-Type: application/json
-X-Loopwind-Signature: sha256=...
 
+```json
+// POST to your webhook
 {
   "event": "render.completed",
   "jobId": "job_abc123",
-  "status": "completed",
-  "outputUrl": "https://cdn.loopwind.dev/renders/job_abc123.mp4",
-  "template": "username/promo-video",
-  "format": "mp4",
-  "duration": 12500,
-  "timestamp": "2025-01-05T..."
+  "outputUrl": "https://cdn.loopwind.dev/renders/job_abc123.mp4"
 }
 ```
 
-### CLI Remote Rendering
+### CLI Output After Publish
 
 ```bash
-# Render using cloud API (fast, no local compute)
-$ loopwind render my-template --remote --props '{"title": "Hello"}'
-✓ Rendered in 234ms
-  Output: https://cdn.loopwind.dev/renders/rnd_xyz789.png
+$ loopwind publish og-card
+
+✓ Published og-card v1.0.0
+
+  Included:
+    - template.tsx (2.1 KB)
+    - template.js (1.4 KB)
+    - config: 12 colors, 2 fonts
+    - assets: logo.png (15 KB)
+
+  Render URL: https://api.loopwind.dev/r/x7k9m2p4
+
+  Usage:
+    <img src="https://api.loopwind.dev/r/x7k9m2p4?title=Hello" />
+
+  Props:
+    - title (string, required)
+    - subtitle (string, optional)
+```
+
+### Render Flow (with Caching)
+
+Rendered images are cached in R2 for fast subsequent requests:
+
+```
+GET /r/x7k9m2p4?title=Hello
+         │
+         ▼
+┌────────────────────────────────────────────────────────────────┐
+│  1. Cache Check (R2)                                           │
+│                                                                │
+│  cache_key = hash(template_id + props + format + size)         │
+│  cached = await R2.get(cache_key)                              │
+│                                                                │
+│  if (cached) {                                                 │
+│    track('hit', template_id)  ← Analytics Engine               │
+│    return cached              ← Fast path (~10ms)              │
+│  }                                                             │
+└────────────────────────────────────────────────────────────────┘
+         │ (cache miss)
+         ▼
+┌────────────────────────────────────────────────────────────────┐
+│  2. Lookup & Load                                              │
+│                                                                │
+│  Worker: token → D1 → org_id + template_id                    │
+│  Org DO: load template.js, config, fonts                      │
+└────────────────────────────────────────────────────────────────┘
+         │
+         ▼
+┌────────────────────────────────────────────────────────────────┐
+│  3. Render (SDK)                                               │
+│                                                                │
+│  import { createRenderer } from 'loopwind';                    │
+│                                                                │
+│  // Create renderer with stored config                         │
+│  const render = createRenderer({                               │
+│    colors: config.colors,                                      │
+│    fonts: config.fonts,                                        │
+│    tokens: config.tokens,                                      │
+│    fontFiles: loadedFontFiles,                                 │
+│  });                                                           │
+│                                                                │
+│  // Execute stored template.js                                 │
+│  const Template = await import(templateJsBlob);                │
+│                                                                │
+│  const png = await render(Template.default, {                  │
+│    props: { title: 'Hello' },                                  │
+│    width: meta.width,                                          │
+│    height: meta.height,                                        │
+│    format: 'png',                                              │
+│  });                                                           │
+└────────────────────────────────────────────────────────────────┘
+         │
+         ▼
+┌────────────────────────────────────────────────────────────────┐
+│  4. Cache & Track                                              │
+│                                                                │
+│  // Store in R2 for future requests                            │
+│  await R2.put(cache_key, png, {                                │
+│    httpMetadata: { contentType: 'image/png' },                 │
+│    customMetadata: { template_id, org_id }                    │
+│  });                                                           │
+│                                                                │
+│  // Track render (not hit - this was a fresh render)           │
+│  track('render', template_id)  ← Analytics Engine              │
+│                                                                │
+│  return png;                                                   │
+└────────────────────────────────────────────────────────────────┘
+```
+
+**Summary:**
+- **Hit** = Served from R2 cache (~10ms)
+- **Render** = Fresh render, then cached (~200-2000ms)
+
+---
 
-# For videos (async)
-$ loopwind render promo-video --remote --format mp4 --props '{"title": "Launch"}'
-⠋ Rendering video... 45% (45/100 frames)
-✓ Rendered in 12.5s
-  Output: https://cdn.loopwind.dev/renders/job_abc123.mp4
+### Caching Strategy
+
+**R2 Cache Keys:**
+
+```typescript
+// Cache key = deterministic hash of all render inputs INCLUDING version
+function getCacheKey(
+  templateId: string,
+  version: string,    // "1.0.0" or "latest" resolved to actual version
+  props: object,
+  format: string,
+  width: number,
+  height: number
+): string {
+  const input = JSON.stringify({ templateId, version, props, format, width, height });
+  return crypto.createHash('sha256').update(input).digest('hex').slice(0, 32);
+}
+
+// Example: "a3f8c2e1b4d9..."
+// Different versions = different cache keys = no accidental cache hits
+```
+
+**Cache Invalidation:**
+
+| Event | Action |
+|-------|--------|
+| Template updated | Delete all cached renders for template |
+| Manual purge | `DELETE /api/templates/:id/cache` |
+| TTL expiry | R2 lifecycle rule (default: 7 days) |
+
+```typescript
+// Invalidate cache when template is updated
+async function invalidateTemplateCache(templateId: string) {
+  const objects = await R2.list({ prefix: `renders/${templateId}/` });
+  await Promise.all(objects.objects.map(obj => R2.delete(obj.key)));
+}
+```
+
+**R2 Storage Structure:**
+
+```
+renders/
+├── {template_id}/
+│   ├── {cache_key}.png
+│   ├── {cache_key}.webp
+│   └── {cache_key}.mp4
+```
+
+---
+
+### Analytics & Tracking
+
+Use Cloudflare Analytics Engine for high-throughput, low-latency tracking:
+
+**Why Analytics Engine:**
+- Handles millions of events/second
+- No blocking - fire and forget
+- Built-in aggregation queries
+- 90-day retention (configurable)
+
+**Track Two Event Types:**
+
+```typescript
+// In render worker
+analytics.writeDataPoint({
+  blobs: [org_id, template_id, format],
+  doubles: [1],  // count
+  indexes: [event_type]  // 'render' or 'hit'
+});
+```
+
+| Event | When | Meaning |
+|-------|------|---------|
+| `render` | Cache miss, fresh render | Actual CPU/rendering work |
+| `hit` | Cache hit from R2 | Fast serve, no rendering |
+
+**Query Analytics:**
+
+```typescript
+// Get stats for a template
+const stats = await analytics.query(`
+  SELECT
+    index1 as event_type,
+    sum(double1) as count
+  FROM analytics
+  WHERE
+    blob1 = '${org_id}'
+    AND blob2 = '${template_id}'
+    AND timestamp > now() - interval '30' day
+  GROUP BY index1
+`);
+
+// Returns: [{ event_type: 'render', count: 150 }, { event_type: 'hit', count: 4500 }]
+```
+
+**Dashboard Stats API:**
+
+```
+GET /api/organizations/:org_id/analytics
+  ?period=7d|30d|90d
+  ?template_id=optional
+
+→ 200 {
+  "period": "30d",
+  "totals": {
+    "renders": 1250,
+    "hits": 45000,
+    "cacheHitRate": 0.973
+  },
+  "byTemplate": [
+    {
+      "template_id": "tpl_abc",
+      "name": "og-card",
+      "renders": 500,
+      "hits": 20000,
+      "cacheHitRate": 0.975
+    },
+    {
+      "template_id": "tpl_def",
+      "name": "changelog-video",
+      "renders": 750,
+      "hits": 25000,
+      "cacheHitRate": 0.971
+    }
+  ],
+  "timeSeries": [
+    { "date": "2025-01-01", "renders": 40, "hits": 1500 },
+    { "date": "2025-01-02", "renders": 45, "hits": 1600 },
+    ...
+  ]
+}
+```
+
+**Per-Template Stats:**
+
+```
+GET /api/templates/:id/analytics
+  ?period=7d|30d|90d
+
+→ 200 {
+  "template": {
+    "id": "tpl_abc",
+    "name": "og-card"
+  },
+  "period": "30d",
+  "renders": 500,
+  "hits": 20000,
+  "cacheHitRate": 0.975,
+  "uniqueProps": 450,  // Different prop combinations
+  "avgRenderTime": 234,  // ms
+  "timeSeries": [...],
+  "topProps": [
+    { "props": {"title": "Welcome"}, "hits": 5000 },
+    { "props": {"title": "About Us"}, "hits": 3200 }
+  ]
+}
+```
+
+**Organization Dashboard Overview:**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Organization: my-org                                     Last 30 days │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Total Requests     Renders          Hits         Cache Rate    │
+│  ┌──────────┐      ┌──────────┐     ┌──────────┐  ┌──────────┐  │
+│  │  46,250  │      │   1,250  │     │  45,000  │  │   97.3%  │  │
+│  └──────────┘      └──────────┘     └──────────┘  └──────────┘  │
+│                                                                 │
+│  Templates                                                      │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ Name           Renders    Hits     Cache    Avg Time    │   │
+│  ├─────────────────────────────────────────────────────────┤   │
+│  │ og-card           500   20,000     97.5%      234ms     │   │
+│  │ changelog-video   750   25,000     97.1%    1,240ms     │   │
+│  │ banner-hero        50    5,000     99.0%      189ms     │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+│  Request Volume (30 days)                                       │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ █                                                        │   │
+│  │ █ █   █                                                  │   │
+│  │ █ █ █ █ █   █ █                                          │   │
+│  │ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -433,7 +1563,7 @@ Authorization: Bearer <token>
 ### Business Tier ($99/month)
 - 50,000 image renders/month
 - 5,000 video renders/month
-- Team accounts
+- Organization accounts
 - Custom domains
 - SLA guarantee
 - Rate limit: 500 req/min
@@ -456,16 +1586,214 @@ X-RateLimit-Reset: 1704499200
 | Component | Technology | Why |
 |-----------|------------|-----|
 | API Gateway | Cloudflare Workers | Rate limiting, auth, routing - all at edge |
-| Auth | Workers + D1 | JWT validation, session management |
-| Database | D1 (SQLite) / Turso | Users, templates, jobs - edge-native |
-| Cache | Workers KV | Sessions, rate limits, template cache |
-| Queue | Durable Objects | Video job orchestration |
-| Storage | R2 | Templates, rendered outputs |
+| Auth | Workers + D1 | JWT validation, global user accounts |
+| Global Database | D1 (SQLite) | Users, API keys, billing - shared across organizations |
+| Analytics | Analytics Engine | High-throughput render/hit tracking, millisecond writes |
+| Org Storage | Durable Objects + SQLite | Templates, files, jobs - isolated per organization |
+| Cache | Workers KV | Sessions, rate limits, font cache |
+| Render Cache | R2 | Rendered outputs (images/videos) |
 | CDN | Cloudflare CDN | Automatic, integrated with R2 |
 | Image Rendering | Workers (WASM) | Satori + Resvg, up to 5min CPU |
 | Video Rendering | Containers | FFmpeg, unlimited duration, GPU support |
 | Monitoring | Workers Analytics + Sentry | Built-in metrics + error tracking |
 
+### Data Architecture: DO SQLite per Organization
+
+Each organization gets its own Durable Object with embedded SQLite database. This provides:
+
+- **Isolation** - Organization data is completely separate
+- **Performance** - Data co-located, no cross-region queries
+- **Consistency** - Strong transactional guarantees within organization
+- **Scalability** - Organizations scale independently
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           Global Layer (D1)                              │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │  users, api_keys, organizations, billing, usage_summary                 │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                    ┌───────────────┼───────────────┐
+                    ▼               ▼               ▼
+┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
+│  OrgDO: org_abc     │ │  OrgDO: org_def     │ │  OrgDO: org_ghi     │
+│  ┌─────────────────┐  │ │  ┌─────────────────┐  │ │  ┌─────────────────┐  │
+│  │ SQLite Database │  │ │  │ SQLite Database │  │ │  │ SQLite Database │  │
+│  │                 │  │ │  │                 │  │ │  │                 │  │
+│  │ • templates     │  │ │  │ • templates     │  │ │  │ • templates     │  │
+│  │ • template_files│  │ │  │ • template_files│  │ │  │ • template_files│  │
+│  │ • render_jobs   │  │ │  │ • render_jobs   │  │ │  │ • render_jobs   │  │
+│  │ • assets        │  │ │  │ • assets        │  │ │  │ • assets        │  │
+│  └─────────────────┘  │ │  └─────────────────┘  │ │  └─────────────────┘  │
+└───────────────────────┘ └───────────────────────┘ └───────────────────────┘
+```
+
+#### Org Durable Object
+
+```typescript
+export class OrgStorage extends DurableObject {
+  sql: SqlStorage;
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.sql = ctx.storage.sql;
+
+    // Initialize schema on first access
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS templates (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL UNIQUE,
+        description TEXT,
+        type TEXT NOT NULL,  -- 'image' | 'video'
+        meta TEXT NOT NULL,  -- JSON: { width, height, fps, duration, props }
+        config TEXT,         -- JSON: loopwind.json (colors, fonts, tokens)
+        private INTEGER DEFAULT 0,
+        tags TEXT,           -- JSON array
+        created_at INTEGER DEFAULT (unixepoch()),
+        updated_at INTEGER DEFAULT (unixepoch())
+      );
+
+      CREATE TABLE IF NOT EXISTS template_files (
+        id TEXT PRIMARY KEY,
+        template_id TEXT NOT NULL REFERENCES templates(id),
+        path TEXT NOT NULL,
+        content BLOB NOT NULL,
+        content_type TEXT,
+        checksum TEXT,
+        size INTEGER,
+        created_at INTEGER DEFAULT (unixepoch()),
+        UNIQUE(template_id, path)
+      );
+
+      CREATE TABLE IF NOT EXISTS assets (
+        id TEXT PRIMARY KEY,
+        path TEXT NOT NULL UNIQUE,
+        content BLOB NOT NULL,
+        content_type TEXT,
+        size INTEGER,
+        created_at INTEGER DEFAULT (unixepoch())
+      );
+
+      CREATE TABLE IF NOT EXISTS render_jobs (
+        id TEXT PRIMARY KEY,
+        template_id TEXT REFERENCES templates(id),
+        status TEXT DEFAULT 'queued',
+        props TEXT,          -- JSON
+        format TEXT,
+        output_url TEXT,
+        error TEXT,
+        progress REAL DEFAULT 0,
+        started_at INTEGER,
+        completed_at INTEGER,
+        created_at INTEGER DEFAULT (unixepoch())
+      );
+    `);
+  }
+
+  // Template CRUD
+  async createTemplate(data: TemplateInput): Promise<Template> {
+    const id = crypto.randomUUID();
+    this.sql.exec(`
+      INSERT INTO templates (id, name, description, type, meta, private, tags)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `, id, data.name, data.description, data.type, JSON.stringify(data.meta),
+       data.private ? 1 : 0, JSON.stringify(data.tags || []));
+    return this.getTemplate(id);
+  }
+
+  async getTemplate(id: string): Promise<Template | null> {
+    const row = this.sql.exec(`SELECT * FROM templates WHERE id = ?`, id).one();
+    return row ? this.parseTemplate(row) : null;
+  }
+
+  async listTemplates(): Promise<Template[]> {
+    return this.sql.exec(`SELECT * FROM templates ORDER BY updated_at DESC`)
+      .toArray()
+      .map(row => this.parseTemplate(row));
+  }
+
+  // File storage (templates are stored as files, not R2)
+  async saveFile(templateId: string, path: string, content: ArrayBuffer, contentType: string) {
+    const id = crypto.randomUUID();
+    const checksum = await this.hash(content);
+    this.sql.exec(`
+      INSERT OR REPLACE INTO template_files (id, template_id, path, content, content_type, checksum, size)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `, id, templateId, path, content, contentType, checksum, content.byteLength);
+  }
+
+  async getFile(templateId: string, path: string): Promise<ArrayBuffer | null> {
+    const row = this.sql.exec(
+      `SELECT content FROM template_files WHERE template_id = ? AND path = ?`,
+      templateId, path
+    ).one();
+    return row?.content as ArrayBuffer | null;
+  }
+
+  async getTemplateFiles(templateId: string): Promise<FileInfo[]> {
+    return this.sql.exec(
+      `SELECT path, content_type, checksum, size FROM template_files WHERE template_id = ?`,
+      templateId
+    ).toArray();
+  }
+
+  // Render jobs
+  async createJob(templateId: string, props: object, format: string): Promise<string> {
+    const id = crypto.randomUUID();
+    this.sql.exec(`
+      INSERT INTO render_jobs (id, template_id, props, format)
+      VALUES (?, ?, ?, ?)
+    `, id, templateId, JSON.stringify(props), format);
+    return id;
+  }
+
+  async updateJobProgress(jobId: string, progress: number) {
+    this.sql.exec(`UPDATE render_jobs SET progress = ? WHERE id = ?`, progress, jobId);
+  }
+
+  async completeJob(jobId: string, outputUrl: string) {
+    this.sql.exec(`
+      UPDATE render_jobs
+      SET status = 'completed', output_url = ?, progress = 1, completed_at = unixepoch()
+      WHERE id = ?
+    `, outputUrl, jobId);
+  }
+
+  private async hash(data: ArrayBuffer): Promise<string> {
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    return [...new Uint8Array(hashBuffer)].map(b => b.toString(16).padStart(2, '0')).join('');
+  }
+
+  private parseTemplate(row: any): Template {
+    return {
+      ...row,
+      meta: JSON.parse(row.meta),
+      tags: JSON.parse(row.tags || '[]'),
+      private: Boolean(row.private),
+    };
+  }
+}
+```
+
+#### Worker Routing to Org DO
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const orgId = await getOrgFromAuth(request, env);
+
+    // Get organization's Durable Object
+    const orgDO = env.ORG_STORAGE.get(
+      env.ORG_STORAGE.idFromName(orgId)
+    );
+
+    // Forward request to organization's DO
+    return orgDO.fetch(request);
+  }
+};
+```
+
 ### Deployment Architecture
 
 ```
@@ -515,11 +1843,12 @@ X-RateLimit-Reset: 1704499200
 │  ┌─────────────────────────────────────────────────────────────────┐   │
 │  │                        Data Layer                                │   │
 │  │                                                                  │   │
-│  │   D1 (SQLite)          KV                    R2                  │   │
-│  │   • Users              • Sessions            • Templates         │   │
-│  │   • Templates          • Rate limits         • Rendered videos   │   │
-│  │   • Jobs               • Template cache      • Assets            │   │
-│  │   • Usage              • Font cache                              │   │
+│  │   D1 (Global)      Org DOs       KV          R2       Analytics │   │
+│  │   • Users          • Templates    • Sessions  • Render  Engine   │   │
+│  │   • Orgs          • Template     • Rate        cache   • Renders│   │
+│  │   • API keys         files          limits    (images/  • Hits   │   │
+│  │   • Billing        • Assets       • Font        videos) • Stats  │   │
+│  │   • Template index                           cache                │   │
 │  │                                                                  │   │
 │  └─────────────────────────────────────────────────────────────────┘   │
 │                                                                        │
@@ -669,9 +1998,17 @@ database_name = "loopwind"
 binding = "STORAGE"
 bucket_name = "loopwind-assets"
 
+[[r2_buckets]]
+binding = "RENDER_CACHE"
+bucket_name = "loopwind-renders"
+
 [[kv_namespaces]]
 binding = "CACHE"
 id = "xxx"
+
+[[analytics_engine_datasets]]
+binding = "ANALYTICS"
+dataset = "loopwind_events"
 ```
 
 ### Rendering Decision Flow
@@ -738,22 +2075,19 @@ loopwind logout             # Clear credentials
 loopwind whoami             # Show current user
 
 # Publishing
-loopwind publish [template] # Publish template to registry
-  --version <ver>           # Semantic version
-  --private                 # Private template
+loopwind publish [template] # Publish template to platform
+  --private                 # Private template (requires auth to render)
   --dry-run                 # Validate only
 
-# Remote rendering
-loopwind render <template>  # Render (local by default)
-  --remote                  # Use cloud API
+# Local rendering (unchanged)
+loopwind render <template>  # Render locally
   --props <json>            # Template props
   --format <fmt>            # Output format
-  --out <path>              # Save locally
+  --out <path>              # Output file
 
-# Account management
-loopwind keys list          # List API keys
-loopwind keys create        # Create new API key
-loopwind keys revoke <id>   # Revoke API key
+# Template management
+loopwind templates          # List published templates
+loopwind unpublish <name>   # Remove from platform
 ```
 
 ### Credential Storage
@@ -828,158 +2162,224 @@ Templates run in isolated environment:
 
 ## Database Schema
 
+### Global D1 Database (shared)
+
+For data that needs to be queried globally (auth, billing, discovery):
+
 ```sql
 -- Users
 CREATE TABLE users (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  email VARCHAR(255) UNIQUE NOT NULL,
-  username VARCHAR(50) UNIQUE NOT NULL,
-  password_hash VARCHAR(255),
-  name VARCHAR(255),
-  avatar_url VARCHAR(500),
-  plan VARCHAR(20) DEFAULT 'free',
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW()
-);
-
--- API Keys
-CREATE TABLE api_keys (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
-  name VARCHAR(100) NOT NULL,
-  key_hash VARCHAR(255) NOT NULL,
-  key_prefix VARCHAR(12) NOT NULL,  -- lw_live_xxxx for display
-  scopes TEXT[] DEFAULT '{}',
-  last_used_at TIMESTAMP,
-  created_at TIMESTAMP DEFAULT NOW()
+  id TEXT PRIMARY KEY,
+  email TEXT UNIQUE NOT NULL,
+  username TEXT UNIQUE NOT NULL,
+  password_hash TEXT,
+  name TEXT,
+  avatar_url TEXT,
+  plan TEXT DEFAULT 'free',
+  created_at INTEGER DEFAULT (unixepoch()),
+  updated_at INTEGER DEFAULT (unixepoch())
 );
 
--- Templates
-CREATE TABLE templates (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
-  name VARCHAR(100) NOT NULL,
-  slug VARCHAR(150) NOT NULL,  -- username/template-name
-  description TEXT,
-  type VARCHAR(20) NOT NULL,  -- image, video
-  meta JSONB NOT NULL,
-  private BOOLEAN DEFAULT FALSE,
-  tags TEXT[] DEFAULT '{}',
-  downloads INTEGER DEFAULT 0,
-  renders INTEGER DEFAULT 0,
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW(),
-  UNIQUE(user_id, name)
+-- Organizations
+CREATE TABLE organizations (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  slug TEXT UNIQUE NOT NULL,
+  owner_id TEXT NOT NULL REFERENCES users(id),
+  plan TEXT DEFAULT 'free',
+  created_at INTEGER DEFAULT (unixepoch())
 );
 
--- Template Versions
-CREATE TABLE template_versions (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  template_id UUID REFERENCES templates(id) ON DELETE CASCADE,
-  version VARCHAR(20) NOT NULL,
-  files JSONB NOT NULL,  -- [{path, url, checksum}]
-  published_at TIMESTAMP DEFAULT NOW(),
-  UNIQUE(template_id, version)
+-- Organization members
+CREATE TABLE org_members (
+  org_id TEXT NOT NULL REFERENCES organizations(id),
+  user_id TEXT NOT NULL REFERENCES users(id),
+  role TEXT DEFAULT 'member',  -- 'owner' | 'admin' | 'member'
+  created_at INTEGER DEFAULT (unixepoch()),
+  PRIMARY KEY (org_id, user_id)
 );
 
--- Render Jobs
-CREATE TABLE render_jobs (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id UUID REFERENCES users(id),
-  template_id UUID REFERENCES templates(id),
-  status VARCHAR(20) DEFAULT 'queued',
-  props JSONB,
-  format VARCHAR(10),
-  output_url VARCHAR(500),
-  error TEXT,
-  progress FLOAT DEFAULT 0,
-  started_at TIMESTAMP,
-  completed_at TIMESTAMP,
-  created_at TIMESTAMP DEFAULT NOW()
+-- API Keys (scoped to organization)
+CREATE TABLE api_keys (
+  id TEXT PRIMARY KEY,
+  org_id TEXT NOT NULL REFERENCES organizations(id),
+  created_by TEXT NOT NULL REFERENCES users(id),
+  name TEXT NOT NULL,
+  key_hash TEXT NOT NULL,
+  key_prefix TEXT NOT NULL,  -- lw_live_xxxx for display
+  scopes TEXT,               -- JSON array
+  last_used_at INTEGER,
+  created_at INTEGER DEFAULT (unixepoch())
 );
 
--- Usage tracking
+-- Usage tracking (for billing)
 CREATE TABLE usage (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id UUID REFERENCES users(id),
-  type VARCHAR(20) NOT NULL,  -- image_render, video_render, publish
+  id TEXT PRIMARY KEY,
+  org_id TEXT NOT NULL REFERENCES organizations(id),
+  type TEXT NOT NULL,        -- 'image_render' | 'video_render' | 'storage_mb'
   count INTEGER DEFAULT 1,
-  month DATE NOT NULL,  -- First of month
-  UNIQUE(user_id, type, month)
+  month TEXT NOT NULL,       -- '2025-01'
+  UNIQUE(org_id, type, month)
+);
+
+-- Render tokens (random IDs for secure URLs)
+-- Maps random token → org + template for rendering
+CREATE TABLE render_tokens (
+  token TEXT PRIMARY KEY,     -- 'x7k9m2p4' (random, used in URL)
+  org_id TEXT NOT NULL REFERENCES organizations(id),
+  template_id TEXT NOT NULL,  -- References template in organization's DO
+  created_at INTEGER DEFAULT (unixepoch()),
+  revoked_at INTEGER          -- Set to revoke token
 );
+CREATE INDEX idx_render_tokens_team ON render_tokens(org_id);
+
+-- Custom domains for render URLs
+CREATE TABLE custom_domains (
+  domain TEXT PRIMARY KEY,              -- 'og.mysite.com'
+  org_id TEXT NOT NULL REFERENCES organizations(id),
+  template_id TEXT,                     -- NULL = route to all templates via /name
+  verified_at INTEGER,                  -- NULL = pending verification
+  created_at INTEGER DEFAULT (unixepoch())
+);
+CREATE INDEX idx_custom_domains_team ON custom_domains(org_id);
+
+-- Allowed hosts for external images (per organization)
+CREATE TABLE allowed_hosts (
+  id TEXT PRIMARY KEY,
+  org_id TEXT NOT NULL REFERENCES organizations(id),
+  pattern TEXT NOT NULL,                -- 'cdn.example.com' or '*.amazonaws.com'
+  created_at INTEGER DEFAULT (unixepoch()),
+  UNIQUE(org_id, pattern)
+);
+CREATE INDEX idx_allowed_hosts_team ON allowed_hosts(org_id);
 ```
 
+### KV Caching for Render Tokens
+
+For fast token lookups, cache render token data in KV:
+
+```typescript
+// Render token lookup with KV cache
+async function lookupRenderToken(token: string, env: Env) {
+  // 1. Check KV cache first (~1ms)
+  const cached = await env.KV.get(`rt:${token}`, 'json');
+  if (cached) {
+    return cached;  // { org_id, template_id }
+  }
+
+  // 2. Cache miss - query D1 (~5-10ms)
+  const row = await env.DB.prepare(`
+    SELECT org_id, template_id FROM render_tokens
+    WHERE token = ? AND revoked_at IS NULL
+  `).bind(token).first();
+
+  if (!row) return null;
+
+  // 3. Cache for 1 hour
+  await env.KV.put(`rt:${token}`, JSON.stringify(row), {
+    expirationTtl: 3600
+  });
+
+  return row;
+}
+
+// Invalidate on token revocation
+async function revokeRenderToken(token: string, env: Env) {
+  await env.DB.prepare(`
+    UPDATE render_tokens SET revoked_at = unixepoch() WHERE token = ?
+  `).bind(token).run();
+
+  await env.KV.delete(`rt:${token}`);
+}
+```
+
+### Org Durable Object SQLite (per organization)
+
+Each organization's templates, files, and jobs are stored in their own DO. See `OrgStorage` class above for schema:
+
+- `templates` - Template metadata
+- `template_files` - Template source code and assets (stored as BLOBs)
+- `assets` - Shared assets (fonts, images)
+- `render_jobs` - Job queue and history
+
+**Why split this way?**
+
+| Data | Storage | Reason |
+|------|---------|--------|
+| Users, organizations | D1 | Global auth, cross-org queries |
+| API keys | D1 | Fast validation at edge |
+| Render tokens | D1 | Fast lookup: token → org + template |
+| Billing/usage | D1 | Aggregation for invoicing |
+| Template source | DO SQLite | Organization isolation, co-located with files |
+| Template files | DO SQLite | Binary storage with transactional updates |
+| Render jobs | DO SQLite | Per-org job queue, no cross-org leakage |
+
 ---
 
 ## Implementation Phases
 
 ### Phase 1: Authentication & Publishing
 - User registration/login
-- API key management
 - `loopwind login/logout/whoami` commands
 - `loopwind publish` command
-- Template storage in R2
-- Basic registry API
+- Org Durable Object with SQLite storage
+- Generate random template IDs for render URLs
 
 ### Phase 2: Image Rendering API
-- Synchronous image rendering endpoint
-- `loopwind render --remote` for images
+- GET `/r/{id}` endpoint for image rendering
+- Query param parsing for props
+- Edge caching with Cache API
 - Rate limiting
 - Usage tracking
 
 ### Phase 3: Video Rendering & Queue
-- Async video rendering with job queue
+- Async video rendering with Cloudflare Containers
+- Job status polling endpoint
 - Webhook notifications
 - Progress tracking
-- `loopwind render --remote` for videos
 
-### Phase 4: Marketplace & Discovery
-- Template search and browse
-- User profiles
-- Download/star tracking
-- loopwind.dev website updates
-
-### Phase 5: Billing & Pro Features
+### Phase 4: Dashboard & Billing
+- loopwind.dev dashboard for managing templates
+- View render URLs and usage stats
 - Stripe integration
-- Usage-based billing
-- Private templates
-- Team accounts
+- Private templates (auth required to render)
+
+### Phase 5: Organization Features
+- Organization accounts with multiple members
+- Shared templates within organization
+- Role-based access control
 
 ---
 
-## API Client SDK
+## Using Published Templates
 
-For easy integration, provide official SDKs:
+No SDK required - just use the render URL directly:
+
+```html
+<!-- Static HTML -->
+<img src="https://api.loopwind.dev/r/x7k9m2p4?title=Hello" />
+```
 
 ```typescript
 // JavaScript/TypeScript
-import { Loopwind } from '@loopwind/sdk';
-
-const lw = new Loopwind({ apiKey: 'lw_live_xxx' });
-
-// Render image
-const image = await lw.render('username/og-card', {
-  props: { title: 'Hello World' },
-  format: 'png'
-});
-
-// Render video (async)
-const job = await lw.renderVideo('username/promo', {
-  props: { title: 'Launch' },
-  format: 'mp4'
-});
+const url = new URL('https://api.loopwind.dev/r/x7k9m2p4');
+url.searchParams.set('title', post.title);
+url.searchParams.set('format', 'webp');
 
-// Poll for completion
-const result = await job.wait();
-console.log(result.outputUrl);
+const response = await fetch(url);
+const image = await response.arrayBuffer();
+```
 
-// Or use webhook
-await lw.renderVideo('username/promo', {
-  props: { title: 'Launch' },
-  webhook: 'https://myapp.com/hooks/render'
-});
+```tsx
+// React/Next.js
+function OGImage({ title }: { title: string }) {
+  const url = `https://api.loopwind.dev/r/x7k9m2p4?title=${encodeURIComponent(title)}`;
+  return <img src={url} alt={title} />;
+}
 ```
 
+For local rendering without the platform, see [SDK.md](./SDK.md).
+
 ---
 
 ## References