@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/remix/SKILL.md

@@ -1,85 +0,0 @@
----
-name: remix
-description: "Use when building Remix v2+ applications with nested routing, loaders, actions, progressive enhancement, streaming, server-side rendering, and full-stack data flow patterns."
----
-# Remix
-
-## Purpose
-
-Guide the design and implementation of production-grade Remix v2+ applications using nested routing, loader/action data flows, progressive enhancement, streaming with `defer` and `Await`, error boundaries, form handling, and server-side rendering. Every instruction prioritizes web-standards alignment, progressive enhancement as a default, and the Remix mental model of treating the browser as a thin client that enhances server-rendered HTML.
-
-## When to Use
-
-- Scaffolding a new Remix v2 application or migrating from Remix v1 / React Router to Remix v2 conventions.
-- Designing nested route hierarchies with shared layouts, pathless routes, and resource routes.
-- Implementing loaders and actions for server-side data fetching and form mutations.
-- Adding streaming with `defer`, `Await`, and `Suspense` for slow data sources.
-- Building progressively enhanced forms that work without JavaScript.
-- Configuring error and catch boundaries for graceful degradation.
-- Deploying Remix to edge runtimes (Cloudflare Workers, Vercel Edge, Deno Deploy).
-- Reviewing Remix code for waterfall data fetching, missing revalidation, or broken progressive enhancement.
-
-## Instructions
-
-1. **Confirm the Remix version and runtime adapter before generating code** because Remix v2 introduced Vite as the default bundler, flat file routing, and breaking changes to route module exports that invalidate patterns from v1. See `references/routing-conventions.md`.
-
-2. **Organize routes using flat file conventions with dot-delimited nesting** because Remix v2 uses `routes/parent.child.tsx` instead of folder nesting, and incorrect naming produces route mismatches that silently render the wrong layout without any build error.
-
-3. **Use `loader` functions for all GET-request data fetching and return plain objects or `json()` responses** because loaders run on the server before rendering, eliminating client-side fetch waterfalls and ensuring the initial HTML contains meaningful content for SEO and perceived performance. See `references/loaders-actions.md`.
-
-4. **Use `action` functions for all non-GET mutations and return redirect responses on success** because actions follow the POST/Redirect/GET pattern that prevents duplicate form submissions on refresh and ensures the browser history stack reflects the user's intent rather than intermediate mutation states.
-
-5. **Build forms with the Remix `<Form>` component instead of `<form>` for progressive enhancement** because `<Form>` intercepts submissions with JavaScript when available for instant optimistic UI, but falls back to a standard HTML form submission when JavaScript fails or is disabled, preserving full functionality.
-
-6. **Implement optimistic UI with `useNavigation` and `useFetcher` instead of local state** because Remix tracks all in-flight navigations and fetcher submissions, providing `navigation.state`, `navigation.formData`, and `fetcher.formData` that reflect the pending mutation without manual state management or race condition handling. See `references/progressive-enhancement.md`.
-
-7. **Use `defer` with `Await` and `Suspense` for data that is not critical to the initial render** because `defer` streams the shell HTML immediately and resolves slow promises on the server, sending the completed HTML chunks as they finish without blocking time-to-first-byte for the entire page. See `references/streaming-defer.md`.
-
-8. **Define `ErrorBoundary` exports in every route segment that can fail independently** because Remix renders the nearest ancestor ErrorBoundary when a loader or action throws, isolating failures to the affected route segment while the rest of the page remains interactive.
-
-9. **Use `shouldRevalidate` to prevent unnecessary loader re-execution after mutations** because Remix revalidates all active loaders by default after any action, and skipping revalidation for loaders whose data is unaffected by the mutation reduces server load and improves post-action render speed.
-
-10. **Colocate route-specific meta, links, and headers exports in the route module** because Remix merges these exports from the entire route hierarchy at render time, and missing or conflicting exports produce incorrect `<head>` content, duplicate stylesheets, or wrong cache headers.
-
-11. **Use resource routes (modules that export only a loader or action, no default component) for API endpoints, webhooks, and file downloads** because resource routes share the same authentication middleware, session handling, and deployment infrastructure as UI routes without requiring a separate API server. See `references/resource-routes.md`.
-
-12. **Handle sessions and cookies with the Remix `createCookieSessionStorage` or `createSessionStorage` utilities** because these utilities sign and encrypt session data by default, preventing tampering, and integrate with the loader/action request flow so sessions are available server-side without client-side storage.
-
-13. **Type loader and action data with `typeof loader` inference instead of manual interfaces** because TypeScript infers the exact return shape from the loader function, and manual interfaces drift out of sync with the actual server response, causing runtime type mismatches that TypeScript cannot detect.
-
-14. **Validate action form data on the server using Zod or a similar schema library and return structured validation errors** because client-side validation is bypassable, and returning a `{ errors }` object from the action allows the form to re-render with field-level error messages without losing user input.
-
-15. **Use `useFetcher` for mutations that should not trigger a navigation** because `useFetcher` submits to an action and receives the response without changing the URL or scroll position, making it appropriate for inline edits, toggles, and background saves that happen within the current page context.
-
-16. **Configure cache headers in loader `headers` exports and use `stale-while-revalidate` for static-ish content** because Remix does not add caching by default, and proper cache headers at the route level reduce origin server load, improve TTFB for repeat visitors, and enable CDN edge caching without a separate caching layer.
-
-## Output Format
-
-Provide implementation code, route module definitions, loader/action functions, form components, and deployment configuration as appropriate. Include file paths relative to the `app/` directory using Remix v2 flat file conventions. When generating route modules, always show the complete module exports (`loader`, `action`, `default`, `ErrorBoundary`, `meta`, `headers`) relevant to the task.
-
-## References
-
-Load only what the current task requires.
-
-| File | Load when |
-| --- | --- |
-| `references/routing-conventions.md` | Task involves route hierarchy design, flat file naming, pathless routes, or layout routes. |
-| `references/loaders-actions.md` | Task involves data fetching, form mutations, server-side validation, or revalidation control. |
-| `references/progressive-enhancement.md` | Task involves optimistic UI, useFetcher, useNavigation, or forms that work without JavaScript. |
-| `references/streaming-defer.md` | Task involves defer, Await, Suspense, streaming SSR, or slow data source handling. |
-| `references/resource-routes.md` | Task involves API endpoints, webhooks, file downloads, or headless route modules. |
-
-## Codex Platform Notes
-
-- Codex supports native subagents via `.codex/agents/*.toml` files with `name`, `description`, and `developer_instructions`.
-- Each subagent TOML can specify `model` and `model_reasoning_effort` to optimize cost per task difficulty:
-  - Light tasks (exploration, docs): `model = "gpt-5.3-codex-spark"`, `model_reasoning_effort = "medium"`
-  - Heavy tasks (security audit, orchestration): `model = "gpt-5.4"`, `model_reasoning_effort = "high"`
-  - Standard tasks (implementation): inherit parent model (omit `model` field).
-- Built-in agents: `default`, `worker`, `explorer`. Custom agents extend these via TOML definitions.
-- Codex operates under network restrictions — skills should not assume outbound HTTP access.
-- Use `$ARGUMENTS` to access user-provided arguments when the skill is invoked.
-- All skill guidance executes within the sandbox; file I/O is confined to the workspace.
-- Skills are installed at `.agents/skills/<skill-id>/SKILL.md`. Workflow skills can also be compiled to `.agents/skills/<workflow-id>/SKILL.md` as `generatedSkills`.
-- Codex supports three autonomy levels: `suggest`, `auto-edit`, `full-auto`.
-- MCP skill tools are available when the Cubis Foundry MCP server is connected.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/remix/evals/assertions.md

