@cubis/foundry 0.3.10

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/nextjs-developer/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: "nextjs-developer"
+displayName: "Next.js Developer"
+description: "Use for implementing/refactoring Next.js App Router features, Server Components/Actions, SEO, and production architecture. Not for version migration workflows or cache-components-only tuning."
+keywords:
+  [
+    "nextjs",
+    "next.js",
+    "react",
+    "app router",
+    "server components",
+    "server actions",
+    "vercel",
+    "ssr",
+    "seo",
+    "typescript",
+  ]
+---
+
+# Next.js Developer
+
+## Overview
+
+Senior Next.js developer expertise for Next.js 14+ with App Router and full-stack features. Covers server components, server actions, edge runtime, performance optimization, and production deployment with focus on fast, SEO-friendly applications.
+
+## When to Use
+
+- Building new Next.js 14+ projects with App Router
+- Implementing Server Components and Server Actions
+- Optimizing Core Web Vitals and performance
+- Setting up data fetching with caching and revalidation
+- Configuring SEO (metadata, sitemaps, structured data)
+- Deploying to Vercel, Docker, or self-hosted environments
+- Writing tests with Playwright and React Testing Library
+
+## Quick Reference
+
+### App Router File Conventions
+
+```
+app/
+├── layout.tsx          # Root layout (required)
+├── page.tsx            # Home page
+├── loading.tsx         # Loading UI (Suspense boundary)
+├── error.tsx           # Error boundary
+├── not-found.tsx       # 404 page
+├── (auth)/             # Route group (no URL segment)
+│   ├── login/page.tsx
+│   └── register/page.tsx
+├── dashboard/
+│   ├── layout.tsx      # Nested layout
+│   ├── page.tsx
+│   └── @modal/         # Parallel route (slot)
+│       └── (..)settings/page.tsx  # Intercepting route
+└── api/
+    └── route.ts        # API route handler
+```
+
+### Server vs Client Components
+
+```tsx
+// Server Component (default) — no directive needed
+async function ProductList() {
+  const products = await db.product.findMany();
+  return (
+    <ul>
+      {products.map((p) => (
+        <li key={p.id}>{p.name}</li>
+      ))}
+    </ul>
+  );
+}
+
+// Client Component — needs 'use client' directive
+("use client");
+import { useState } from "react";
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount((c) => c + 1)}>{count}</button>;
+}
+```
+
+### Server Actions
+
+```tsx
+// Inline server action
+async function createPost(formData: FormData) {
+  "use server";
+  const title = formData.get("title") as string;
+  await db.post.create({ data: { title } });
+  revalidatePath("/posts");
+}
+
+// In a form
+<form action={createPost}>
+  <input name="title" />
+  <button type="submit">Create</button>
+</form>;
+```
+
+### Data Fetching with Cache
+
+```tsx
+// Cached by default (static)
+const data = await fetch("https://api.example.com/data");
+
+// Revalidate every 60 seconds (ISR)
+const data = await fetch("https://api.example.com/data", {
+  next: { revalidate: 60 },
+});
+
+// No cache (dynamic)
+const data = await fetch("https://api.example.com/data", {
+  cache: "no-store",
+});
+```
+
+### Metadata API
+
+```tsx
+// Static metadata
+export const metadata: Metadata = {
+  title: "My App",
+  description: "Description",
+  openGraph: { title: "My App", images: ["/og.png"] },
+};
+
+// Dynamic metadata
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const product = await getProduct(params.id);
+  return { title: product.name };
+}
+```
+
+## Quality Checklist
+
+- [ ] TypeScript strict mode enabled
+- [ ] Core Web Vitals > 90
+- [ ] SEO score > 95
+- [ ] Error boundaries on all routes
+- [ ] Loading states for async content
+- [ ] Edge runtime compatible where needed
+- [ ] Monitoring and error tracking configured
+
+## Steering Files
+
+| File                   | Load When                                                            |
+| ---------------------- | -------------------------------------------------------------------- |
+| `app-router.md`        | Route structure, layouts, route groups, parallel/intercepting routes |
+| `server-components.md` | Server/Client component patterns, streaming, Suspense                |
+| `server-actions.md`    | Form handling, mutations, validation, optimistic updates             |
+| `data-fetching.md`     | Fetch patterns, caching, revalidation, SWR/React Query               |
+| `performance.md`       | Image/font/script optimization, Core Web Vitals, bundle analysis     |
+| `seo.md`               | Metadata API, sitemaps, structured data, Open Graph                  |
+| `deployment.md`        | Vercel, Docker, self-hosting, monitoring, multi-region               |
+| `testing.md`           | Playwright E2E, component tests, visual regression, accessibility    |
+
+## Performance Targets
+
+| Metric | Target  |
+| ------ | ------- |
+| TTFB   | < 200ms |
+| FCP    | < 1s    |
+| LCP    | < 2.5s  |
+| CLS    | < 0.1   |
+| FID    | < 100ms |

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/nextjs-developer/references/app-router.md

