@rovela-ai/sdk 0.19.4 → 0.19.5

package/templates/store-template/.claude/skills/add-section/SKILL.md

@@ -0,0 +1,438 @@
+---
+name: add-section
+description: Use when the user wants to add a new section to the homepage or any page. Covers component creation, page.tsx integration, responsive layout, and content from blueprint.
+---
+
+# Add Homepage Section
+
+> **Languages**: before writing any user-visible copy, check the store's
+> languages (`SELECT default_locale, enabled_locales FROM store_settings`).
+> Multilingual stores need every new string in ALL enabled languages via the
+> store dictionary — see CLAUDE.md §5.5 "Languages & translations". Internal
+> links always use `LocaleLink` from `@rovela-ai/sdk/core`, never raw
+> `next/link`.
+
+## Step-by-Step Process
+
+### 1. Create the Component
+
+Create a new file at `/app/components/sections/SectionName.tsx`:
+
+```tsx
+'use client';
+
+export default function SectionName() {
+  return (
+    <section className="py-16 md:py-24 px-4">
+      <div className="max-w-7xl mx-auto">
+        {/* Section content */}
+      </div>
+    </section>
+  );
+}
+```
+
+Add `'use client'` only if the component uses hooks (`useState`, `useEffect`) or event handlers (`onClick`, `onSubmit`). Pure display sections don't need it.
+
+### 2. Import in page.tsx
+
+```tsx
+// In /app/app/page.tsx
+import SectionName from '@/components/sections/SectionName';
+
+// Add below existing sections
+<SectionName />
+```
+
+### 3. Verify
+
+Run error check (get_errors) to confirm no TypeScript issues.
+
+## Content Sources
+
+- Use exact content from `/app/.rovela/blueprint.json` for headlines, descriptions, testimonials
+- Hardcode content directly in the component (not runtime reads)
+- For images: call `mcp__r2__generate_image` directly in this session (never via Task/Agent — subagents don't inherit MCP). Write descriptive scene prompts (40-75 words) using photography terminology. Use `imageUrl` from blueprint if already populated. A CSS gradient is acceptable per-image ONLY when the tool returns `{ success: false }` (Gemini API error/safety block) for that call — never as a substitute for skipping
+- Never hardcode external image URLs — always generate or use blueprint data
+
+## Header Customization
+
+The header is the FIRST thing visitors see. It MUST reflect the store's brand personality — never leave it as a generic white bar with gray text.
+
+**Read the Visual Creative Brief in CLAUDE.md** before customizing the header.
+
+### Solid Header (default)
+
+Use when the hero does NOT have a full-bleed background image:
+
+```tsx
+<header className="sticky top-0 z-50 w-full border-b border-border/40 bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+  <nav className="container mx-auto px-4 sm:px-6 lg:px-8">
+    <div className="flex h-16 items-center justify-between">
+      {/* Logo: use font-heading, brand-appropriate weight */}
+      <Link href="/" className="text-xl font-bold font-heading tracking-tight">
+        {storeName}
+      </Link>
+
+      {/* Nav links: use brand-appropriate hover color */}
+      <div className="hidden md:flex items-center gap-8">
+        {navigation.map((item) => (
+          <Link key={item.name} href={item.href}
+            className="text-sm font-medium text-muted-foreground transition-colors hover:text-primary">
+            {item.name}
+          </Link>
+        ))}
+      </div>
+
+      {/* Actions */}
+      <div className="flex items-center gap-3">
+        <CartIcon showCount />
+        {/* Mobile menu toggle */}
+      </div>
+    </div>
+  </nav>
+</header>
+```
+
+### Transparent Header (for hero with background image)
+
+Use when hero has `imageUrl` and layout is `fullscreen` or `center`:
+
+```tsx
+'use client';
+import { useState, useEffect } from 'react';
+
+export function Header() {
+  const [scrolled, setScrolled] = useState(false);
+
+  useEffect(() => {
+    const onScroll = () => setScrolled(window.scrollY > 50);
+    window.addEventListener('scroll', onScroll);
+    return () => window.removeEventListener('scroll', onScroll);
+  }, []);
+
+  return (
+    <header className={cn(
+      'fixed top-0 z-50 w-full transition-all duration-300',
+      scrolled
+        ? 'bg-background/95 backdrop-blur border-b border-border/40 shadow-sm'
+        : 'bg-transparent'
+    )}>
+      <nav className="container mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="flex h-16 items-center justify-between">
+          <Link href="/" className={cn(
+            'text-xl font-bold font-heading tracking-tight transition-colors',
+            scrolled ? 'text-foreground' : 'text-white'
+          )}>
+            {storeName}
+          </Link>
+          {/* Nav links: same transition pattern for text color */}
+        </div>
+      </nav>
+    </header>
+  );
+}
+```
+
+When using transparent header, add `pt-0` to the hero section (header overlaps it), NOT `mt-16`.
+
+---
+
+## Hero Section Patterns
+
+The hero is the most visually impactful section. Blueprint data is at `blueprint.homepage.hero`.
+
+**Required data points to implement:**
+- `headline.text` + `headline.emphasis[]` (words to style differently)
+- `subheadline.text`
+- `cta.primary` + `cta.secondary` (button text, variant, link)
+- `imageUrl` (from blueprint, or generated via `mcp__r2__generate_image` called directly in this session — per-image gradient fallback ONLY if that specific call returns `{ success: false }`)
+- `socialProof` (optional stats bar)
+- `layout` (split, center, fullscreen)
+
+### Split Layout (most common)
+
+Two columns: text left, image right. Stacks on mobile.
+
+```tsx
+<section className="relative py-20 lg:py-28">
+  <div className="container mx-auto px-4 sm:px-6 lg:px-8">
+    <div className="grid grid-cols-1 lg:grid-cols-2 gap-12 lg:gap-16 items-center">
+      {/* Text column */}
+      <div className="max-w-xl">
+        <h1 className="text-4xl sm:text-5xl lg:text-6xl font-bold font-heading tracking-tight leading-[1.1]">
+          {/* Render emphasis words with accent color */}
+          Barefoot Shoes for{' '}
+          <span className="text-primary">Natural Movement</span>
+        </h1>
+        <p className="mt-6 text-lg text-muted-foreground leading-relaxed">
+          {subheadline}
+        </p>
+        <div className="mt-8 flex flex-wrap items-center gap-4">
+          <Link href={cta.primary.link} className="inline-flex items-center px-7 py-3.5 rounded-lg bg-primary text-primary-foreground font-semibold text-sm shadow-sm hover:bg-primary/90 transition-colors">
+            {cta.primary.text}
+          </Link>
+          {cta.secondary && (
+            <Link href={cta.secondary.link} className="inline-flex items-center px-7 py-3.5 rounded-lg border border-border font-semibold text-sm hover:bg-accent transition-colors">
+              {cta.secondary.text}
+            </Link>
+          )}
+        </div>
+
+        {/* Social proof (if exists in blueprint) */}
+        {socialProof && (
+          <div className="mt-10 flex items-center gap-8 border-t border-border/50 pt-8">
+            {socialProof.content.map((stat) => (
+              <div key={stat.label}>
+                <div className="text-2xl font-bold font-heading">{stat.value}</div>
+                <div className="text-xs text-muted-foreground">{stat.label}</div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* Image column */}
+      <div className="relative aspect-[4/5] lg:aspect-[3/4] rounded-2xl overflow-hidden">
+        {imageUrl ? (
+          <img src={imageUrl} alt={headline} className="absolute inset-0 w-full h-full object-cover" />
+        ) : (
+          <div className="absolute inset-0 bg-gradient-to-br from-primary/20 via-accent/10 to-secondary/20" />
+        )}
+      </div>
+    </div>
+  </div>
+</section>
+```
+
+### Center Layout
+
+Full-width centered text. Image as subtle background or below text.
+
+```tsx
+<section className="relative py-24 lg:py-36">
+  {/* Optional background image with overlay */}
+  {imageUrl && (
+    <>
+      <img src={imageUrl} alt="" className="absolute inset-0 w-full h-full object-cover" />
+      <div className="absolute inset-0 bg-background/80 backdrop-blur-sm" />
+    </>
+  )}
+
+  <div className="relative container mx-auto px-4 sm:px-6 lg:px-8 text-center">
+    <h1 className="text-4xl sm:text-5xl lg:text-7xl font-bold font-heading tracking-tight leading-[1.1] max-w-4xl mx-auto">
+      {/* Emphasis words */}
+      Crafted for <span className="text-primary">Comfort</span>
+    </h1>
+    <p className="mt-6 text-lg lg:text-xl text-muted-foreground max-w-2xl mx-auto leading-relaxed">
+      {subheadline}
+    </p>
+    <div className="mt-10 flex items-center justify-center gap-4">
+      <Link href={cta.primary.link} className="inline-flex items-center px-8 py-4 rounded-lg bg-primary text-primary-foreground font-semibold shadow-sm hover:bg-primary/90 transition-colors">
+        {cta.primary.text}
+      </Link>
+      {cta.secondary && (
+        <Link href={cta.secondary.link} className="inline-flex items-center px-8 py-4 rounded-lg border border-border font-semibold hover:bg-accent transition-colors">
+          {cta.secondary.text}
+        </Link>
+      )}
+    </div>
+
+    {/* Social proof centered */}
+    {socialProof && (
+      <div className="mt-14 flex items-center justify-center gap-10 text-center">
+        {socialProof.content.map((stat) => (
+          <div key={stat.label}>
+            <div className="text-3xl font-bold font-heading">{stat.value}</div>
+            <div className="text-sm text-muted-foreground">{stat.label}</div>
+          </div>
+        ))}
+      </div>
+    )}
+  </div>
+</section>
+```
+
+### Fullscreen Layout
+
+Viewport-height hero with background image. Use transparent header (see above).
+
+```tsx
+<section className="relative min-h-[90vh] flex items-end pb-20 lg:pb-28">
+  {/* Background image */}
+  {imageUrl ? (
+    <>
+      <img src={imageUrl} alt="" className="absolute inset-0 w-full h-full object-cover" />
+      <div className="absolute inset-0 bg-gradient-to-t from-background via-background/50 to-transparent" />
+    </>
+  ) : (
+    <div className="absolute inset-0 bg-gradient-to-br from-primary/30 via-background to-accent/20" />
+  )}
+
+  <div className="relative container mx-auto px-4 sm:px-6 lg:px-8">
+    <div className="max-w-2xl">
+      <h1 className="text-4xl sm:text-5xl lg:text-6xl font-bold font-heading tracking-tight leading-[1.1] text-foreground">
+        {headline}
+      </h1>
+      <p className="mt-6 text-lg text-muted-foreground leading-relaxed">
+        {subheadline}
+      </p>
+      <div className="mt-8 flex flex-wrap items-center gap-4">
+        <Link href={cta.primary.link} className="inline-flex items-center px-7 py-3.5 rounded-lg bg-primary text-primary-foreground font-semibold shadow-sm hover:bg-primary/90 transition-colors">
+          {cta.primary.text}
+        </Link>
+      </div>
+    </div>
+  </div>
+</section>
+```
+
+### Emphasis Words
+
+Style words from `headline.emphasis[]` to stand out. Pick ONE approach per store:
+
+```tsx
+{/* Option 1: Brand color */}
+<span className="text-primary">Natural</span>
+
+{/* Option 2: Gradient text */}
+<span className="bg-gradient-to-r from-primary to-accent bg-clip-text text-transparent">Natural</span>
+
+{/* Option 3: Underline accent */}
+<span className="underline decoration-primary decoration-4 underline-offset-4">Natural</span>
+```
+
+### Hero Image Fallback
+
+ALWAYS handle missing `imageUrl`:
+
+```tsx
+{imageUrl ? (
+  <img src={imageUrl} alt={headline} className="w-full h-full object-cover" />
+) : (
+  <div className="w-full h-full bg-gradient-to-br from-primary/20 via-accent/10 to-secondary/20" />
+)}
+```
+
+---
+
+## Video in Sections
+
+Any section that takes an `imageUrl` can take a video URL instead — the merchant can paste a `.mp4` / `.webm` / `.mov` URL into chat ("use this for the hero") or store it via the admin product gallery. When you receive a media URL, decide between `<img>` and `<video>` by file extension.
+
+**Hero / background loop** — autoplay required, `muted` and `playsInline` are non-negotiable, `prefers-reduced-motion` falls back to a still:
+
+```tsx
+{isVideoUrl(mediaUrl) ? (
+  <video
+    src={mediaUrl}
+    autoPlay
+    muted
+    loop
+    playsInline
+    preload="metadata"
+    className="absolute inset-0 w-full h-full object-cover motion-reduce:hidden"
+  />
+) : (
+  <img src={mediaUrl} alt={headline} className="absolute inset-0 w-full h-full object-cover" />
+)}
+```
+
+**Foreground / testimonial / product demo** — explicit user control:
+
+```tsx
+<video
+  src={mediaUrl}
+  controls
+  preload="metadata"
+  className="w-full rounded-lg"
+/>
+```
+
+The `isVideoUrl` helper is exported from `@rovela-ai/sdk/media`. Or inline it: `url.match(/\.(mp4|webm|mov)(\?|#|$)/i)`.
+
+Never embed YouTube / Vimeo iframes — out of scope.
+
+---
+
+## Other Section Layout Patterns
+
+### Feature Grid (3-4 items)
+
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
+  {features.map((f) => (
+    <div key={f.title} className="p-6 rounded-lg bg-card border border-border">
+      <h3 className="text-lg font-semibold">{f.title}</h3>
+      <p className="mt-2 text-muted-foreground">{f.description}</p>
+    </div>
+  ))}
+</div>
+```
+
+### Testimonial Cards
+
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+  {testimonials.map((t) => (
+    <blockquote key={t.author} className="p-6 bg-card rounded-lg border border-border">
+      <p className="text-foreground italic">"{t.quote}"</p>
+      <footer className="mt-4 text-sm text-muted-foreground">— {t.author}</footer>
+    </blockquote>
+  ))}
+</div>
+```
+
+### CTA Banner
+
+```tsx
+<div className="text-center py-16 bg-primary text-primary-foreground rounded-2xl">
+  <h2 className="text-3xl font-bold">{headline}</h2>
+  <p className="mt-4 text-primary-foreground/80 max-w-xl mx-auto">{subheadline}</p>
+  <a href="/products" className="mt-8 inline-block px-8 py-3 bg-background text-foreground rounded-lg font-medium">
+    {buttonText}
+  </a>
+</div>
+```
+
+## Valid Routes for Links
+
+Link only to pages that exist:
+- Storefront: `/`, `/products`, `/cart`, `/checkout`
+- Auth: `/auth/signin`, `/auth/signup`, `/account`
+- Legal: `/contact`, `/privacy`, `/terms`
+
+Pages that DO NOT exist: `/about`, `/gallery`, `/pricing`, `/faq`, `/blog`, `/services`, `/team`
+
+Use anchor links (`#features`, `#testimonials`) for same-page navigation.
+
+## Section Type Catalog (16 types — picked from the brief's `homepageStructure`)
+
+When the merchant asks to "add a [section type]," look up the type in this catalog and use the matching skeleton. When they don't name a type, infer from intent ("add a process explanation" → `process-reveal`; "add an about-the-founders block" → `founders-note`; "add an editorial product spread" → `lookbook-spread`).
+
+- **`hero`** — first-impression headline + subhead + CTA. Pattern per the brief's `Hero pattern:` callout (9 patterns).
+- **`features`** — 3-4 card grid of brand benefits. `<section className="py-16 lg:py-24">` with `grid grid-cols-1 md:grid-cols-3 gap-8`. Each card: icon + h3 (≤4 words) + p (≤16 words).
+- **`process-reveal`** — How it's made / roasted / cured. 3-5 process steps with large step numbers + h3 + 30-50 word description. Use real verbs.
+- **`lookbook-spread`** — Editorial product spread (uses `editorial-2col` or `bento-grid` pattern). 3-6 products with prose copy.
+- **`manifesto-block`** — Single-column long-form brand prose. `<section className="py-32 lg:py-48 bg-muted/30">` + h2 + 60-120 word paragraph in display voice.
+- **`founders-note`** — Founder photo + signature quote. 5-col grid: photo (col-span-2) + quote (col-span-3, font-serif italic).
+- **`values-strip`** — Compact icon + label row. 3-5 brand values, `min-h-[8vh]` short rhythm.
+- **`how-it-works`** — Numbered steps for services/SaaS. 3 steps with big numbers + h3 + ≤20 word descriptions.
+- **`testimonials`** — Customer quotes. 2-4 quotes max, ≤30 words each, name specific product attributes.
+- **`social-proof`** — Press logos OR metric row ("4.9★ from 10K reviews"). Centered grid.
+- **`guide-spread`** — Educational content. 80-120 word intro + 2-4 guide entries with inline images.
+- **`faq`** — Accordion. 4-6 questions, ≤12 word question + ≤30 word answer.
+- **`newsletter-cta`** — Newsletter signup. `<section className="py-20 lg:py-24 bg-muted/30 text-center">` + h2 + 30-word body + email input + button.
+- **`trust`** — Trust badges row. 3-4 specific commitments with lucide icons + ≤8 word body.
+- **`cta`** — Final call-to-action. Big headline + single primary button.
+- **`product-showcase`** — Real products from DB. Pattern per the brief's `Product showcase:` callout (6 patterns).
+
+## Rhythm Sizes (5 sizes — variable cadence per section)
+
+- **`xs`** — `min-h-[8vh] py-4 lg:py-6` — strip, ribbon, pull-quote
+- **`sm`** — `py-12 lg:py-16` — trust strips, newsletter, social proof
+- **`md`** — `py-20 lg:py-24` — default for commerce sections
+- **`lg`** — `min-h-screen` or `py-32 lg:py-40` — hero, CTA, manifesto
+- **`xl`** — `min-h-[150vh]` or `py-40 lg:py-64` — editorial deep dives, lookbook spreads
+
+When adding a section, pick a rhythm that VARIES the page cadence — if surrounding sections are `md-md-md`, an inserted `xs` (strip) or `lg` (deep) breaks the rhythm and reads as designed.

package/templates/store-template/.claude/skills/build-feature/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: build-feature
+description: Use when the user asks for a new custom feature or module (booking, reviews, loyalty, wishlist, blog, etc.) that requires new database tables, API routes, and pages.
+---
+
+# Build Custom Feature
+
+## Workflow
+
+1. **Create database tables** via `getSql()` and `execute_sql` MCP tool
+2. **Build API routes** in `/app/api/` using `getSql()` for queries
+3. **Build frontend pages** (customer-facing and/or admin)
+4. **Update navigation** (Header, Footer, admin sidebar)
+5. **Verify** with `get_errors` after each file
+
+## Database Access
+
+**CRITICAL**: The SDK's `db` export is a Drizzle ORM instance. It does NOT have `.query()`, `.execute()`, or `.run()` methods.
+
+### For custom tables, use `getSql()`:
+
+```typescript
+import { getSql } from '@rovela-ai/sdk/core/server'
+
+const sql = getSql()
+
+// Results are arrays directly — NO .rows wrapper
+const rows = await sql`SELECT * FROM my_table WHERE status = ${status}`
+// rows = [{id: '...', name: '...'}, ...]
+
+// Parameterized (safe from SQL injection)
+await sql`INSERT INTO my_table (name, value) VALUES (${name}, ${value}) RETURNING *`
+```
+
+### For existing tables, use SDK query helpers:
+
+```typescript
+import { findProducts, findOrders, findCustomerByEmail } from '@rovela-ai/sdk/core/server'
+
+const products = await findProducts({ status: 'active' })
+const order = await findOrderById(orderId)
+```
+
+## Create Tables
+
+Use `execute_sql` MCP tool first, then verify:
+
+```sql
+CREATE TABLE IF NOT EXISTS my_feature (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name TEXT NOT NULL,
+  status TEXT DEFAULT 'active',
+  data JSONB DEFAULT '{}',
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+Then confirm with `list_objects` and `get_object_details`.
+
+## Custom API Route Template
+
+```typescript
+// app/api/my-feature/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { getSql } from '@rovela-ai/sdk/core/server'
+
+export async function GET(request: NextRequest) {
+  try {
+    const sql = getSql()
+    const { searchParams } = new URL(request.url)
+    const status = searchParams.get('status') || 'active'
+
+    const rows = await sql`
+      SELECT * FROM my_feature WHERE status = ${status}
+      ORDER BY created_at DESC
+    `
+    return NextResponse.json({ data: rows })
+  } catch (error) {
+    console.error('[MyFeature] GET error:', error)
+    return NextResponse.json({ error: 'Failed to load' }, { status: 500 })
+  }
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json()
+    if (!body.name) {
+      return NextResponse.json({ error: 'Name is required' }, { status: 400 })
+    }
+
+    const sql = getSql()
+    const result = await sql`
+      INSERT INTO my_feature (name, data)
+      VALUES (${body.name}, ${JSON.stringify(body.data || {})}::jsonb)
+      RETURNING *
+    `
+    return NextResponse.json({ data: result[0] }, { status: 201 })
+  } catch (error) {
+    console.error('[MyFeature] POST error:', error)
+    return NextResponse.json({ error: 'Failed to create' }, { status: 500 })
+  }
+}
+```
+
+## Admin Page Pattern
+
+Admin pages go in `app/admin/(dashboard)/`. **The Admin Design Contract (CLAUDE.md §7.6) is BINDING here** — use the SDK admin kit, never rebuild it. Full visual canon (only if §7.6 leaves a question open): Grep sections of `node_modules/@rovela-ai/sdk/docs/design/admin-ledger-visual-universe.html` — never read it whole.
+
+```typescript
+// app/admin/(dashboard)/my-feature/page.tsx
+'use client'
+
+import { useState, useEffect } from 'react'
+import { AdminPageHeader, AdminEmptyState, adminToast } from '@rovela-ai/sdk/admin'
+import { Calendar } from 'lucide-react'
+
+export default function AdminMyFeaturePage() {
+  const [data, setData] = useState<MyRow[]>([])
+  const [loading, setLoading] = useState(true)
+  const [loadError, setLoadError] = useState<string | null>(null)
+
+  useEffect(() => {
+    fetch('/api/admin/my-feature')
+      .then(res => res.ok ? res.json() : Promise.reject(res))
+      .then(json => setData(json.data || []))
+      .catch(() => setLoadError('Could not load. Refresh to retry.'))
+      .finally(() => setLoading(false))
+  }, [])
+
+  return (
+    <div className="space-y-6">
+      {/* AdminPageHeader owns the title + primary action — never a raw <h1> */}
+      <AdminPageHeader title="My feature" subtitle="One line on what this manages." />
+      <div className="admin-card admin-card-body">
+        {loadError && <div className="admin-alert-inline admin-alert-inline-error mb-4">{loadError}</div>}
+        {loading ? (
+          <div className="flex justify-center p-12"><span className="admin-spinner admin-spinner-lg" /></div>
+        ) : data.length === 0 ? (
+          <AdminEmptyState icon={<Calendar />} title="Nothing here yet" description="Create your first item to get started." />
+        ) : (
+          /* Tables: wrap in <div className="overflow-x-auto">, mark secondary
+             columns admin-col-optional. 2-4 column card lists: stacked rows,
+             not a table. Admin tokens only (hsl(var(--admin-*)) / admin-*
+             classes) — NEVER storefront tokens like text-muted-foreground. */
+          <div className="overflow-x-auto">{/* rows */}</div>
+        )}
+      </div>
+    </div>
+  )
+}
+```
+
+Non-negotiables on every admin page you build:
+- **Spinner**: the `admin-spinner` class — never `Loader2` or any animated lucide icon.
+- **Events → `adminToast.success/error`** (deleted, sent, saved-transactionally, failed); **states → inline `admin-alert`**. Never both for one outcome.
+- **Dialogs → `AdminModal`; deletes → `DeleteConfirmDialog`** — never native `confirm()`/`alert()`, never a hand-rolled fixed overlay, never inline "Delete? Yes/No".
+- **Document-shaped forms** (settings-like editing of an existing entity) save through `AdminSaveBar` + `useDirtyState`; transactional create/edit keeps inline buttons.
+- **Money**: decimal currency units (`29.99`), never cents. **Dates**: `useAdminDates` (store timezone). **Orders**: display in `order.currency`.
+- **375px**: responsive grid prefixes, no fixed widths over ~340px.
+
+## Admin Sidebar Navigation
+
+When your feature has an admin page, you MUST add it to the admin sidebar.
+
+Edit `app/admin/(dashboard)/layout.tsx` to pass `navItems` to `AdminLayout`:
+
+```typescript
+import { Calendar } from 'lucide-react'
+
+<AdminLayout
+  navItems={[
+    { id: 'my-feature', label: 'My Feature', href: '/admin/my-feature', icon: <Calendar className="h-4 w-4" /> },
+  ]}
+>
+```
+
+If `navItems` already exists, add your item to the existing array.
+Active state is auto-detected from the URL — no extra config needed.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| `db.query(sql)` | Use `getSql()` tagged templates |
+| `db.execute(sql)` | Use `getSql()` tagged templates |
+| `result.rows[0]` | `result[0]` — no `.rows` wrapper |
+| Missing `?.` on API responses | Always check `res.ok` before accessing data |
+| Admin API auth check with `getServerSession` | Admin pages are already protected by `AdminGuard` layout |
+| Forgot admin sidebar item | If feature has admin page, MUST add `navItems` to AdminLayout in layout.tsx |
+
+## Checklist
+
+- [ ] Tables created and verified with `list_objects`
+- [ ] API routes return correct data (test with `execute_sql` for comparison)
+- [ ] Frontend fetches from real API (not hardcoded data)
+- [ ] Error states handled (loading, empty, error)
+- [ ] `get_errors` returns zero errors
+- [ ] Customer navigation updated (Header/Footer links)
+- [ ] Admin sidebar updated if feature has admin page (`navItems` in layout.tsx)
+- [ ] Mobile responsive (no fixed widths)