AI integration

## Task
 
Integrate the **Vlozi Blog SDK** (`@vlozi/blog`) into my React/Next.js application. Create a complete blog section with a list page, post detail page, category/tag navigation, and search functionality.
 
## STEP 1 — Analyze My Codebase First (MANDATORY)
 
Before writing ANY code, you MUST analyze my existing codebase and list your findings. Do not skip this step.
 
1. **Design system:** Check tailwind.config, globals.css, theme files, or CSS variables. List my color palette, fonts, border-radius tokens, and spacing scale.
2. **Component library:** Check if I use shadcn/ui, MUI, Chakra, Ant Design, or custom components. Look in /components/ui/ or /components/. List the exact components I have (Button, Input, Card, Badge, Skeleton, etc.).
3. **Layout pattern:** Check my existing pages. Identify the shared layout (header, footer, sidebar, container width, padding). The blog pages MUST use the exact same layout.
4. **Typography:** Note my font family, heading sizes, and text/muted colors.
5. **Routing:** Check if I use Next.js App Router or Pages Router.
6. **Dark mode:** Check if I have dark mode and how it's implemented.
 
**Output your findings before writing code** so I can verify you understood my codebase.
 
## STEP 2 — The four hard rules (violating any of these breaks the integration)
 
These are the most common ways to break the integration. Each rule prevents a real customer-reported failure mode.
 
### Rule 1 — Import `@vlozi/blog/styles.css` FIRST
 
```tsx
// app/layout.tsx
import "@vlozi/blog/styles.css";   // ← MUST be first
import "./globals.css";             // ← my own styles second

npm install @vlozi/blog

NEXT_PUBLIC_VLOZI_API_KEY={{API_KEY}}
NEXT_PUBLIC_VLOZI_BASE_URL=https://api.vlozi.app

interface VloziConfig {
  apiKey: string;
  baseUrl: string;
}
 
interface Post {
  title: string;
  slug: string;                  // canonical React key — Post type has NO id field
  excerpt: string;
  content?: string;              // HTML string — ONLY on single post (blog.get / usePost)
  publishedAt: string;           // ISO date string
  seoTitle?: string;
  seoDescription?: string;
  featuredImageUrl?: string | null;
  category?: Category | null;
  tags?: Tag[];
  author?: Author | null;        // Attribution, when configured
  readingTime?: number;          // Estimated minutes
}
 
interface Category {
  name: string;
  slug: string;
  postCount?: number;
}
 
interface Tag {
  name: string;
  slug: string;
  postCount?: number;
}
 
interface Author {
  name: string;
  slug?: string;         // URL-safe identifier (for /authors/:slug pages)
  avatarUrl?: string;    // Absolute URL to 1:1 avatar
  bio?: string;
  url?: string;          // Website or profile URL
}
 
interface ListParams {
  page?: number;                                  // default: 1
  limit?: number;                                 // default: 10, max: 100
  category?: string | string[];                   // slug, or array for OR-match
  tag?: string | string[];                        // slug, or array for OR-match
  search?: string;                                // case-insensitive title+excerpt search
  sort?: "publishedAt" | "title" | "createdAt";   // default: "publishedAt"
  order?: "asc" | "desc";                         // default: "desc"
}
 
interface PaginatedResponse<T> {
  data: T[];
  meta: { page: number; limit: number; total: number; totalPages: number; };
}
 
interface ArchiveGroup {
  year: number;
  month: number;       // 1–12
  monthName: string;   // "January", etc.
  posts: Post[];
  count: number;
}
 
interface ArchiveResult {
  groups: ArchiveGroup[]; // sorted newest first
  totalPosts: number;
}
 
interface NeighborsResult {
  previous: Post | null; // older adjacent post
  next:     Post | null; // newer adjacent post
}

client.blog.list(params?: ListParams) → Promise<PaginatedResponse<Post>>
client.blog.get(slug: string) → Promise<Post>  // includes full HTML content
client.blog.categories.list() → Promise<{ data: Category[] }>
client.blog.tags.list() → Promise<{ data: Tag[] }>
client.blog.archive(options?: { maxPosts?: number }) → Promise<ArchiveResult>
client.blog.related(slug: string, options?: { limit?: number; pool?: number }) → Promise<Post[]>
client.blog.neighbors(slug: string, options?: { pool?: number }) → Promise<NeighborsResult>

usePosts(params?: ListParams) → { data, loading, error, refetch, page, totalPages, hasNextPage, hasPrevPage }
usePost(slug: string) → { data: Post | null, loading, error }
useCategories() → { data: Category[] | null, loading, error, refetch }
useTags() → { data: Tag[] | null, loading, error, refetch }
useArchive(options?: { maxPosts?: number }) → { data: ArchiveResult | null, loading, error, refetch }
useRelatedPosts(slug: string, options?: { limit?: number; pool?: number }) → { data: Post[] | null, loading, error }
useNeighbors(slug: string, options?: { pool?: number }) → { data: NeighborsResult | null, loading, error }

Props: limit?, columns? (1|2|3|4), variant? ("grid"|"list"), category?, tag?, showPagination?, renderItem?, renderLoading?, renderEmpty?, renderError?, className?
⚠️ BlogList does NOT accept a search prop. For search, use usePosts hook directly.

Props: limit?, columns? (1|2|3|4), category?, tag?, search?, sort?, order?, rootMargin? (default "400px"), prefetchOnHover?, imageComponent?, renderItem?, renderLoading?, renderEmpty?, renderError?, className?

Props: post (required), variant? ("default"|"featured"|"compact"), onClick?, renderMeta?, footer?, className?

Props: slug (required), showFeaturedImage?, renderTitle?, className?

Props: variant? ("sidebar"|"tabs"|"pills"), activeCategory?, onSelect? (receives slug or null), showCounts?, className?

Props: variant? ("pills"|"cloud"), activeTag?, onSelect? (receives slug or null), showCounts?, className?

Props: variant? ("grouped"|"flat"), maxPosts? (default 1000), postHref?, renderGroup?, renderLoading?, renderEmpty?, renderError?, className?

Props: slug (required), limit? (default 3), pool? (default 100), columns?, heading?, renderItem?, imageComponent?, prefetchOnHover?, renderLoading?, renderError?, renderEmpty?, className?

Props: slug (required), pool? (default 500), postHref?, renderLink?, renderLoading?, hideWhenEmpty? (default true), className?

"use client";
import { VloziClient } from "@vlozi/blog";
import { VloziProvider } from "@vlozi/blog/react";
import { useMemo, ReactNode } from "react";
 
export function BlogProvider({ children }: { children: ReactNode }) {
  const client = useMemo(() => new VloziClient({
    apiKey: process.env.NEXT_PUBLIC_VLOZI_API_KEY!,
    baseUrl: process.env.NEXT_PUBLIC_VLOZI_BASE_URL!,
  }), []);
  return <VloziProvider client={client}>{children}</VloziProvider>;
}

 
## Minimal blog (2 pages)
 
Creates just a list page and detail page — no search or filtering. The AI will still match your existing design.
 
```md
Install @vlozi/blog and create:
1. /blog page — Post grid with pagination
2. /blog/[slug] page — Full post with SEO via generateMetadata
 