@@ -1,50 +0,0 @@
-# Remix Eval Assertions
-
-## Eval 1: Nested Route with Loaders and Error Boundaries
-
-This eval tests the ability to design a Remix v2 blog platform with nested routing, server-side data loading, form-based mutations with progressive enhancement, and granular error boundaries.
-
-### Assertions
-
-| # | Type | What it checks | Why it matters |
-|---|------|----------------|----------------|
-| 1 | contains | `loader` — Server-side data fetching | Remix loaders run on the server before rendering, eliminating client-side fetch waterfalls. Without loaders, the initial HTML is empty, hurting SEO and perceived performance. |
-| 2 | contains | `action` — Server-side form handling | Actions follow the POST/Redirect/GET pattern, preventing duplicate form submissions on refresh. Using client-side fetch for mutations bypasses Remix's built-in revalidation and progressive enhancement. |
-| 3 | contains | `ErrorBoundary` — Granular error isolation | Remix renders the nearest ancestor ErrorBoundary when a loader or action throws. Without per-route error boundaries, a single failed data fetch crashes the entire page instead of just the affected section. |
-| 4 | contains | `Form` — Progressive enhancement | Remix's `<Form>` component intercepts submissions for instant optimistic UI with JavaScript, but falls back to standard HTML form submission without it. Using `<form>` directly loses the Remix navigation integration. |
-| 5 | contains | `blog.` — Flat file route conventions | Remix v2 uses dot-delimited flat file naming (blog.$slug.tsx) instead of v1 folder nesting. Wrong naming conventions produce route mismatches that silently render the wrong layout. |
-
-### What a passing response looks like
-
-- Route files: `app/routes/blog.tsx` (layout), `app/routes/blog._index.tsx` (post list), `app/routes/blog.$slug.tsx` (post detail), `app/routes/blog.$slug.edit.tsx` (edit form).
-- Each route exports a `loader` that fetches data server-side and returns `json()`.
-- The edit route exports an `action` that validates form data with Zod, saves to database, and returns `redirect()` on success or `json({ errors })` on validation failure.
-- The edit form uses `<Form method="post">` with `useActionData()` to display validation errors.
-- Each route exports an `ErrorBoundary` that renders a user-friendly error message with `useRouteError()`.
-- The blog layout route renders an `<Outlet />` for child content alongside the category sidebar.
-
----
-
-## Eval 2: Streaming Dashboard with Defer
-
-This eval tests the ability to build a streaming Remix page that returns fast data immediately and streams slow data progressively, with proper loading states and error handling for deferred promises.
-
-### Assertions
-
-| # | Type | What it checks | Why it matters |
-|---|------|----------------|----------------|
-| 1 | contains | `defer` — Streaming data response | `defer()` allows the server to send the HTML shell with resolved data immediately while streaming deferred promises as they complete, eliminating the need to wait for the slowest data source before sending any HTML. |
-| 2 | contains | `Await` — Deferred data rendering | The `<Await>` component resolves deferred promises in the component tree, integrating with Suspense for loading states. Without it, deferred data cannot be rendered after streaming. |
-| 3 | contains | `Suspense` — Loading state boundary | `<Suspense>` wraps `<Await>` to provide a fallback UI (skeleton) that renders in the initial HTML while deferred promises are pending. Missing Suspense boundaries cause unhandled promise errors. |
-| 4 | contains | `errorElement` — Deferred error handling | The `errorElement` prop on `<Await>` catches errors from deferred promises without propagating to the route ErrorBoundary, keeping the rest of the page functional when a single data source fails. |
-| 5 | contains | `typeof loader` — Type inference from loader | Using `typeof loader` for type inference ensures component types stay synchronized with the actual loader return shape. Manual interfaces drift out of sync when the loader changes. |
-
-### What a passing response looks like
-
-- Loader returns `defer({ user: await getUserProfile(userId), analytics: getAnalytics(userId) })` where user is awaited (critical) and analytics is a bare promise (deferred).
-- Component uses `useLoaderData<typeof loader>()` for type-safe data access.
-- User profile section renders immediately in the HTML response.
-- Analytics section is wrapped in `<Suspense fallback={<AnalyticsSkeleton />}>` with `<Await resolve={data.analytics} errorElement={<AnalyticsError />}>`.
-- The `<Await>` render function receives the resolved analytics data and renders charts/metrics.
-- `errorElement` renders a graceful fallback message when the analytics API fails.
-- TypeScript types are inferred from the loader, not manually defined.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/remix/evals/evals.json

