whale-code 6.5.8 → 6.5.9

package/dist/server/handlers/api-docs.js

@@ -1,1517 +1,153 @@
-// server/handlers/api-docs.ts — Static API documentation reference for agents
+// server/handlers/api-docs.ts — Dynamic API documentation from gateway OpenAPI spec
 
 const GATEWAY_BASE_URL = "https://whale-gateway.fly.dev";
+const OPENAPI_URL = `${GATEWAY_BASE_URL}/openapi.json`;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 
 // ---------------------------------------------------------------------------
-// Types
+// Cached OpenAPI spec — fetched from gateway on demand
 // ---------------------------------------------------------------------------
 
-// ---------------------------------------------------------------------------
-// Endpoint registry — every public REST API route
-// ---------------------------------------------------------------------------
-
-const SECTIONS = {
-  products: {
-    name: "Products",
-    description: "Product catalog CRUD, variations, and categories",
-    base: "/v1/stores/:storeId/products",
-    endpoints: [{
-      method: "GET",
-      path: "/v1/stores/:storeId/products",
-      scope: "read:products",
-      description: "List products with pagination and filters",
-      params: {
-        limit: "Number (1-100, default 25)",
-        starting_after: "Product ID cursor for forward pagination",
-        ending_before: "Product ID cursor for backward pagination",
-        category_id: "Filter by category UUID",
-        status: "Filter by status: published, draft, archived",
-        type: "Filter by type: simple, variable, grouped",
-        search: "Full-text search on name and SKU",
-        include: "Set to 'none' to skip loading variations (faster for large catalogs)"
-      },
-      response: '{ object: "list", data: Product[], has_more: boolean, url: string }'
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/products/:id",
-      scope: "read:products",
-      description: "Get a single product with variations and inventory",
-      response: "Product (includes pricing_data, field_values, inventory, variations)"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/products",
-      scope: "write:products",
-      description: "Create a new product",
-      body: {
-        name: "Required. Product name",
-        sku: "SKU code",
-        category_id: "Category UUID",
-        status: "published | draft (default: draft)",
-        type: "simple | variable | grouped (default: simple)",
-        description: "Full description",
-        short_description: "Summary text",
-        cost_price: "Cost per unit",
-        pricing_data: "Pricing tiers JSON",
-        field_values: "Custom fields JSON (must match category field schema)",
-        featured_image: "Image URL",
-        image_gallery: "Array of image URLs",
-        manage_stock: "Boolean — track inventory",
-        stock_quantity: "Initial stock (if manage_stock)"
-      },
-      response: "Product"
-    }, {
-      method: "PATCH",
-      path: "/v1/stores/:storeId/products/:id",
-      scope: "write:products",
-      description: "Update an existing product (partial update)",
-      body: {
-        "...": "Any product fields to update"
-      },
-      response: "Product"
-    }, {
-      method: "DELETE",
-      path: "/v1/stores/:storeId/products/:id",
-      scope: "write:products",
-      description: "Archive a product (soft delete)",
-      response: "{ deleted: true }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/products/:id/variations",
-      scope: "read:products",
-      description: "List variations for a product",
-      response: '{ object: "list", data: Variation[] }'
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/products/:id/variations",
-      scope: "write:products",
-      description: "Create a product variation",
-      body: {
-        name: "Variation name (e.g. 'Small', '1oz')",
-        sku: "Variation SKU",
-        pricing_data: "Variation-specific pricing",
-        field_values: "Variation-specific field values",
-        stock_quantity: "Initial stock"
-      },
-      response: "Variation"
-    }, {
-      method: "PATCH",
-      path: "/v1/stores/:storeId/products/:id/variations/:variationId",
-      scope: "write:products",
-      description: "Update a variation",
-      body: {
-        "...": "Any variation fields"
-      },
-      response: "Variation"
-    }, {
-      method: "DELETE",
-      path: "/v1/stores/:storeId/products/:id/variations/:variationId",
-      scope: "write:products",
-      description: "Delete a variation",
-      response: "{ deleted: true }"
-    }]
-  },
-  orders: {
-    name: "Orders",
-    description: "Order management — list, view, update status, void, and refund",
-    base: "/v1/stores/:storeId/orders",
-    endpoints: [{
-      method: "GET",
-      path: "/v1/stores/:storeId/orders",
-      scope: "read:orders",
-      description: "List orders with pagination",
-      params: {
-        limit: "Number (1-100, default 25)",
-        starting_after: "Order ID cursor",
-        ending_before: "Order ID cursor",
-        status: "Filter: pending, confirmed, processing, shipped, delivered, cancelled",
-        customer_id: "Filter by customer UUID",
-        location_id: "Filter by location UUID",
-        created_after: "ISO datetime — filter orders created on or after this date",
-        created_before: "ISO datetime — filter orders created on or before this date"
-      },
-      response: '{ object: "list", data: Order[], has_more: boolean }'
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/orders/:id",
-      scope: "read:orders",
-      description: "Get a single order with line items",
-      response: "Order (includes line_items[], customer, payment_details)"
-    }, {
-      method: "PATCH",
-      path: "/v1/stores/:storeId/orders/:id",
-      scope: "write:orders",
-      description: "Update order status or fields",
-      body: {
-        status: "Order status: pending, confirmed, processing, preparing, packed, ready, shipped, in_transit, delivered, completed, cancelled, refunded",
-        fulfillment_status: "unfulfilled, partial, fulfilled, cancelled, shipped, in_transit, delivered, ready_for_pickup, ready",
-        tracking_number: "Shipping tracking number",
-        tracking_url: "Tracking URL",
-        shipping_service: "Carrier name",
-        shipping_method: "Shipping method",
-        staff_notes: "Internal notes"
-      },
-      response: "Order"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/orders/:id/void",
-      scope: "write:orders",
-      description: "Void an unsettled order",
-      response: "Order (status: voided)",
-      notes: "Only works on orders where payment has not yet settled"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/orders/:id/refund",
-      scope: "write:orders",
-      description: "Refund a settled order",
-      body: {
-        amount: "Partial refund amount (optional — omit for full refund)",
-        reason: "Refund reason"
-      },
-      response: "Order (includes refund details)"
-    }]
-  },
-  cart: {
-    name: "Cart",
-    description: "Shopping cart — create, add/update/remove items, view",
-    base: "/v1/stores/:storeId/cart",
-    endpoints: [{
-      method: "POST",
-      path: "/v1/stores/:storeId/cart",
-      scope: "write:cart",
-      description: "Create a new shopping cart",
-      body: {
-        customer_id: "Optional customer UUID",
-        location_id: "Optional location UUID (auto-resolves default)"
-      },
-      response: "Cart { id, items: [], totals }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/cart/:cartId",
-      scope: "read:cart",
-      description: "Get cart with all items and computed totals",
-      response: "Cart { id, items: CartItem[], totals: { subtotal, tax, total } }"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/cart/:cartId/items",
-      scope: "write:cart",
-      description: "Add an item to the cart",
-      body: {
-        product_id: "Required. Product UUID",
-        quantity: "Required. Number of units",
-        variation_id: "Variation UUID (for variable products)",
-        tier: "Pricing tier name (e.g. 'retail', 'wholesale')",
-        unit_price: "Override price (optional — auto-resolved from pricing_data)"
-      },
-      response: 'CartItem { object: "cart_item", id, product_id, product_name, quantity, unit_price, line_total }'
-    }, {
-      method: "PATCH",
-      path: "/v1/stores/:storeId/cart/:cartId/items/:itemId",
-      scope: "write:cart",
-      description: "Update cart item quantity",
-      body: {
-        quantity: "New quantity (must be >= 1)"
-      },
-      response: 'CartItem { object: "cart_item", id, quantity, unit_price, line_total }'
-    }, {
-      method: "DELETE",
-      path: "/v1/stores/:storeId/cart/:cartId/items/:itemId",
-      scope: "write:cart",
-      description: "Remove an item from the cart",
-      response: '{ object: "cart_item", id, deleted: true }'
-    }]
-  },
-  checkout: {
-    name: "Checkout",
-    description: "E-commerce checkout and POS payment intents",
-    base: "/v1/stores/:storeId/checkout",
-    endpoints: [{
-      method: "POST",
-      path: "/v1/stores/:storeId/checkout",
-      scope: "write:checkout",
-      description: "Convert a cart into an order (e-commerce checkout)",
-      body: {
-        cart_id: "Required. Cart UUID",
-        customer_email: "Customer email (auto-creates customer if not found)",
-        customer_name: "Customer name",
-        customer_id: "Existing customer UUID",
-        payment_method: "Payment method identifier",
-        opaque_data: "Authorize.Net card token { dataDescriptor, dataValue }",
-        bill_to: "Billing address { firstName, lastName, address, city, state, zip, country }",
-        ship_to: "Shipping address (same shape as bill_to)",
-        loyalty_code: "Loyalty/discount code",
-        loyalty_points_redeemed: "Points to redeem (integer >= 0)",
-        loyalty_discount_amount: "Discount amount from loyalty (number >= 0)"
-      },
-      response: 'Order { object: "order", id, order_number, status: "completed" }',
-      notes: "Cart is consumed — cannot be reused after successful checkout. Supports idempotency (returns existing order on replay)."
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/checkout/intents",
-      scope: "write:checkout",
-      description: "Create a payment intent (POS terminal flow)",
-      body: {
-        cartItems: "Required. Array of cart items",
-        paymentMethod: "Payment method (card, cash, etc.)",
-        locationId: "Location UUID",
-        registerId: "POS register ID",
-        sessionId: "POS session ID",
-        customerId: "Customer UUID",
-        customerName: "Customer name",
-        userId: "Staff user UUID",
-        tipAmount: "Tip amount",
-        cashTendered: "Cash amount given (for cash payments)",
-        changeGiven: "Change returned",
-        idempotencyKey: "Idempotency key for safe retries"
-      },
-      response: "PaymentIntent { id, status: 'created', amount }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/checkout/intents/:id",
-      scope: "read:checkout",
-      description: "Get payment intent status",
-      response: "PaymentIntent { id, status, amount, created_at }"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/checkout/intents/:id/capture",
-      scope: "write:checkout",
-      description: "Capture an authorized payment",
-      response: "PaymentIntent { status: 'captured' }"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/checkout/intents/:id/cancel",
-      scope: "write:checkout",
-      description: "Cancel a payment intent",
-      response: "PaymentIntent { status: 'cancelled' }"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/checkout/intents/:id/charge",
-      scope: "write:checkout",
-      description: "Charge via Dejavoo POS terminal",
-      body: {
-        terminal_id: "Dejavoo terminal ID"
-      },
-      response: "PaymentIntent (with terminal response)",
-      notes: "POS-specific — sends charge request to physical terminal"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/checkout/intents/:id/abort",
-      scope: "write:checkout",
-      description: "Abort an in-progress terminal charge",
-      response: "PaymentIntent { status: 'aborted' }"
-    }]
-  },
-  customers: {
-    name: "Customers",
-    description: "Customer CRM — CRUD and search",
-    base: "/v1/stores/:storeId/customers",
-    endpoints: [{
-      method: "GET",
-      path: "/v1/stores/:storeId/customers",
-      scope: "read:customers",
-      description: "List customers with pagination and search",
-      params: {
-        limit: "Number (1-100, default 25)",
-        starting_after: "Customer ID cursor",
-        search: "Search by name, email, or phone"
-      },
-      response: '{ object: "list", data: Customer[], has_more: boolean }'
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/customers/:id",
-      scope: "read:customers",
-      description: "Get a single customer with full profile",
-      response: "Customer (includes loyalty_points, total_spent, total_orders)"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/customers",
-      scope: "write:customers",
-      description: "Create a new customer",
-      body: {
-        first_name: "Required",
-        last_name: "Required",
-        email: "Email address",
-        phone: "Phone number",
-        date_of_birth: "YYYY-MM-DD"
-      },
-      response: "Customer"
-    }, {
-      method: "PATCH",
-      path: "/v1/stores/:storeId/customers/:id",
-      scope: "write:customers",
-      description: "Update a customer",
-      body: {
-        "...": "Any customer fields"
-      },
-      response: "Customer"
-    }]
-  },
-  inventory: {
-    name: "Inventory",
-    description: "Inventory levels, summaries, adjustments, and transfers",
-    base: "/v1/stores/:storeId/inventory",
-    endpoints: [{
-      method: "GET",
-      path: "/v1/stores/:storeId/inventory",
-      scope: "read:inventory",
-      description: "List inventory levels across locations",
-      params: {
-        limit: "Number (1-100, default 25)",
-        starting_after: "Cursor",
-        location_id: "Filter by location UUID",
-        product_id: "Filter by product UUID",
-        low_stock: "Set to 'true' to filter to low_stock or out_of_stock items only"
-      },
-      response: '{ object: "list", data: InventoryLevel[] }'
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/inventory/summary",
-      scope: "read:inventory",
-      description: "Inventory summary grouped by location",
-      response: "{ locations: [{ id, name, total_products, total_units, total_value }] }"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/inventory/adjust",
-      scope: "write:inventory",
-      description: "Adjust inventory quantity for a product at a location",
-      body: {
-        product_id: "Required. Product UUID",
-        location_id: "Required. Location UUID",
-        quantity_change: "Required. Number (+/-) to adjust by",
-        reason: "Reason for adjustment (default: 'api_adjustment')"
-      },
-      response: '{ object: "inventory_adjustment", product_id, location_id, quantity_change, new_quantity, reason }'
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/inventory/transfer",
-      scope: "write:inventory",
-      description: "Transfer inventory between locations",
-      body: {
-        product_id: "Required. Product UUID",
-        from_location_id: "Required. Source location UUID",
-        to_location_id: "Required. Destination location UUID",
-        quantity: "Required. Number of units to transfer"
-      },
-      response: "{ from: InventoryLevel, to: InventoryLevel }"
-    }]
-  },
-  locations: {
-    name: "Locations",
-    description: "Store locations — list and view",
-    base: "/v1/stores/:storeId/locations",
-    endpoints: [{
-      method: "GET",
-      path: "/v1/stores/:storeId/locations",
-      scope: "read:locations",
-      description: "List all store locations",
-      response: '{ object: "list", data: Location[] }'
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/locations/:id",
-      scope: "read:locations",
-      description: "Get a single location",
-      response: "Location { id, name, address, city, state, zip, type, is_active }"
-    }]
-  },
-  analytics: {
-    name: "Analytics",
-    description: "Sales, inventory, traffic, customer, and product analytics",
-    base: "/v1/stores/:storeId/analytics",
-    endpoints: [{
-      method: "GET",
-      path: "/v1/stores/:storeId/analytics/sales",
-      scope: "read:analytics",
-      description: "Sales analytics summary",
-      params: {
-        start_date: "YYYY-MM-DD (default: 30 days ago)",
-        end_date: "YYYY-MM-DD (default: today)",
-        location_id: "Filter by location UUID"
-      },
-      response: '{ object: "analytics.sales", period: { start_date, end_date }, total_orders, completed_orders, total_revenue, total_tax, total_discount, average_order_value, gross_sales, net_sales, total_profit, profit_margin, unique_customers }'
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/analytics/sales/daily",
-      scope: "read:analytics",
-      description: "Daily sales breakdown",
-      params: {
-        start_date: "YYYY-MM-DD (default: 30 days ago)",
-        end_date: "YYYY-MM-DD (default: today)",
-        location_id: "Filter by location UUID"
-      },
-      response: "{ days: [{ date, revenue, orders, average_order_value }] }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/analytics/sales/weekly",
-      scope: "read:analytics",
-      description: "Weekly sales breakdown",
-      params: {
-        start_date: "YYYY-MM-DD (default: 30 days ago)",
-        end_date: "YYYY-MM-DD (default: today)",
-        location_id: "Filter by location UUID"
-      },
-      response: "{ weeks: [{ week_start, revenue, orders }] }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/analytics/inventory",
-      scope: "read:analytics",
-      description: "Inventory analytics — stock levels and velocity",
-      response: "{ total_value, low_stock[], out_of_stock[], velocity[] }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/analytics/traffic",
-      scope: "read:analytics",
-      description: "Storefront traffic analytics",
-      response: "{ sessions, page_views, bounce_rate, avg_session_duration }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/analytics/funnel",
-      scope: "read:analytics",
-      description: "Conversion funnel analytics",
-      response: "{ steps: [{ name, count, conversion_rate }] }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/analytics/customers",
-      scope: "read:analytics",
-      description: "Customer analytics — segments, retention, lifetime value",
-      response: "{ total_customers, new_customers, returning, avg_ltv, segments[] }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/analytics/products",
-      scope: "read:analytics",
-      description: "Per-product performance analytics",
-      params: {
-        limit: "Number of products",
-        category_id: "Filter by category"
-      },
-      response: "{ products: [{ id, name, revenue, units_sold, avg_price }] }"
-    }]
-  },
-  storefront: {
-    name: "Storefront",
-    description: "Storefront sessions, event tracking, and customer OTP authentication",
-    base: "/v1/stores/:storeId/storefront",
-    endpoints: [{
-      method: "GET",
-      path: "/v1/stores/:storeId/storefront/sessions",
-      scope: "read:storefront",
-      description: "List storefront sessions",
-      response: '{ object: "list", data: Session[] }'
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/storefront/sessions/:id",
-      scope: "read:storefront",
-      description: "Get a single session",
-      response: "Session { id, customer_id, events[], created_at }"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/storefront/sessions",
-      scope: "write:storefront",
-      description: "Create a storefront session",
-      body: {
-        customer_id: "Optional customer UUID",
-        metadata: "Optional session metadata"
-      },
-      response: "Session"
-    }, {
-      method: "PATCH",
-      path: "/v1/stores/:storeId/storefront/sessions/:id",
-      scope: "write:storefront",
-      description: "Update a session",
-      body: {
-        metadata: "Updated metadata"
-      },
-      response: "Session"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/storefront/events",
-      scope: "write:storefront",
-      description: "Track a storefront event",
-      body: {
-        session_id: "Session UUID",
-        event_type: "Event name (e.g. page_view, add_to_cart, purchase)",
-        event_data: "Event payload JSON"
-      },
-      response: "{ tracked: true }"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/storefront/auth/send-code",
-      scope: "write:storefront",
-      description: "Send passwordless OTP to a customer",
-      body: {
-        email: "Customer email OR",
-        phone: "Customer phone"
-      },
-      response: "{ sent: true }",
-      notes: "Rate-limited to prevent abuse. Code expires in 10 minutes."
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/storefront/auth/verify-code",
-      scope: "write:storefront",
-      description: "Verify OTP code and authenticate customer",
-      body: {
-        email: "Customer email OR phone",
-        code: "6-digit OTP code"
-      },
-      response: "{ customer_id, session_token, expires_at }"
-    }]
-  },
-  coa: {
-    name: "COA (Certificates of Analysis)",
-    description: "Lab test results — list, verify, view, and embed",
-    base: "/v1/stores/:storeId/coa",
-    endpoints: [{
-      method: "GET",
-      path: "/v1/stores/:storeId/coa",
-      scope: "read:coa",
-      description: "List COAs (scoped to client)",
-      params: {
-        limit: "Number (1-100)",
-        starting_after: "Cursor"
-      },
-      response: '{ object: "list", data: COA[] }'
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/coa/verify",
-      scope: "read:coa",
-      description: "Verify a COA by sample ID",
-      params: {
-        sample_id: "Lab sample identifier"
-      },
-      response: "COA (with verification status)",
-      notes: "Public-facing verification — can be linked from product pages"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/coa/:id",
-      scope: "read:coa",
-      description: "Get a single COA with full lab data",
-      response: "COA { id, product_name, batch_number, sample_id, cannabinoids, terpenes, ... }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/coa/:id/embed",
-      scope: "read:coa",
-      description: "Get embeddable COA data for iframes or widgets",
-      response: "{ html: string, data: COA }",
-      notes: "Use for embedding lab results on product detail pages"
-    }]
-  },
-  portal: {
-    name: "Customer Portal",
-    description: "B2B portal — authentication, profiles, and documents",
-    base: "/v1/stores/:storeId/portal",
-    endpoints: [{
-      method: "POST",
-      path: "/v1/stores/:storeId/portal/auth/send-code",
-      scope: "write:portal",
-      description: "Send portal login OTP",
-      body: {
-        email: "Customer email"
-      },
-      response: "{ sent: true }"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/portal/auth/verify",
-      scope: "write:portal",
-      description: "Verify OTP and get portal session",
-      body: {
-        email: "Customer email",
-        code: "OTP code"
-      },
-      response: "{ customer_id, token, expires_at }"
-    }, {
-      method: "POST",
-      path: "/v1/stores/:storeId/portal/auth/refresh",
-      scope: "write:portal",
-      description: "Refresh portal session token",
-      body: {
-        token: "Current session token"
-      },
-      response: "{ token, expires_at }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/portal/stores",
-      scope: "read:portal",
-      description: "Get stores the customer belongs to",
-      response: "{ stores: Store[] }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/portal/profiles",
-      scope: "read:portal",
-      description: "List customer profiles",
-      response: "{ profiles: Profile[] }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/portal/documents",
-      scope: "read:portal",
-      description: "List customer documents",
-      response: '{ object: "list", data: Document[] }'
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/portal/documents/:id",
-      scope: "read:portal",
-      description: "Get a single document",
-      response: "Document { id, name, type, url, created_at }"
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/portal/api-key",
-      scope: "read:portal",
-      description: "Get customer's API key for portal access",
-      response: "{ api_key, scopes[], expires_at }"
-    }]
-  },
-  webhooks: {
-    name: "Webhooks",
-    description: "Inbound webhook ingestion — receives events from external services (HMAC-authenticated, no API key required)",
-    base: "/v1/webhooks",
-    endpoints: [{
-      method: "POST",
-      path: "/v1/webhooks/:slug",
-      scope: "(none — HMAC signature)",
-      description: "Receive an inbound webhook event",
-      body: {
-        timestamp: "Unix timestamp (optional — replay protection, rejects if > 5 min old)",
-        event: "Event type identifier (or 'type' field)",
-        "...": "All other fields pass through to webhook_events table"
-      },
-      response: '{ object: "webhook_event", received: true, event_type: string }',
-      notes: "Authenticated via HMAC sha256 signature from the webhook endpoint's signing_secret. No API key required."
-    }]
-  },
-  agent: {
-    name: "Agent",
-    description: "AI agent chat — SSE streaming proxy to the internal whale-agent service",
-    base: "/v1/stores/:storeId/agent",
-    endpoints: [{
-      method: "POST",
-      path: "/v1/stores/:storeId/agent/chat",
-      scope: "write:agent",
-      description: "Stream an AI agent response via Server-Sent Events",
-      body: {
-        message: "User message (string — either this or messages required)",
-        messages: "Array of { role: 'user'|'assistant'|'system', content: string }",
-        conversation_id: "Conversation ID for multi-turn context",
-        context: "Additional context object passed to the agent"
-      },
-      response: "SSE stream (text/event-stream) — streamed tokens from the agent",
-      notes: "Proxies to internal whale-agent service. 120s timeout (504 on timeout, 502 on connection failure)."
-    }]
-  },
-  telemetry: {
-    name: "Telemetry",
-    description: "SDK telemetry ingestion — errors, analytics events, Web Vitals, and AI/LLM call tracking",
-    base: "/v1/stores/:storeId/telemetry",
-    endpoints: [{
-      method: "POST",
-      path: "/v1/stores/:storeId/telemetry/ingest",
-      scope: "write:telemetry",
-      description: "Ingest a batch of telemetry data (errors, events, vitals, AI calls)",
-      body: {
-        session: "Required. { session_id, visitor_id, started_at, page_url, referrer, user_agent, screen_width, screen_height, device, language, utm_* }",
-        user: "Optional. { user_id, email?, name?, traits? }",
-        errors: "Array (max 50). Each: { error_type, error_message, fingerprint, occurred_at, severity?, stack_trace?, breadcrumbs? }",
-        events: "Array (max 100). Each: { event_name, properties, timestamp }",
-        vitals: "Array (max 20). Each: { name: CLS|FID|LCP|INP|TTFB|FCP, value, rating, timestamp }",
-        ai_calls: "Array (max 50). Each: { model, provider?, prompt_tokens?, completion_tokens?, cost?, duration_ms?, status?, agent_id? }"
-      },
-      response: '{ object: "telemetry_batch", accepted: { errors, events, vitals, ai_calls }, session_id }',
-      notes: "Used by @neowhale/telemetry SDK. Errors go to ClickHouse, events to Supabase, vitals and AI calls to ClickHouse."
-    }, {
-      method: "POST",
-      path: "/v1/native/telemetry",
-      scope: "(JWT-authenticated)",
-      description: "Ingest telemetry from native (macOS/iOS) apps",
-      body: {
-        "...": "Same batch format as /telemetry/ingest"
-      },
-      response: '{ object: "telemetry_batch", accepted: { ... } }',
-      notes: "Authenticated via JWT token (not API key). Bypasses standard API key middleware."
-    }]
-  },
-  media: {
-    name: "Media",
-    description: "Image and video proxy with on-the-fly transformations (HMAC-signed, no API key required)",
-    base: "/v1/stores/:storeId",
-    endpoints: [{
-      method: "GET",
-      path: "/v1/stores/:storeId/media",
-      scope: "(HMAC signature via 's' query param)",
-      description: "Proxy and transform an image (resize, format conversion, quality)",
-      params: {
-        url: "Required. Base64url-encoded source image URL",
-        w: "Width: 64, 96, 128, 256, 384, 640, 828, 1080, 1280, or 1920",
-        q: "Quality 1-100 (default: 80)",
-        f: "Format: avif, webp, jpeg, png (default: webp)",
-        s: "Required. HMAC signature"
-      },
-      response: "Binary image data with Cache-Control: public, max-age=86400, s-maxage=604800, immutable",
-      notes: "Max 8 concurrent transforms, queues for 5s then returns 503 with Retry-After: 2. Use WhaleClient.signMedia() to generate signatures."
-    }, {
-      method: "GET",
-      path: "/v1/stores/:storeId/video",
-      scope: "(HMAC signature via 's' query param)",
-      description: "Stream a video with HTTP range request support",
-      params: {
-        url: "Required. Base64url-encoded source video URL",
-        s: "Required. HMAC signature"
-      },
-      response: "Streamed video (supports Accept-Ranges: bytes for seeking). Auto-resolves optimized -web.mp4 variants.",
-      notes: "Cache-Control: public, max-age=86400, s-maxage=604800, immutable. X-Video-Source header indicates original vs optimized."
-    }]
-  },
-  infrastructure: {
-    name: "Infrastructure",
-    description: "Health checks, OpenAPI spec, and interactive documentation",
-    base: "",
-    endpoints: [{
-      method: "GET",
-      path: "/health",
-      scope: "(no auth)",
-      description: "Health check — simple or detailed with dependency status",
-      params: {
-        detailed: "Set to 'true' to check Supabase and ClickHouse dependencies"
-      },
-      response: '{ status: "ok"|"degraded"|"down", version: "2026-02-20", uptime_s?, dependencies?: { supabase, clickhouse } }',
-      notes: "Simple response: 200 always. Detailed: 503 if both dependencies are down. Cached for 10s."
-    }, {
-      method: "GET",
-      path: "/openapi.json",
-      scope: "(no auth)",
-      description: "OpenAPI 3.0 specification",
-      response: "OpenAPI JSON spec"
-    }, {
-      method: "GET",
-      path: "/docs",
-      scope: "(no auth)",
-      description: "Interactive API documentation page",
-      response: "HTML page"
-    }]
+let _cache = null;
+async function fetchOpenApiSpec() {
+  if (_cache && Date.now() - _cache.fetchedAt < CACHE_TTL_MS) {
+    return _cache.spec;
   }
-};
-
-// ---------------------------------------------------------------------------
-// Auth reference
-// ---------------------------------------------------------------------------
-
-const AUTH_GUIDE = {
-  base_url: GATEWAY_BASE_URL,
-  api_version: "2026-02-20",
-  api_version_header: "X-API-Version",
-  authentication: {
-    method: "API Key via header",
-    header: "x-api-key",
-    key_format: "wk_live_<32chars> (production) or wk_test_<32chars> (sandbox)",
-    how_to_get: "Use the api_keys tool (action: generate) or the WhaleTools dashboard under Settings → API Keys"
-  },
-  scopes: {
-    wildcard: "* (full access), read:* (all reads), write:* (all writes)",
-    per_resource: ["read:products", "write:products", "read:orders", "write:orders", "read:customers", "write:customers", "read:inventory", "write:inventory", "read:locations", "read:analytics", "read:cart", "write:cart", "read:checkout", "write:checkout", "read:storefront", "write:storefront", "read:portal", "write:portal", "read:coa"],
-    internal: ["write:agent", "write:telemetry"],
-    internal_note: "Agent chat and telemetry scopes are used by WhaleTools SDKs and internal services. Media/video endpoints use HMAC signatures instead of API keys."
-  },
-  rate_limits: {
-    default_per_minute: 60,
-    headers: "X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset",
-    exceeded_status: 429,
-    retry_header: "Retry-After (seconds)"
-  },
-  pagination: {
-    style: "Cursor-based",
-    params: "limit (1-100, default 25), starting_after (ID), ending_before (ID)",
-    response: '{ object: "list", data: [...], has_more: true|false, url: "..." }'
-  },
-  error_format: {
-    shape: '{ error: { type, message, code, param?, request_id? } }',
-    types: {
-      authentication_error: "401 — invalid_api_key (also returned for missing key)",
-      permission_error: "403 — insufficient_scope, store_mismatch",
-      not_found_error: "404 — resource_not_found",
-      invalid_request_error: "400/405/409 — validation_error, method_not_allowed, conflict",
-      rate_limit_error: "429 — rate_limit_exceeded, auth_rate_limited (too many auth attempts)",
-      api_error: "500 — internal_error"
-    }
-  },
-  security_headers: {
-    cors: "Configurable per-store. Default: allow all origins",
-    idempotency: "Idempotency-Key header supported on all POST/PATCH requests",
-    versioning: "X-API-Version header (optional — latest version used if omitted)"
-  },
-  url_pattern: "All endpoints: /v1/stores/:storeId/<resource>",
-  note: "Replace :storeId with your store UUID. Get it from the WhaleTools dashboard or the store tool."
-};
-
-// ---------------------------------------------------------------------------
-// Code examples by section
-// ---------------------------------------------------------------------------
-
-function getExamples(section) {
-  const BASE = GATEWAY_BASE_URL;
-  const storeVar = "${STORE_ID}";
-  const keyVar = "${API_KEY}";
-  const templates = {
-    products: {
-      raw_fetch: `// List products
-const res = await fetch("${BASE}/v1/stores/${storeVar}/products?limit=25&status=published", {
-  headers: { "x-api-key": "${keyVar}" }
-});
-const { data: products, has_more } = await res.json();
-
-// Get single product
-const product = await fetch("${BASE}/v1/stores/${storeVar}/products/\${productId}", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());`,
-      nextjs_ssr: `// app/products/page.tsx (Next.js App Router — Server Component)
-const API_KEY = process.env.WHALE_API_KEY!;
-const STORE_ID = process.env.WHALE_STORE_ID!;
-const BASE = "${BASE}";
-
-async function getProducts(page?: string) {
-  const params = new URLSearchParams({ limit: "25", status: "published" });
-  if (page) params.set("starting_after", page);
-
-  const res = await fetch(\`\${BASE}/v1/stores/\${STORE_ID}/products?\${params}\`, {
-    headers: { "x-api-key": API_KEY },
-    next: { revalidate: 60 }, // ISR: revalidate every 60s
-  });
-
-  if (!res.ok) throw new Error("Failed to fetch products");
-  return res.json();
-}
-
-export default async function ProductsPage({ searchParams }: { searchParams: { after?: string } }) {
-  const { data: products, has_more } = await getProducts(searchParams.after);
-
-  return (
-    <div className="grid grid-cols-3 gap-4">
-      {products.map((p: any) => (
-        <div key={p.id} className="border rounded p-4">
-          {p.featured_image && <img src={p.featured_image} alt={p.name} />}
-          <h2>{p.name}</h2>
-          <p>{p.pricing_data?.tiers?.[0]?.price ? \`$\${p.pricing_data.tiers[0].price}\` : "Contact for pricing"}</p>
-        </div>
-      ))}
-      {has_more && <a href={\`?after=\${products.at(-1)?.id}\`}>Next page →</a>}
-    </div>
-  );
-}`,
-      react_client: `// hooks/useProducts.ts (React client-side)
-import { useState, useEffect } from "react";
-
-const BASE = "${BASE}";
-
-export function useProducts(storeId: string, apiKey: string) {
-  const [products, setProducts] = useState([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    fetch(\`\${BASE}/v1/stores/\${storeId}/products?status=published&limit=50\`, {
-      headers: { "x-api-key": apiKey },
-    })
-      .then(r => r.json())
-      .then(({ data }) => setProducts(data))
-      .finally(() => setLoading(false));
-  }, [storeId, apiKey]);
-
-  return { products, loading };
-}`
+  const res = await fetch(OPENAPI_URL, {
+    headers: {
+      Accept: "application/json"
     },
-    cart: {
-      raw_fetch: `// Create cart
-const cart = await fetch("${BASE}/v1/stores/${storeVar}/cart", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({ customer_id: customerId })
-}).then(r => r.json());
-
-// Add item
-await fetch("${BASE}/v1/stores/${storeVar}/cart/\${cart.id}/items", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({ product_id: "...", quantity: 2 })
-}).then(r => r.json());
-
-// View cart
-const fullCart = await fetch("${BASE}/v1/stores/${storeVar}/cart/\${cart.id}", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());`,
-      nextjs_ssr: `// app/api/cart/route.ts (Next.js Route Handler — server-side proxy)
-import { NextRequest, NextResponse } from "next/server";
-
-const API_KEY = process.env.WHALE_API_KEY!;
-const STORE_ID = process.env.WHALE_STORE_ID!;
-const BASE = "${BASE}";
-
-export async function POST(req: NextRequest) {
-  const body = await req.json();
-  const res = await fetch(\`\${BASE}/v1/stores/\${STORE_ID}/cart\`, {
-    method: "POST",
-    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
-    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(8000)
   });
-  return NextResponse.json(await res.json());
-}`,
-      react_client: `// hooks/useCart.ts
-import { useState, useCallback } from "react";
-
-export function useCart(storeId: string, apiKey: string) {
-  const [cart, setCart] = useState<any>(null);
-  const BASE = "${BASE}";
-  const headers = { "x-api-key": apiKey, "Content-Type": "application/json" };
-
-  const createCart = useCallback(async () => {
-    const res = await fetch(\`\${BASE}/v1/stores/\${storeId}/cart\`, {
-      method: "POST", headers,
-    });
-    const data = await res.json();
-    setCart(data);
-    return data;
-  }, [storeId]);
-
-  const addItem = useCallback(async (productId: string, quantity: number) => {
-    if (!cart) return;
-    const res = await fetch(\`\${BASE}/v1/stores/\${storeId}/cart/\${cart.id}/items\`, {
-      method: "POST", headers,
-      body: JSON.stringify({ product_id: productId, quantity }),
-    });
-    const data = await res.json();
-    setCart(data);
-    return data;
-  }, [storeId, cart]);
-
-  const removeItem = useCallback(async (itemId: string) => {
-    if (!cart) return;
-    const res = await fetch(\`\${BASE}/v1/stores/\${storeId}/cart/\${cart.id}/items/\${itemId}\`, {
-      method: "DELETE", headers,
-    });
-    const data = await res.json();
-    setCart(data);
-    return data;
-  }, [storeId, cart]);
-
-  return { cart, createCart, addItem, removeItem };
-}`
-    },
-    checkout: {
-      raw_fetch: `// E-commerce checkout (convert cart to order)
-const order = await fetch("${BASE}/v1/stores/${storeVar}/checkout", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({
-    cart_id: cartId,
-    payment_method: "card",
-    shipping_address: { street: "123 Main St", city: "Charlotte", state: "NC", zip: "28202" }
-  })
-}).then(r => r.json());
-
-// POS payment intent flow
-const intent = await fetch("${BASE}/v1/stores/${storeVar}/checkout/intents", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({ cart_id: cartId, amount: 49.99 })
-}).then(r => r.json());
-
-// Capture after authorization
-await fetch("${BASE}/v1/stores/${storeVar}/checkout/intents/\${intent.id}/capture", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}" }
-});`,
-      nextjs_ssr: `// app/api/checkout/route.ts (Server-side checkout — keep API key secret)
-import { NextRequest, NextResponse } from "next/server";
-
-const API_KEY = process.env.WHALE_API_KEY!;
-const STORE_ID = process.env.WHALE_STORE_ID!;
-const BASE = "${BASE}";
-
-export async function POST(req: NextRequest) {
-  const { cart_id, shipping_address } = await req.json();
-
-  const res = await fetch(\`\${BASE}/v1/stores/\${STORE_ID}/checkout\`, {
-    method: "POST",
-    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
-    body: JSON.stringify({ cart_id, shipping_address }),
-  });
-
   if (!res.ok) {
-    const err = await res.json();
-    return NextResponse.json(err, { status: res.status });
+    throw new Error(`Gateway returned ${res.status} fetching OpenAPI spec`);
   }
-
-  return NextResponse.json(await res.json());
-}`,
-      react_client: `// components/CheckoutButton.tsx
-"use client";
-import { useState } from "react";
-
-export function CheckoutButton({ cartId }: { cartId: string }) {
-  const [loading, setLoading] = useState(false);
-
-  const handleCheckout = async () => {
-    setLoading(true);
-    try {
-      // Call YOUR server-side route (never expose API key to client)
-      const res = await fetch("/api/checkout", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ cart_id: cartId }),
-      });
-      const order = await res.json();
-      if (order.id) window.location.href = \`/orders/\${order.id}/confirmation\`;
-    } finally {
-      setLoading(false);
-    }
+  const spec = await res.json();
+  _cache = {
+    spec,
+    fetchedAt: Date.now()
   };
-
-  return <button onClick={handleCheckout} disabled={loading}>{loading ? "Processing..." : "Checkout"}</button>;
-}`
-    },
-    orders: {
-      raw_fetch: `// List orders
-const { data: orders } = await fetch("${BASE}/v1/stores/${storeVar}/orders?limit=25", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());
-
-// Get order details
-const order = await fetch("${BASE}/v1/stores/${storeVar}/orders/\${orderId}", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());
-
-// Update order status
-await fetch("${BASE}/v1/stores/${storeVar}/orders/\${orderId}", {
-  method: "PATCH",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({ status: "shipped" })
-});`,
-      nextjs_ssr: `// app/orders/page.tsx (Server Component)
-async function getOrders() {
-  const res = await fetch(
-    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/orders?limit=50\`,
-    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 30 } }
-  );
-  return res.json();
+  return spec;
 }
 
-export default async function OrdersPage() {
-  const { data: orders } = await getOrders();
-  return (
-    <table>
-      <thead><tr><th>Order</th><th>Status</th><th>Total</th><th>Date</th></tr></thead>
-      <tbody>
-        {orders.map((o: any) => (
-          <tr key={o.id}>
-            <td><a href={\`/orders/\${o.id}\`}>{o.order_number}</a></td>
-            <td>{o.status}</td>
-            <td>\${o.total}</td>
-            <td>{new Date(o.created_at).toLocaleDateString()}</td>
-          </tr>
-        ))}
-      </tbody>
-    </table>
-  );
-}`,
-      react_client: `// hooks/useOrders.ts
-import useSWR from "swr";
-
-const fetcher = (url: string) => fetch(url).then(r => r.json());
-
-export function useOrders() {
-  // Fetch via your own API route (keeps API key server-side)
-  const { data, error, isLoading } = useSWR("/api/orders", fetcher);
-  return { orders: data?.data ?? [], error, isLoading };
-}`
-    },
-    customers: {
-      raw_fetch: `// Search customers
-const { data: customers } = await fetch("${BASE}/v1/stores/${storeVar}/customers?search=john", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());
-
-// Create customer
-const customer = await fetch("${BASE}/v1/stores/${storeVar}/customers", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({ first_name: "John", last_name: "Doe", email: "john@example.com" })
-}).then(r => r.json());`,
-      nextjs_ssr: `// app/api/customers/route.ts
-import { NextRequest, NextResponse } from "next/server";
-
-const headers = { "x-api-key": process.env.WHALE_API_KEY! };
-const base = \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}\`;
-
-export async function GET(req: NextRequest) {
-  const search = req.nextUrl.searchParams.get("q") || "";
-  const res = await fetch(\`\${base}/customers?search=\${encodeURIComponent(search)}\`, { headers });
-  return NextResponse.json(await res.json());
-}`,
-      react_client: `// hooks/useCustomers.ts
-import useSWR from "swr";
-
-export function useCustomers(search: string) {
-  const { data, isLoading } = useSWR(
-    search ? \`/api/customers?q=\${encodeURIComponent(search)}\` : null,
-    (url) => fetch(url).then(r => r.json())
-  );
-  return { customers: data?.data ?? [], isLoading };
-}`
-    },
-    inventory: {
-      raw_fetch: `// Get inventory summary
-const summary = await fetch("${BASE}/v1/stores/${storeVar}/inventory/summary", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());
-
-// Adjust stock
-await fetch("${BASE}/v1/stores/${storeVar}/inventory/adjust", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({ product_id: "...", location_id: "...", adjustment: -5, reason: "Sold offline" })
-});`,
-      nextjs_ssr: `// app/inventory/page.tsx
-async function getInventory() {
-  const res = await fetch(
-    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/inventory/summary\`,
-    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 60 } }
-  );
-  return res.json();
+/** Get cached spec if available (for sync callers like /openapi.json endpoint) */
+function getCachedSpecSync() {
+  if (_cache && Date.now() - _cache.fetchedAt < CACHE_TTL_MS) {
+    return _cache.spec;
+  }
+  return null;
 }
 
-export default async function InventoryPage() {
-  const summary = await getInventory();
-  return (
-    <div>
-      {summary.locations.map((loc: any) => (
-        <div key={loc.id}>
-          <h3>{loc.name}</h3>
-          <p>{loc.total_products} products, {loc.total_units} units</p>
-        </div>
-      ))}
-    </div>
-  );
-}`,
-      react_client: `// hooks/useInventory.ts
-import useSWR from "swr";
-
-export function useInventorySummary() {
-  const { data, isLoading } = useSWR("/api/inventory/summary", (url) => fetch(url).then(r => r.json()));
-  return { summary: data, isLoading };
-}`
-    },
-    analytics: {
-      raw_fetch: `// Sales analytics
-const sales = await fetch("${BASE}/v1/stores/${storeVar}/analytics/sales?period=last_30", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());
-
-// Daily breakdown
-const daily = await fetch("${BASE}/v1/stores/${storeVar}/analytics/sales/daily?period=last_7", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());
-
-// Product performance
-const topProducts = await fetch("${BASE}/v1/stores/${storeVar}/analytics/products?limit=10", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());`,
-      nextjs_ssr: `// app/dashboard/page.tsx
-async function getDashboard() {
-  const base = \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/analytics\`;
-  const headers = { "x-api-key": process.env.WHALE_API_KEY! };
-  const opts = { headers, next: { revalidate: 300 } as any };
-
-  const [sales, daily, products] = await Promise.all([
-    fetch(\`\${base}/sales?period=last_30\`, opts).then(r => r.json()),
-    fetch(\`\${base}/sales/daily?period=last_7\`, opts).then(r => r.json()),
-    fetch(\`\${base}/products?limit=5\`, opts).then(r => r.json()),
-  ]);
+// ---------------------------------------------------------------------------
+// Helpers — derive section/endpoint data from the live OpenAPI spec
+// ---------------------------------------------------------------------------
 
-  return { sales, daily, products };
+function deriveSections(spec) {
+  const tags = spec.tags || [];
+  const tagEndpointCounts = {};
+  for (const [, methods] of Object.entries(spec.paths)) {
+    for (const [, op] of Object.entries(methods)) {
+      const operation = op;
+      if (operation.tags) {
+        for (const tag of operation.tags) {
+          tagEndpointCounts[tag] = (tagEndpointCounts[tag] || 0) + 1;
+        }
+      }
+    }
+  }
+  return tags.map(t => ({
+    key: t.name.toLowerCase().replace(/\s+/g, "_"),
+    name: t.name,
+    description: t.description || "",
+    endpoint_count: tagEndpointCounts[t.name] || 0
+  }));
 }
-
-export default async function DashboardPage() {
-  const { sales, daily, products } = await getDashboard();
-  return (
-    <div>
-      <h1>Dashboard</h1>
-      <div className="grid grid-cols-3 gap-4">
-        <div>Revenue: \${sales.total_revenue}</div>
-        <div>Orders: {sales.total_orders}</div>
-        <div>AOV: \${sales.average_order_value}</div>
-      </div>
-    </div>
-  );
-}`,
-      react_client: `// hooks/useAnalytics.ts
-import useSWR from "swr";
-
-export function useSalesAnalytics(period = "last_30") {
-  const { data, isLoading } = useSWR(
-    \`/api/analytics/sales?period=\${period}\`,
-    (url) => fetch(url).then(r => r.json())
-  );
-  return { sales: data, isLoading };
-}`
-    },
-    locations: {
-      raw_fetch: `// List all locations
-const { data: locations } = await fetch("${BASE}/v1/stores/${storeVar}/locations", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());`,
-      nextjs_ssr: `// lib/api.ts — shared helper
-export async function getLocations() {
-  const res = await fetch(
-    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/locations\`,
-    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 3600 } }
-  );
-  return res.json().then(r => r.data);
-}`,
-      react_client: `// hooks/useLocations.ts
-import useSWR from "swr";
-
-export function useLocations() {
-  const { data } = useSWR("/api/locations", (url) => fetch(url).then(r => r.json()));
-  return data?.data ?? [];
-}`
-    },
-    storefront: {
-      raw_fetch: `// Track page view event
-await fetch("${BASE}/v1/stores/${storeVar}/storefront/events", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({
-    session_id: sessionId,
-    event_type: "page_view",
-    event_data: { url: "/products/blue-dream", product_id: "..." }
-  })
-});
-
-// Send OTP for customer login
-await fetch("${BASE}/v1/stores/${storeVar}/storefront/auth/send-code", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({ email: "customer@example.com" })
-});`,
-      nextjs_ssr: `// app/api/auth/send-code/route.ts
-import { NextRequest, NextResponse } from "next/server";
-
-export async function POST(req: NextRequest) {
-  const { email } = await req.json();
-  const res = await fetch(
-    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/storefront/auth/send-code\`,
-    {
-      method: "POST",
-      headers: { "x-api-key": process.env.WHALE_API_KEY!, "Content-Type": "application/json" },
-      body: JSON.stringify({ email }),
+function deriveEndpointsForSection(spec, sectionName) {
+  const endpoints = [];
+  for (const [path, methods] of Object.entries(spec.paths)) {
+    for (const [method, op] of Object.entries(methods)) {
+      const operation = op;
+      if (operation.tags?.some(t => t.toLowerCase().replace(/\s+/g, "_") === sectionName || t === sectionName)) {
+        endpoints.push({
+          method: method.toUpperCase(),
+          path,
+          summary: operation.summary || "",
+          description: operation.description,
+          parameters: operation.parameters,
+          requestBody: operation.requestBody,
+          responses: operation.responses
+        });
+      }
     }
-  );
-  return NextResponse.json(await res.json(), { status: res.status });
-}`,
-      react_client: `// hooks/useAuth.ts
-import { useState } from "react";
-
-export function useStorefrontAuth() {
-  const [loading, setLoading] = useState(false);
-
-  const sendCode = async (email: string) => {
-    setLoading(true);
-    await fetch("/api/auth/send-code", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ email }),
-    });
-    setLoading(false);
-  };
-
-  const verifyCode = async (email: string, code: string) => {
-    const res = await fetch("/api/auth/verify-code", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ email, code }),
-    });
-    return res.json(); // { customer_id, session_token }
-  };
-
-  return { sendCode, verifyCode, loading };
-}`
-    },
-    coa: {
-      raw_fetch: `// List COAs
-const { data: coas } = await fetch("${BASE}/v1/stores/${storeVar}/coa?limit=50", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());
-
-// Verify by sample ID
-const verified = await fetch("${BASE}/v1/stores/${storeVar}/coa/verify?sample_id=LAB-2026-001", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());
-
-// Get embeddable COA data
-const embed = await fetch("${BASE}/v1/stores/${storeVar}/coa/\${coaId}/embed", {
-  headers: { "x-api-key": "${keyVar}" }
-}).then(r => r.json());`,
-      nextjs_ssr: `// app/products/[id]/coa/page.tsx
-async function getCOAEmbed(coaId: string) {
-  const res = await fetch(
-    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/coa/\${coaId}/embed\`,
-    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 3600 } }
-  );
-  return res.json();
+  }
+  return endpoints;
+}
+function findSectionTag(spec, sectionKey) {
+  return spec.tags?.find(t => t.name.toLowerCase().replace(/\s+/g, "_") === sectionKey || t.name === sectionKey);
 }
 
-export default async function COAPage({ params }: { params: { id: string } }) {
-  const { html, data } = await getCOAEmbed(params.id);
-  return (
-    <div>
-      <h1>Certificate of Analysis — {data.product_name}</h1>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-    </div>
-  );
-}`,
-      react_client: `// components/COAViewer.tsx
-"use client";
-import { useEffect, useState } from "react";
-
-export function COAViewer({ coaId }: { coaId: string }) {
-  const [html, setHtml] = useState("");
-
-  useEffect(() => {
-    fetch(\`/api/coa/\${coaId}/embed\`).then(r => r.json()).then(d => setHtml(d.html));
-  }, [coaId]);
+// ---------------------------------------------------------------------------
+// Auth guide (static — these are usage instructions, not endpoint data)
+// ---------------------------------------------------------------------------
 
-  return <div dangerouslySetInnerHTML={{ __html: html }} />;
-}`
+const AUTH_GUIDE = {
+  authentication: {
+    method: "API Key via x-api-key header",
+    key_format: {
+      live: "wk_live_<32 chars> — production data",
+      test: "wk_test_<32 chars> — sandbox data"
     },
-    portal: {
-      raw_fetch: `// B2B portal login
-await fetch("${BASE}/v1/stores/${storeVar}/portal/auth/send-code", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({ email: "buyer@dispensary.com" })
-});
-
-// Verify and get session
-const session = await fetch("${BASE}/v1/stores/${storeVar}/portal/auth/verify", {
-  method: "POST",
-  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
-  body: JSON.stringify({ email: "buyer@dispensary.com", code: "123456" })
-}).then(r => r.json());
-
-// List documents with portal token
-const { data: docs } = await fetch("${BASE}/v1/stores/${storeVar}/portal/documents", {
-  headers: { "x-api-key": "${keyVar}", "Authorization": "Bearer " + session.token }
-}).then(r => r.json());`,
-      nextjs_ssr: `// app/portal/layout.tsx — server-side session check
-import { cookies } from "next/headers";
-import { redirect } from "next/navigation";
-
-export default async function PortalLayout({ children }: { children: React.ReactNode }) {
-  const token = cookies().get("portal_token")?.value;
-  if (!token) redirect("/portal/login");
-  return <div className="portal-layout">{children}</div>;
-}`,
-      react_client: `// hooks/usePortal.ts
-import { useState } from "react";
-
-export function usePortal() {
-  const [token, setToken] = useState<string | null>(null);
-
-  const login = async (email: string, code: string) => {
-    const res = await fetch("/api/portal/verify", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ email, code }),
-    });
-    const data = await res.json();
-    setToken(data.token);
-    return data;
-  };
-
-  const getDocuments = async () => {
-    const res = await fetch("/api/portal/documents", {
-      headers: { Authorization: \`Bearer \${token}\` },
-    });
-    return res.json();
-  };
-
-  return { token, login, getDocuments };
-}`
+    example: `fetch("${GATEWAY_BASE_URL}/v1/stores/{store_id}/products", {\n  headers: { "x-api-key": "wk_live_..." }\n})`
+  },
+  scopes: {
+    description: "Each API key has scopes controlling access",
+    wildcard: "* — full access (all read + write)",
+    categories: ["read:products, write:products", "read:orders, write:orders", "read:customers, write:customers", "read:inventory, write:inventory", "read:analytics", "read:storefront, write:storefront", "read:agents, write:agents", "read:documents, write:documents", "read:telemetry, write:telemetry"]
+  },
+  rate_limiting: {
+    headers: ["X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset", "Retry-After (on 429)"],
+    plans: {
+      free: "60/min",
+      starter: "300/min",
+      growth: "600/min",
+      enterprise: "3000/min"
     }
-  };
-  return templates[section] ?? null;
-}
+  },
+  pagination: {
+    type: "Cursor-based",
+    params: ["limit (1-500, default 25)", "starting_after (resource ID)", "ending_before (resource ID)"]
+  },
+  errors: {
+    format: '{ "error": { "type": "...", "message": "...", "code": "...", "request_id": "req_..." } }',
+    types: ["authentication_error (401)", "permission_error (403)", "not_found_error (404)", "invalid_request_error (400/422)", "rate_limit_error (429)", "conflict_error (409)", "api_error (500)"]
+  }
+};
 
 // ---------------------------------------------------------------------------
-// Quick start guide
+// Quick start guide (static usage instructions)
 // ---------------------------------------------------------------------------
 
 const QUICK_START = {
-  title: "WhaleTools API — Quick Start Guide",
+  title: "WhaleTools API Quick Start",
   steps: [{
     step: 1,
     title: "Get your API key",
-    description: "Generate an API key from the WhaleTools dashboard (Settings → API Keys) or use the api_keys MCP tool.",
-    code: `// Via dashboard: Settings → API Keys → Generate
-// Or programmatically:
-// api_keys tool: { action: "generate", name: "My Website", scopes: ["read:products", "read:cart", "write:cart", "write:checkout"] }`
+    description: "Generate a key via the dashboard at whaletools.dev/dashboard/api-keys or use the api_keys MCP tool."
   }, {
     step: 2,
-    title: "Set up environment variables",
-    description: "Store your API key and store ID securely. Never expose the API key in client-side code.",
-    code: `# .env.local (Next.js) or .env
-WHALE_API_KEY=wk_live_abc123...
-WHALE_STORE_ID=your-store-uuid`
+    title: "Make your first request",
+    code: `curl -H "x-api-key: wk_live_..." ${GATEWAY_BASE_URL}/v1/stores/{store_id}/products`
   }, {
     step: 3,
-    title: "Fetch products",
-    description: "Make your first API call to list published products.",
-    code: `const res = await fetch(
-  \`https://whale-gateway.fly.dev/v1/stores/\${process.env.WHALE_STORE_ID}/products?status=published&limit=25\`,
-  { headers: { "x-api-key": process.env.WHALE_API_KEY } }
-);
-const { data: products, has_more } = await res.json();
-console.log(\`Loaded \${products.length} products\`);`
+    title: "Use the TypeScript SDK",
+    code: `import { WhaleClient } from "@neowhale/api-client";\nconst whale = new WhaleClient({ apiKey: "wk_live_..." });\nconst products = await whale.products.list();`
   }, {
     step: 4,
-    title: "Create a cart",
-    description: "Start a shopping session by creating a cart.",
-    code: `const cart = await fetch(
-  \`https://whale-gateway.fly.dev/v1/stores/\${STORE_ID}/cart\`,
-  {
-    method: "POST",
-    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
-    body: JSON.stringify({})
-  }
-).then(r => r.json());
-console.log("Cart ID:", cart.id);`
-  }, {
-    step: 5,
-    title: "Add items to cart",
-    description: "Add products to the cart by product ID.",
-    code: `await fetch(
-  \`https://whale-gateway.fly.dev/v1/stores/\${STORE_ID}/cart/\${cart.id}/items\`,
-  {
-    method: "POST",
-    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
-    body: JSON.stringify({ product_id: products[0].id, quantity: 1 })
-  }
-);`
-  }, {
-    step: 6,
-    title: "Checkout",
-    description: "Convert the cart into an order.",
-    code: `const order = await fetch(
-  \`https://whale-gateway.fly.dev/v1/stores/\${STORE_ID}/checkout\`,
-  {
-    method: "POST",
-    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
-    body: JSON.stringify({
-      cart_id: cart.id,
-      shipping_address: {
-        street: "123 Main St",
-        city: "Charlotte",
-        state: "NC",
-        zip: "28202"
-      }
-    })
-  }
-).then(r => r.json());
-console.log("Order created:", order.id, "Status:", order.status);`
+    title: "Use the Python SDK",
+    code: `from whaletools import WhaleClient\nwhale = WhaleClient(api_key="wk_live_...")\nproducts = whale.products.list()`
   }],
-  tips: ["Keep your API key server-side. Use Next.js Route Handlers or API routes as a proxy for client-side calls.", "Use cursor pagination (starting_after) instead of offset for consistent results.", "Set next: { revalidate: 60 } in Next.js fetch for automatic ISR (Incremental Static Regeneration).", "Idempotency-Key header prevents duplicate orders — always set it on checkout requests.", "All list endpoints return { object: 'list', data: [...], has_more: boolean }."]
+  api_reference: `${GATEWAY_BASE_URL}/docs`,
+  openapi_spec: `${GATEWAY_BASE_URL}/openapi.json`
 };
 
 // ---------------------------------------------------------------------------
@@ -1523,20 +159,25 @@ export async function handleApiDocs(_sb, args, _storeId) {
   switch (action) {
     case "sections":
       {
-        const sections = Object.entries(SECTIONS).map(([key, s]) => ({
-          key,
-          name: s.name,
-          description: s.description,
-          endpoint_count: s.endpoints.length
-        }));
-        return {
-          success: true,
-          data: {
-            total_endpoints: sections.reduce((sum, s) => sum + s.endpoint_count, 0),
-            sections,
-            usage: 'Use api_docs with action "endpoints" and section "<key>" to see full endpoint details.'
-          }
-        };
+        try {
+          const spec = await fetchOpenApiSpec();
+          const sections = deriveSections(spec);
+          return {
+            success: true,
+            data: {
+              api_version: spec.info.version,
+              total_endpoints: sections.reduce((sum, s) => sum + s.endpoint_count, 0),
+              total_sections: sections.length,
+              sections,
+              usage: 'Use api_docs with action "endpoints" and section "<key>" to see full endpoint details.'
+            }
+          };
+        } catch (err) {
+          return {
+            success: false,
+            error: `Failed to fetch API spec: ${err.message}`
+          };
+        }
       }
     case "endpoints":
       {
@@ -1547,53 +188,82 @@ export async function handleApiDocs(_sb, args, _storeId) {
             error: 'Missing required param "section". Use action "sections" to see available sections.'
           };
         }
-        const s = SECTIONS[section];
-        if (!s) {
+        try {
+          const spec = await fetchOpenApiSpec();
+          const tag = findSectionTag(spec, section);
+          if (!tag) {
+            const available = (spec.tags || []).map(t => t.name.toLowerCase().replace(/\s+/g, "_"));
+            return {
+              success: false,
+              error: `Unknown section "${section}". Available: ${available.join(", ")}`
+            };
+          }
+          const endpoints = deriveEndpointsForSection(spec, section);
+          return {
+            success: true,
+            data: {
+              section: tag.name,
+              description: tag.description || "",
+              endpoint_count: endpoints.length,
+              endpoints
+            }
+          };
+        } catch (err) {
           return {
             success: false,
-            error: `Unknown section "${section}". Available: ${Object.keys(SECTIONS).join(", ")}`
+            error: `Failed to fetch API spec: ${err.message}`
           };
         }
-        return {
-          success: true,
-          data: {
-            section: s.name,
-            description: s.description,
-            base: s.base,
-            endpoints: s.endpoints
-          }
-        };
-      }
-    case "auth":
-      {
-        return {
-          success: true,
-          data: AUTH_GUIDE
-        };
       }
-    case "examples":
+    case "search":
       {
-        const section = args.section;
-        if (!section) {
+        const query = (args.query || "").toLowerCase();
+        if (!query) {
           return {
             success: false,
-            error: 'Missing required param "section". Use action "sections" to see available sections.'
+            error: 'Missing required param "query". Provide a search term (e.g., "products", "checkout", "webhook").'
           };
         }
-        const examples = getExamples(section);
-        if (!examples) {
+        try {
+          const spec = await fetchOpenApiSpec();
+          const results = [];
+          for (const [path, methods] of Object.entries(spec.paths)) {
+            for (const [method, op] of Object.entries(methods)) {
+              const operation = op;
+              const text = `${path} ${operation.summary || ""} ${operation.description || ""} ${(operation.tags || []).join(" ")}`.toLowerCase();
+              if (text.includes(query)) {
+                results.push({
+                  method: method.toUpperCase(),
+                  path,
+                  summary: operation.summary || "",
+                  tags: operation.tags || []
+                });
+              }
+            }
+          }
+          return {
+            success: true,
+            data: {
+              query,
+              result_count: results.length,
+              results: results.slice(0, 50),
+              ...(results.length > 50 ? {
+                note: `Showing first 50 of ${results.length} results. Narrow your search.`
+              } : {})
+            }
+          };
+        } catch (err) {
           return {
             success: false,
-            error: `No examples for section "${section}". Available: ${Object.keys(SECTIONS).join(", ")}`
+            error: `Failed to fetch API spec: ${err.message}`
           };
         }
+      }
+    case "auth":
+      {
         return {
           success: true,
-          data: {
-            section,
-            examples,
-            tip: "Always keep API keys server-side. Use Next.js Route Handlers or API routes as a proxy for client-side calls."
-          }
+          data: AUTH_GUIDE
         };
       }
     case "quick_start":
@@ -1606,185 +276,38 @@ export async function handleApiDocs(_sb, args, _storeId) {
     default:
       return {
         success: false,
-        error: `Unknown api_docs action: "${action}". Available: sections, endpoints, auth, examples, quick_start`
+        error: `Unknown api_docs action: "${action}". Available: sections, endpoints, search, auth, quick_start`
       };
   }
 }
 
 // ---------------------------------------------------------------------------
-// OpenAPI 3.0 spec generation — serves /openapi.json for Scalar docs viewer
+// OpenAPI spec proxy — serves /openapi.json on the agent server
 // ---------------------------------------------------------------------------
 
-let _cachedSpec = null;
-
-/** Convert :param to {param} for OpenAPI path syntax */
-function toOpenApiPath(path) {
-  return path.replace(/:([a-zA-Z_]+)/g, "{$1}");
+/** Generate (fetch) the OpenAPI spec — async version for the handler */
+export async function generateOpenApiSpec() {
+  return fetchOpenApiSpec();
 }
 
-/** Build OpenAPI parameter objects from the endpoint definition */
-function buildParameters(endpoint, path) {
-  const params = [];
-
-  // Extract path parameters from the path itself
-  const pathParams = path.match(/:([a-zA-Z_]+)/g) || [];
-  for (const p of pathParams) {
-    const name = p.slice(1);
-    params.push({
-      name,
-      in: "path",
-      required: true,
-      schema: {
-        type: "string"
-      },
-      description: name === "storeId" ? "Store UUID" : name === "id" ? "Resource UUID" : `${name} identifier`
-    });
-  }
-
-  // Add query parameters for GET endpoints
-  if (endpoint.method === "GET" && endpoint.params) {
-    for (const [name, desc] of Object.entries(endpoint.params)) {
-      params.push({
-        name,
-        in: "query",
-        required: desc.toLowerCase().startsWith("required"),
-        schema: {
-          type: "string"
-        },
-        description: desc
-      });
-    }
-  }
-  return params;
-}
+/** Sync fallback: return cached spec or a redirect hint */
+export function generateOpenApiSpecSync() {
+  const cached = getCachedSpecSync();
+  if (cached) return cached;
 
-/** Build request body schema from endpoint body definition */
-function buildRequestBody(endpoint) {
-  if (!endpoint.body || endpoint.method === "GET") return undefined;
-  const properties = {};
-  const required = [];
-  for (const [name, desc] of Object.entries(endpoint.body)) {
-    if (name === "...") {
-      properties["additionalProperties"] = {
-        type: "object",
-        description: desc
-      };
-      continue;
-    }
-    properties[name] = {
-      type: "string",
-      description: desc
-    };
-    if (desc.toLowerCase().startsWith("required")) {
-      required.push(name);
-    }
-  }
+  // Return a minimal spec pointing to the canonical source
   return {
-    required: true,
-    content: {
-      "application/json": {
-        schema: {
-          type: "object",
-          properties,
-          ...(required.length > 0 ? {
-            required
-          } : {})
-        }
-      }
-    }
-  };
-}
-
-/** Generate the full OpenAPI 3.0 spec from SECTIONS */
-export function generateOpenApiSpec() {
-  if (_cachedSpec) return _cachedSpec;
-  const paths = {};
-  for (const [sectionKey, section] of Object.entries(SECTIONS)) {
-    for (const endpoint of section.endpoints) {
-      const openApiPath = toOpenApiPath(endpoint.path);
-      if (!paths[openApiPath]) paths[openApiPath] = {};
-      const method = endpoint.method.toLowerCase();
-      const operation = {
-        summary: endpoint.description,
-        operationId: `${method}_${sectionKey}_${endpoint.path.split("/").pop()?.replace(/:/g, "")}`,
-        tags: [section.name],
-        parameters: buildParameters(endpoint, endpoint.path),
-        responses: {
-          "200": {
-            description: endpoint.response || "Success",
-            content: {
-              "application/json": {
-                schema: {
-                  type: "object"
-                }
-              }
-            }
-          },
-          "401": {
-            description: "Unauthorized — missing or invalid API key"
-          },
-          "404": {
-            description: "Resource not found"
-          }
-        },
-        security: [{
-          BearerAuth: []
-        }, {
-          ApiKeyAuth: []
-        }]
-      };
-      if (endpoint.notes) {
-        operation.description = endpoint.notes;
-      }
-      const requestBody = buildRequestBody(endpoint);
-      if (requestBody) {
-        operation.requestBody = requestBody;
-      }
-      paths[openApiPath][method] = operation;
-    }
-  }
-  _cachedSpec = {
-    openapi: "3.0.3",
+    openapi: "3.1.0",
     info: {
       title: "WhaleTools Platform API",
-      description: "Complete commerce, catalog, CRM, analytics, and agent API for the WhaleTools platform.",
-      version: "2026-03-07",
-      contact: {
-        name: "WhaleTools",
-        url: "https://whaletools.dev"
-      }
+      version: "latest",
+      description: `Full spec available at ${OPENAPI_URL}`
     },
     servers: [{
       url: GATEWAY_BASE_URL,
       description: "Production"
     }],
-    security: [{
-      BearerAuth: []
-    }, {
-      ApiKeyAuth: []
-    }],
-    paths,
-    components: {
-      securitySchemes: {
-        BearerAuth: {
-          type: "http",
-          scheme: "bearer",
-          bearerFormat: "JWT",
-          description: "Supabase JWT from auth login"
-        },
-        ApiKeyAuth: {
-          type: "apiKey",
-          in: "header",
-          name: "x-api-key",
-          description: "Store API key generated via the api_keys tool"
-        }
-      }
-    },
-    tags: Object.entries(SECTIONS).map(([, s]) => ({
-      name: s.name,
-      description: s.description
-    }))
+    paths: {}
   };
-  return _cachedSpec;
 }
 //# sourceMappingURL=api-docs.js.map