@@ -0,0 +1,218 @@
+# App Router Architecture
+
+## File Conventions
+
+| File            | Purpose                                                 |
+| --------------- | ------------------------------------------------------- |
+| `layout.tsx`    | Shared UI, persists across navigations, wraps children  |
+| `template.tsx`  | Like layout but re-mounts on navigation (new instance)  |
+| `page.tsx`      | Unique UI for a route, makes route publicly accessible  |
+| `loading.tsx`   | Loading UI using Suspense boundary                      |
+| `error.tsx`     | Error boundary for the segment                          |
+| `not-found.tsx` | 404 UI for the segment                                  |
+| `route.ts`      | API endpoint (cannot coexist with page.tsx in same dir) |
+
+## Layout Patterns
+
+```tsx
+// Root layout — required, wraps entire app
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+
+// Nested layout — wraps a segment and its children
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex">
+      <Sidebar />
+      <main className="flex-1">{children}</main>
+    </div>
+  );
+}
+```
+
+### Layout Rules
+
+- Root layout must contain `<html>` and `<body>` tags
+- Layouts do NOT re-render when navigating between child routes
+- Layouts cannot access `pathname` — use `usePathname()` in a Client Component
+- Data fetched in a layout is NOT passed to children — fetch in each segment
+
+## Route Groups
+
+Group routes without affecting the URL structure using `(folderName)`:
+
+```
+app/
+├── (marketing)/
+│   ├── layout.tsx      # Marketing layout
+│   ├── about/page.tsx  # /about
+│   └── blog/page.tsx   # /blog
+├── (shop)/
+│   ├── layout.tsx      # Shop layout
+│   ├── products/page.tsx  # /products
+│   └── cart/page.tsx      # /cart
+└── layout.tsx          # Root layout
+```
+
+Use cases:
+
+- Different layouts for different sections
+- Organizing routes by team or feature
+- Opting specific segments into a layout
+
+## Parallel Routes
+
+Render multiple pages simultaneously in the same layout using named slots (`@folder`):
+
+```tsx
+// app/layout.tsx
+export default function Layout({
+  children,
+  analytics,
+  team,
+}: {
+  children: React.ReactNode;
+  analytics: React.ReactNode;
+  team: React.ReactNode;
+}) {
+  return (
+    <>
+      {children}
+      {analytics}
+      {team}
+    </>
+  );
+}
+```
+
+```
+app/
+├── layout.tsx
+├── page.tsx
+├── @analytics/
+│   └── page.tsx
+└── @team/
+    └── page.tsx
+```
+
+### Parallel Route Rules
+
+- Slots are NOT route segments — `@analytics` doesn't affect the URL
+- Each slot can have its own `loading.tsx` and `error.tsx`
+- Use `default.tsx` in slots to handle unmatched routes
+
+## Intercepting Routes
+
+Intercept a route to show it in the current layout while preserving context:
+
+| Convention | Matches       |
+| ---------- | ------------- |
+| `(.)`      | Same level    |
+| `(..)`     | One level up  |
+| `(..)(..)` | Two levels up |
+| `(...)`    | From root     |
+
+```
+app/
+├── feed/
+│   ├── page.tsx
+│   └── (..)photo/[id]/page.tsx  # Intercepts /photo/[id] from /feed
+└── photo/
+    └── [id]/page.tsx            # Full page when accessed directly
+```
+
+Common pattern: modal on click, full page on direct URL or refresh.
+
+## Dynamic Routes
+
+```tsx
+// app/blog/[slug]/page.tsx — dynamic segment
+export default function Post({ params }: { params: { slug: string } }) {
+  return <h1>{params.slug}</h1>;
+}
+
+// app/shop/[...categories]/page.tsx — catch-all
+// Matches /shop/a, /shop/a/b, /shop/a/b/c
+export default function Category({
+  params,
+}: {
+  params: { categories: string[] };
+}) {
+  return <div>{params.categories.join(" > ")}</div>;
+}
+
+// app/shop/[[...categories]]/page.tsx — optional catch-all
+// Also matches /shop (without segments)
+```
+
+## Static Generation for Dynamic Routes
+
+```tsx
+// Generate static params at build time
+export async function generateStaticParams() {
+  const posts = await getPosts();
+  return posts.map((post) => ({ slug: post.slug }));
+}
+
+// dynamicParams = false → return 404 for unknown params
+export const dynamicParams = false;
+```
+
+## Route Handlers (API Routes)
+
+```tsx
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+export async function GET(request: NextRequest) {
+  const posts = await db.post.findMany();
+  return NextResponse.json(posts);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const post = await db.post.create({ data: body });
+  return NextResponse.json(post, { status: 201 });
+}
+```
+
+### Route Handler Rules
+
+- Cannot coexist with `page.tsx` in the same route segment
+- Supported methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
+- `GET` handlers are cached by default when not using `Request` object
+- Use `NextRequest` for access to cookies, headers, URL search params
+
+## Middleware
+
+```tsx
+// middleware.ts (at project root)
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+export function middleware(request: NextRequest) {
+  // Auth check
+  const token = request.cookies.get("token");
+  if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
+    return NextResponse.redirect(new URL("/login", request.url));
+  }
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/api/:path*"],
+};
+```

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/nextjs-developer/references/data-fetching.md