@@ -1,68 +0,0 @@
-{
-  "evals": [
-    {
-      "name": "nested-route-with-loaders-and-error-boundaries",
-      "description": "Validate that the skill produces a Remix v2 nested route structure with loaders, actions, progressive enhancement, and error boundaries for a blog platform with authenticated authors.",
-      "input": "Build a Remix v2 blog platform with nested routes. The layout route at /blog shows a sidebar with post categories. Child route /blog/$slug renders the post content loaded from a database. Authors can edit their posts at /blog/$slug/edit using a form with server-side validation. The edit form must work without JavaScript. Add error boundaries for missing posts (404) and server errors. Use flat file routing conventions.",
-      "assertions": [
-        {
-          "type": "contains",
-          "value": "loader",
-          "description": "Route modules must export loader functions for server-side data fetching, ensuring the HTML response contains meaningful content on first render without client-side fetch waterfalls."
-        },
-        {
-          "type": "contains",
-          "value": "action",
-          "description": "The edit route must export an action function for handling form mutations server-side, following the POST/Redirect/GET pattern to prevent duplicate submissions on browser refresh."
-        },
-        {
-          "type": "contains",
-          "value": "ErrorBoundary",
-          "description": "Route modules must export ErrorBoundary components to isolate failures to the affected route segment, keeping the rest of the page interactive when a loader or action throws."
-        },
-        {
-          "type": "contains",
-          "value": "Form",
-          "description": "The edit form must use Remix's <Form> component for progressive enhancement, providing instant optimistic UI with JavaScript while falling back to standard HTML form submission without it."
-        },
-        {
-          "type": "contains",
-          "value": "blog.",
-          "description": "Route files must use Remix v2 flat file conventions with dot-delimited nesting (e.g., blog._index.tsx, blog.$slug.tsx) instead of folder-based nesting from v1."
-        }
-      ]
-    },
-    {
-      "name": "streaming-dashboard-with-defer",
-      "description": "Validate that the skill produces a streaming Remix page using defer and Await for a dashboard with mixed fast and slow data sources, including proper loading states and error handling.",
-      "input": "Create a Remix dashboard route at /dashboard that loads user profile data (fast, from cache) and analytics data (slow, from an external API that takes 2-3 seconds). The user profile must appear immediately in the HTML response. The analytics section should stream in after the external API responds. Show loading skeletons while analytics loads. Handle the case where the analytics API fails without breaking the profile section. Include proper TypeScript types inferred from the loader.",
-      "assertions": [
-        {
-          "type": "contains",
-          "value": "defer",
-          "description": "The loader must use defer() to return a mix of resolved data (user profile) and unresolved promises (analytics), enabling the server to stream the HTML shell immediately without waiting for slow data sources."
-        },
-        {
-          "type": "contains",
-          "value": "Await",
-          "description": "The component must use the Remix <Await> component to render streamed data when it resolves, integrating with React Suspense for loading states and error handling on deferred promises."
-        },
-        {
-          "type": "contains",
-          "value": "Suspense",
-          "description": "The component must wrap <Await> in a React <Suspense> boundary with a fallback UI (loading skeleton) that renders in the initial HTML while the deferred analytics promise is pending."
-        },
-        {
-          "type": "contains",
-          "value": "errorElement",
-          "description": "The <Await> component must include an errorElement prop to handle analytics API failures gracefully, preventing the error from propagating to the ErrorBoundary and breaking the entire dashboard."
-        },
-        {
-          "type": "contains",
-          "value": "typeof loader",
-          "description": "Loader data must be typed using TypeScript inference with typeof loader rather than manual interfaces, ensuring the component types stay synchronized with the actual loader return shape."
-        }
-      ]
-    }
-  ]
-}

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/remix/examples/01-basic-usage.md