## STEP 1 — Analyze my codebase first (MANDATORY, output findings before coding):
- Layout: Find my header, footer, container width, and page padding. Blog MUST use the same layout.
- Components: Find my component library (shadcn/ui? MUI? custom?). Use MY Card, Button, Badge, Skeleton — don't create new ones.
- Theme: Find my colors, fonts, spacing, border-radius. Match them exactly.
- Dark mode: If I have it, support it.
 
## STEP 2 — Setup:

 
Env vars (.env.local):
NEXT_PUBLIC_VLOZI_API_KEY={{API_KEY}}
NEXT_PUBLIC_VLOZI_BASE_URL=https://api.vlozi.app
 
Provider (client component):
```tsx
const client = useMemo(() => new VloziClient({
  apiKey: process.env.NEXT_PUBLIC_VLOZI_API_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_VLOZI_BASE_URL!,
}), []);

 
## Blog widget (embed on any page)
 
Adds a "Latest Posts" section to an existing page. The AI will match your page's existing card and section styles.
 
```md
Add a "Latest Blog Posts" section to my homepage using @vlozi/blog.
 
## STEP 1 — Analyze my homepage first (MANDATORY, output findings before coding):
- Find the card style, section headings, spacing, typography, and colors already used on this page
- Find my existing Card, Badge, and Button components — use them, don't create new ones
- Find my container width and grid patterns
 
## STEP 2 — Setup:
```bash
npm install @vlozi/blog

const client = useMemo(() => new VloziClient({
  apiKey: process.env.NEXT_PUBLIC_VLOZI_API_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_VLOZI_BASE_URL!,
}), []);

const { data, loading } = usePosts({ limit: 3, sort: "publishedAt", order: "desc" });

 
## Customize your prompt
 
Append any of these to the prompts above to add specific features:
 
- **Custom cards:** `Don't use BlogCard. Build custom cards using usePosts hook and my existing Card component.`
- **SSG:** `Generate all blog pages statically using generateStaticParams.`
- **Dark mode:** `Ensure blog pages work in both light and dark mode using the same theme toggle as the rest of my app.`
- **Headless:** `Use only hooks (usePosts, usePost, useCategories, useTags). Build all UI from scratch using my component library.`
- **Category pages:** `Also create /blog/category/[slug] pages that filter posts by category.`
- **Raw API (non-React):** `Don't use the React SDK. Use raw fetch calls to /blog/public/posts, /blog/public/categories, /blog/public/tags with Authorization: Bearer header.`
- **Animations:** `Add smooth page transitions and card hover animations matching the style used elsewhere in my app.`
- **Breadcrumbs:** `Add breadcrumb navigation (Home → Blog → Post Title) using my app's existing breadcrumb component.`
 
## Troubleshooting
 
If the AI generates code with errors, paste this follow-up:
 
```md
Fix the Vlozi integration:
- "useVlozi must be used within a VloziProvider" → Wrap with <VloziProvider>
- "apiKey/baseUrl is required" → new VloziClient({ apiKey: process.env.NEXT_PUBLIC_VLOZI_API_KEY!, baseUrl: process.env.NEXT_PUBLIC_VLOZI_BASE_URL! })
- Content not styled → import "@vlozi/blog/styles.css"
- post.content undefined → content only exists on usePost/blog.get, not in list responses
- onSelect receives null → convert: (slug) => setState(slug ?? undefined)
- Search fires too fast → debounce 300ms, pass undefined not ""
- Search not working with BlogList → BlogList does NOT accept a search prop. Use the usePosts hook directly with { search: debouncedSearch } and render the grid manually
- Blog doesn't match my design → Analyze my tailwind.config / globals.css / components/ folder and use the SAME colors, fonts, spacing, border-radius, and components as the rest of my app