@@ -0,0 +1,266 @@
+# Data Fetching Patterns
+
+## Fetch in Server Components
+
+Server Components can fetch data directly without an API layer:
+
+```tsx
+// Direct database access
+async function ProductList() {
+  const products = await db.product.findMany({
+    orderBy: { createdAt: "desc" },
+    take: 20,
+  });
+  return (
+    <ul>
+      {products.map((p) => (
+        <ProductCard key={p.id} product={p} />
+      ))}
+    </ul>
+  );
+}
+
+// External API
+async function WeatherWidget({ city }: { city: string }) {
+  const res = await fetch(`https://api.weather.com/v1/${city}`);
+  if (!res.ok) throw new Error("Failed to fetch weather");
+  const data = await res.json();
+  return <div>{data.temperature}°C</div>;
+}
+```
+
+## Caching Strategies
+
+### Static Data (cached indefinitely)
+
+```tsx
+// Default behavior — cached at build time
+const data = await fetch("https://api.example.com/data");
+
+// Equivalent explicit form
+const data = await fetch("https://api.example.com/data", {
+  cache: "force-cache",
+});
+```
+
+### Time-Based Revalidation (ISR)
+
+```tsx
+// Revalidate every 60 seconds
+const data = await fetch("https://api.example.com/data", {
+  next: { revalidate: 60 },
+});
+
+// Page-level revalidation
+export const revalidate = 60; // seconds
+```
+
+### Dynamic Data (no cache)
+
+```tsx
+// Always fetch fresh
+const data = await fetch("https://api.example.com/data", {
+  cache: "no-store",
+});
+
+// Page-level dynamic
+export const dynamic = "force-dynamic";
+```
+
+### Tag-Based Revalidation
+
+```tsx
+// Tag a fetch
+const posts = await fetch('https://api.example.com/posts', {
+  next: { tags: ['posts'] },
+});
+
+// Revalidate by tag (in a Server Action)
+'use server';
+import { revalidateTag } from 'next/cache';
+
+export async function createPost() {
+  await db.post.create({ ... });
+  revalidateTag('posts'); // All fetches tagged 'posts' refetch
+}
+```
+
+## Parallel vs Sequential Fetching
+
+### Parallel (preferred)
+
+```tsx
+async function Dashboard() {
+  // Both requests start simultaneously
+  const [revenue, orders, customers] = await Promise.all([
+    getRevenue(),
+    getRecentOrders(),
+    getCustomerCount(),
+  ]);
+
+  return (
+    <div>
+      <RevenueChart data={revenue} />
+      <OrderList orders={orders} />
+      <CustomerCount count={customers} />
+    </div>
+  );
+}
+```
+
+### Sequential (when dependent)
+
+```tsx
+async function UserPosts({ userId }: { userId: string }) {
+  // Must get user first to know their preferences
+  const user = await getUser(userId);
+  // Then fetch posts based on user preferences
+  const posts = await getPosts({ category: user.preferredCategory });
+
+  return <PostList posts={posts} />;
+}
+```
+
+### Streaming with Suspense (best of both)
+
+```tsx
+import { Suspense } from "react";
+
+export default function Dashboard() {
+  return (
+    <div>
+      {/* Each section loads independently */}
+      <Suspense fallback={<Skeleton />}>
+        <Revenue />
+      </Suspense>
+      <Suspense fallback={<Skeleton />}>
+        <RecentOrders />
+      </Suspense>
+      <Suspense fallback={<Skeleton />}>
+        <TopProducts />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+## Client-Side Fetching
+
+### SWR
+
+```tsx
+"use client";
+
+import useSWR from "swr";
+
+const fetcher = (url: string) => fetch(url).then((r) => r.json());
+
+export function LivePrice({ productId }: { productId: string }) {
+  const { data, error, isLoading } = useSWR(
+    `/api/products/${productId}/price`,
+    fetcher,
+    { refreshInterval: 5000 }, // Poll every 5s
+  );
+
+  if (isLoading) return <PriceSkeleton />;
+  if (error) return <span>Error loading price</span>;
+  return <span>${data.price}</span>;
+}
+```
+
+### React Query (TanStack Query)
+
+```tsx
+"use client";
+
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+
+export function TodoList() {
+  const queryClient = useQueryClient();
+
+  const { data: todos, isLoading } = useQuery({
+    queryKey: ["todos"],
+    queryFn: () => fetch("/api/todos").then((r) => r.json()),
+  });
+
+  const mutation = useMutation({
+    mutationFn: (newTodo: string) =>
+      fetch("/api/todos", {
+        method: "POST",
+        body: JSON.stringify({ title: newTodo }),
+      }),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["todos"] }),
+  });
+
+  if (isLoading) return <Loading />;
+  return (
+    <ul>
+      {todos.map((todo) => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## When to Use What
+
+| Scenario                       | Approach                                            |
+| ------------------------------ | --------------------------------------------------- |
+| Static content (blog, docs)    | Server Component + `force-cache`                    |
+| Semi-static (product catalog)  | Server Component + `revalidate: 60`                 |
+| User-specific data             | Server Component + `no-store` + auth check          |
+| Real-time updates              | Client Component + SWR/React Query with polling     |
+| Infinite scroll                | Client Component + React Query `useInfiniteQuery`   |
+| Form submission result         | Server Action + `revalidatePath`/`revalidateTag`    |
+| Dashboard with mixed freshness | Suspense boundaries with different cache strategies |
+
+## Error Handling
+
+```tsx
+// error.tsx — automatic error boundary
+"use client";
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+## Request Deduplication
+
+Next.js automatically deduplicates `fetch` requests with the same URL and options during a single render pass:
+
+```tsx
+// Both components fetch the same URL — only ONE request is made
+async function Header() {
+  const user = await fetch("/api/user"); // Request 1
+  return <nav>{user.name}</nav>;
+}
+
+async function Sidebar() {
+  const user = await fetch("/api/user"); // Deduped — reuses Request 1
+  return <aside>{user.avatar}</aside>;
+}
+```
+
+For non-fetch data sources, use React `cache()`:
+
+```tsx
+import { cache } from "react";
+
+export const getUser = cache(async (id: string) => {
+  return await db.user.findUnique({ where: { id } });
+});
+```