@@ -1,212 +0,0 @@
-# Example: Blog with Nested Routes, Loaders, and Progressive Forms
-
-## Scenario
-
-A team is building a content blog with Remix v2. The blog has a layout with a sidebar listing categories, a post list page, individual post pages loaded from a database, and an edit page for authors. The edit form must work without JavaScript for accessibility and resilience. Route-level error boundaries should handle missing posts gracefully.
-
-## Prompt
-
-"Create a Remix v2 blog with nested routes. The /blog layout shows a category sidebar. /blog lists recent posts. /blog/$slug shows a post loaded from the database. /blog/$slug/edit has a form for updating the post title and body with server-side Zod validation. The edit form must work without JavaScript. Add ErrorBoundary for missing posts."
-
-## Expected Output
-
-### Route Files (Flat File Convention)
-
-```
-app/routes/
-  blog.tsx           # Layout: sidebar + Outlet
-  blog._index.tsx    # Post list
-  blog.$slug.tsx     # Post detail
-  blog.$slug.edit.tsx # Edit form
-```
-
-### Layout Route
-
-```tsx
-// app/routes/blog.tsx
-import { json, type LoaderFunctionArgs } from "@remix-run/node";
-import { Outlet, useLoaderData, NavLink } from "@remix-run/react";
-import { getCategories } from "~/models/category.server";
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  const categories = await getCategories();
-  return json({ categories });
-}
-
-export default function BlogLayout() {
-  const { categories } = useLoaderData<typeof loader>();
-
-  return (
-    <div className="blog-layout">
-      <aside className="sidebar">
-        <h2>Categories</h2>
-        <nav>
-          {categories.map((cat) => (
-            <NavLink key={cat.slug} to={`/blog?category=${cat.slug}`}>
-              {cat.name}
-            </NavLink>
-          ))}
-        </nav>
-      </aside>
-      <main>
-        <Outlet />
-      </main>
-    </div>
-  );
-}
-```
-
-### Post Detail with ErrorBoundary
-
-```tsx
-// app/routes/blog.$slug.tsx
-import { json, type LoaderFunctionArgs } from "@remix-run/node";
-import { useLoaderData, useRouteError, isRouteErrorResponse, Outlet } from "@remix-run/react";
-import { getPostBySlug } from "~/models/post.server";
-
-export async function loader({ params }: LoaderFunctionArgs) {
-  const post = await getPostBySlug(params.slug!);
-  if (!post) {
-    throw new Response("Post not found", { status: 404 });
-  }
-  return json({ post });
-}
-
-export default function PostDetail() {
-  const { post } = useLoaderData<typeof loader>();
-
-  return (
-    <article>
-      <h1>{post.title}</h1>
-      <time dateTime={post.publishedAt}>{post.publishedAt}</time>
-      <div dangerouslySetInnerHTML={{ __html: post.htmlContent }} />
-      <Outlet />
-    </article>
-  );
-}
-
-export function ErrorBoundary() {
-  const error = useRouteError();
-
-  if (isRouteErrorResponse(error) && error.status === 404) {
-    return (
-      <div className="error-container">
-        <h1>Post Not Found</h1>
-        <p>The post you are looking for does not exist or has been removed.</p>
-      </div>
-    );
-  }
-
-  return (
-    <div className="error-container">
-      <h1>Something went wrong</h1>
-      <p>An unexpected error occurred while loading this post.</p>
-    </div>
-  );
-}
-```
-
-### Edit Form with Progressive Enhancement
-
-```tsx
-// app/routes/blog.$slug.edit.tsx
-import { json, redirect, type ActionFunctionArgs, type LoaderFunctionArgs } from "@remix-run/node";
-import { Form, useActionData, useLoaderData, useNavigation } from "@remix-run/react";
-import { z } from "zod";
-import { getPostBySlug, updatePost } from "~/models/post.server";
-import { requireAuthor } from "~/utils/auth.server";
-
-const UpdatePostSchema = z.object({
-  title: z.string().min(1, "Title is required").max(200),
-  body: z.string().min(1, "Body is required"),
-});
-
-export async function loader({ params, request }: LoaderFunctionArgs) {
-  await requireAuthor(request);
-  const post = await getPostBySlug(params.slug!);
-  if (!post) {
-    throw new Response("Post not found", { status: 404 });
-  }
-  return json({ post });
-}
-
-export async function action({ params, request }: ActionFunctionArgs) {
-  await requireAuthor(request);
-  const formData = await request.formData();
-  const result = UpdatePostSchema.safeParse(Object.fromEntries(formData));
-
-  if (!result.success) {
-    return json(
-      { errors: result.error.flatten().fieldErrors },
-      { status: 400 }
-    );
-  }
-
-  await updatePost(params.slug!, result.data);
-  return redirect(`/blog/${params.slug}`);
-}
-
-export default function EditPost() {
-  const { post } = useLoaderData<typeof loader>();
-  const actionData = useActionData<typeof action>();
-  const navigation = useNavigation();
-  const isSubmitting = navigation.state === "submitting";
-
-  return (
-    <Form method="post">
-      <fieldset disabled={isSubmitting}>
-        <div>
-          <label htmlFor="title">Title</label>
-          <input
-            id="title"
-            name="title"
-            type="text"
-            defaultValue={post.title}
-            aria-invalid={actionData?.errors?.title ? true : undefined}
-            aria-describedby="title-error"
-          />
-          {actionData?.errors?.title && (
-            <p id="title-error" className="error">{actionData.errors.title[0]}</p>
-          )}
-        </div>
-
-        <div>
-          <label htmlFor="body">Body</label>
-          <textarea
-            id="body"
-            name="body"
-            rows={20}
-            defaultValue={post.body}
-            aria-invalid={actionData?.errors?.body ? true : undefined}
-            aria-describedby="body-error"
-          />
-          {actionData?.errors?.body && (
-            <p id="body-error" className="error">{actionData.errors.body[0]}</p>
-          )}
-        </div>
-
-        <button type="submit">
-          {isSubmitting ? "Saving..." : "Save Changes"}
-        </button>
-      </fieldset>
-    </Form>
-  );
-}
-
-export function ErrorBoundary() {
-  return (
-    <div className="error-container">
-      <h1>Error</h1>
-      <p>Could not load the edit form. You may not have permission to edit this post.</p>
-    </div>
-  );
-}
-```
-
-## Key Decisions
-
-- **Flat file routing** -- `blog.$slug.edit.tsx` uses dot-delimited nesting, the Remix v2 default. This keeps all route files in a single directory for easier navigation.
-- **`<Form method="post">`** -- works as a standard HTML form without JavaScript. When JS is available, Remix intercepts the submission for a client-side navigation with instant feedback.
-- **Server-side Zod validation** -- the action validates on the server because client-side validation is bypassable. Validation errors are returned as JSON and displayed next to the fields.
-- **`redirect()` on success** -- follows POST/Redirect/GET to prevent duplicate submissions on browser refresh.
-- **`throw new Response("...", { status: 404 })`** -- Remix catches thrown responses and renders the nearest ErrorBoundary with the status code, keeping the rest of the layout intact.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/remix/examples/02-advanced-usage.md

@@ -1,213 +0,0 @@
-# Example: Streaming Dashboard with Defer, Fetchers, and Resource Routes
-
-## Scenario
-
-A team is building an analytics dashboard with Remix v2. The dashboard loads user profile data instantly from cache and streams slow analytics data from an external API. A sidebar widget uses `useFetcher` to bookmark reports without navigating away. A resource route serves CSV exports. The team needs to handle analytics API failures without breaking the profile section.
-
-## Prompt
-
-"Create a Remix v2 analytics dashboard at /dashboard. Load user profile (fast, cached) and analytics summary (slow, 2-3s external API) with streaming. Show a loading skeleton for analytics. Handle analytics API failure gracefully. Add a fetcher-powered bookmark button for reports. Create a resource route at /dashboard/export.csv that streams a CSV download. Include proper TypeScript types and cache headers."
-
-## Expected Output
-
-### Streaming Loader with Defer
-
-```tsx
-// app/routes/dashboard.tsx
-import { defer, type LoaderFunctionArgs } from "@remix-run/node";
-import {
-  Await,
-  useLoaderData,
-  useFetcher,
-  Link,
-} from "@remix-run/react";
-import { Suspense } from "react";
-import { getUserProfile } from "~/models/user.server";
-import { getAnalyticsSummary } from "~/models/analytics.server";
-import { requireUserId } from "~/utils/auth.server";
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  const userId = await requireUserId(request);
-
-  // Await critical data, defer slow data
-  const user = await getUserProfile(userId);
-  const analytics = getAnalyticsSummary(userId); // NOT awaited — deferred
-
-  return defer(
-    { user, analytics },
-    {
-      headers: {
-        "Cache-Control": "private, max-age=60, stale-while-revalidate=300",
-      },
-    }
-  );
-}
-
-export function headers() {
-  return {
-    "Cache-Control": "private, max-age=60, stale-while-revalidate=300",
-  };
-}
-
-export default function Dashboard() {
-  const { user, analytics } = useLoaderData<typeof loader>();
-
-  return (
-    <div className="dashboard">
-      {/* Critical: renders immediately in HTML */}
-      <header>
-        <h1>Welcome, {user.name}</h1>
-        <p>{user.plan} plan — {user.projectCount} projects</p>
-      </header>
-
-      {/* Deferred: streams in after analytics API responds */}
-      <Suspense fallback={<AnalyticsSkeleton />}>
-        <Await resolve={analytics} errorElement={<AnalyticsError />}>
-          {(data) => (
-            <section className="analytics-grid">
-              <StatCard label="Page Views" value={data.pageViews} />
-              <StatCard label="Unique Visitors" value={data.uniqueVisitors} />
-              <StatCard label="Bounce Rate" value={`${data.bounceRate}%`} />
-              <StatCard label="Avg Session" value={`${data.avgSessionMinutes}m`} />
-              <ReportList reports={data.topReports} />
-            </section>
-          )}
-        </Await>
-      </Suspense>
-    </div>
-  );
-}
-
-function AnalyticsSkeleton() {
-  return (
-    <section className="analytics-grid">
-      {Array.from({ length: 4 }).map((_, i) => (
-        <div key={i} className="stat-card skeleton" aria-busy="true" />
-      ))}
-    </section>
-  );
-}
-
-function AnalyticsError() {
-  return (
-    <section className="analytics-error">
-      <p>Analytics data is temporarily unavailable. Your profile and projects are unaffected.</p>
-      <Link to="." reloadDocument>
-        Try again
-      </Link>
-    </section>
-  );
-}
-```
-
-### Fetcher-Powered Bookmark Button
-
-```tsx
-// app/components/BookmarkButton.tsx
-import { useFetcher } from "@remix-run/react";
-
-export function BookmarkButton({ reportId, isBookmarked }: {
-  reportId: string;
-  isBookmarked: boolean;
-}) {
-  const fetcher = useFetcher();
-
-  // Optimistic UI: use the pending form data if a submission is in flight
-  const optimisticBookmarked = fetcher.formData
-    ? fetcher.formData.get("bookmarked") === "true"
-    : isBookmarked;
-
-  return (
-    <fetcher.Form method="post" action="/dashboard/bookmark">
-      <input type="hidden" name="reportId" value={reportId} />
-      <input
-        type="hidden"
-        name="bookmarked"
-        value={String(!optimisticBookmarked)}
-      />
-      <button
-        type="submit"
-        aria-label={optimisticBookmarked ? "Remove bookmark" : "Add bookmark"}
-        disabled={fetcher.state === "submitting"}
-      >
-        {optimisticBookmarked ? "Bookmarked" : "Bookmark"}
-      </button>
-    </fetcher.Form>
-  );
-}
-```
-
-### Bookmark Action Route
-
-```tsx
-// app/routes/dashboard.bookmark.tsx
-import { json, type ActionFunctionArgs } from "@remix-run/node";
-import { requireUserId } from "~/utils/auth.server";
-import { toggleBookmark } from "~/models/bookmark.server";
-
-export async function action({ request }: ActionFunctionArgs) {
-  const userId = await requireUserId(request);
-  const formData = await request.formData();
-  const reportId = String(formData.get("reportId"));
-  const bookmarked = formData.get("bookmarked") === "true";
-
-  await toggleBookmark({ userId, reportId, bookmarked });
-  return json({ ok: true });
-}
-```
-
-### Resource Route for CSV Export
-
-```tsx
-// app/routes/dashboard.export[.csv].tsx
-import { type LoaderFunctionArgs } from "@remix-run/node";
-import { requireUserId } from "~/utils/auth.server";
-import { getAnalyticsExport } from "~/models/analytics.server";
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  const userId = await requireUserId(request);
-  const data = await getAnalyticsExport(userId);
-
-  const csv = [
-    "Date,Page Views,Unique Visitors,Bounce Rate",
-    ...data.rows.map(
-      (r) => `${r.date},${r.pageViews},${r.uniqueVisitors},${r.bounceRate}`
-    ),
-  ].join("\n");
-
-  return new Response(csv, {
-    headers: {
-      "Content-Type": "text/csv",
-      "Content-Disposition": 'attachment; filename="analytics-export.csv"',
-    },
-  });
-}
-```
-
-### Revalidation Control
-
-```tsx
-// app/routes/dashboard.tsx (additional export)
-import type { ShouldRevalidateFunctionArgs } from "@remix-run/react";
-
-export function shouldRevalidate({
-  formAction,
-  defaultShouldRevalidate,
-}: ShouldRevalidateFunctionArgs) {
-  // Only revalidate the dashboard loader when a bookmark action completes
-  // Skip revalidation for unrelated actions (e.g., logout, settings)
-  if (formAction?.startsWith("/dashboard")) {
-    return true;
-  }
-  return defaultShouldRevalidate;
-}
-```
-
-## Key Decisions
-
-- **`defer({ user, analytics })`** -- `user` is awaited (critical, renders in initial HTML), `analytics` is a bare promise (streamed after the external API responds). This sends the HTML shell in ~50ms instead of waiting 2-3s for the analytics API.
-- **`errorElement` on `<Await>`** -- analytics failures are caught by the Await's errorElement, not the route ErrorBoundary. The user profile and navigation remain functional.
-- **`useFetcher` for bookmarks** -- submits to `/dashboard/bookmark` without navigating away from the dashboard. The fetcher tracks submission state independently, enabling optimistic UI from `fetcher.formData`.
-- **Resource route with `[.csv]` escape** -- the brackets escape the dot in `export.csv`, making the file path `dashboard.export[.csv].tsx` which maps to the URL `/dashboard/export.csv`.
-- **`shouldRevalidate`** -- prevents re-fetching the slow analytics data when unrelated actions complete, reducing unnecessary server load.
-- **`stale-while-revalidate` cache headers** -- the dashboard serves stale content for up to 5 minutes while revalidating in the background, reducing origin server load for repeat visits.