Full application build: landing page, auth, chat with MCP tool use, harness management, and OAuth

.cursor/rules/convex-id-types.mdc

@@ -0,0 +1,68 @@
+---
+description: Use Convex branded Id types instead of plain strings for document IDs. Applies when working with Convex state, props, or mutations.
+globs: apps/web/src/**/*.tsx,apps/web/src/**/*.ts,packages/convex-backend/convex/**/*.ts
+alwaysApply: false
+---
+
+# Convex Branded ID Types
+
+## Rule
+
+NEVER use `string` for Convex document IDs. NEVER use `as never` or `as Id<"...">` casts to silence type mismatches. Instead, use the generated `Id<"tablename">` type from `@harness/convex-backend/convex/_generated/dataModel` throughout the entire type chain — state, props, callbacks, and function parameters.
+
+## Why
+
+Convex generates branded types like `Id<"harnesses">` that are distinct from `string` at the type level. This prevents accidentally passing an `Id<"harnesses">` where an `Id<"conversations">` is expected. Using `as never` completely defeats this safety.
+
+## Import
+
+```tsx
+import type { Id } from "@harness/convex-backend/convex/_generated/dataModel";
+```
+
+## Pattern: State
+
+```tsx
+// GOOD — proper branded type
+const [activeId, setActiveId] = useState<Id<"harnesses"> | null>(null);
+
+// BAD — plain string loses type safety
+const [activeId, setActiveId] = useState<string | null>(null);
+```
+
+## Pattern: Component Props
+
+```tsx
+// GOOD — types flow from Convex queries to mutations without casts
+function HarnessCard({
+  harness,
+  onDelete,
+}: {
+  harness: { _id: Id<"harnesses">; name: string };
+  onDelete: (id: Id<"harnesses">) => void;
+}) {
+  return <button onClick={() => onDelete(harness._id)}>Delete</button>;
+}
+```
+
+## Pattern: Mutations
+
+```tsx
+// GOOD — types match, no casts needed
+const removeHarness = useMutation({
+  mutationFn: useConvexMutation(api.harnesses.remove),
+});
+removeHarness.mutate({ id: harness._id }); // Id<"harnesses"> flows naturally
+
+// BAD — as never bypasses ALL type checking
+removeHarness.mutate({ id: someString as never });
+```
+
+## How It Works
+
+1. Convex query results already return `_id` as `Id<"tablename">`
+2. Store these in state with `useState<Id<"tablename"> | null>`
+3. Pass through props with `Id<"tablename">` (not `string`)
+4. When the value reaches a mutation call, types match — zero casts needed
+
+The key is to never widen `Id<"tablename">` to `string` at any point in the chain.

.cursor/rules/tanstack-auth-guards.mdc

@@ -0,0 +1,95 @@
+---
+description: Use TanStack Router beforeLoad guards for authentication instead of navigating during render. Applies when creating or modifying protected routes in this project.
+globs: apps/web/src/routes/**/*.tsx
+alwaysApply: false
+---
+
+# TanStack Router + Clerk Auth Guards
+
+## Rule
+
+NEVER call `navigate()` during the render phase for authentication redirects. This is a React anti-pattern that causes unpredictable behavior, especially with SSR (TanStack Start).
+
+Instead, use TanStack Router's `beforeLoad` option to check authentication and `throw redirect()` before the component ever mounts.
+
+## How it works in this project
+
+The root route (`__root.tsx`) already fetches Clerk auth state server-side and injects `userId` into the route context:
+
+```tsx
+// __root.tsx — beforeLoad returns { userId, token } into context
+beforeLoad: async (ctx) => {
+  const { userId, token } = await fetchClerkAuth();
+  if (token) {
+    ctx.context.convexQueryClient.serverHttpClient?.setAuth(token);
+  }
+  return { userId, token };
+},
+```
+
+Child routes access `context.userId` in their own `beforeLoad`.
+
+## Pattern: Protected Route
+
+```tsx
+import { createFileRoute, redirect } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/my-protected-route")({
+  beforeLoad: ({ context }) => {
+    if (!context.userId) {
+      throw redirect({ to: "/sign-in" });
+    }
+  },
+  component: MyProtectedPage,
+});
+
+function MyProtectedPage() {
+  // No need for useUser() auth checks here — the user is guaranteed
+  // to be authenticated by the time this component renders.
+}
+```
+
+## Anti-pattern (DO NOT use)
+
+```tsx
+// BAD — navigating during render
+function MyPage() {
+  const { user } = useUser();
+  const navigate = useNavigate();
+
+  if (!user) {
+    navigate({ to: "/sign-in" }); // Side effect during render!
+    return null;
+  }
+}
+```
+
+## Data-dependent redirects
+
+For redirects that depend on client-side data (e.g., Convex queries), use `useEffect` — not a bare call during render:
+
+```tsx
+function ChatPage() {
+  const navigate = useNavigate();
+  const { data: harnesses, isLoading } = useQuery(convexQuery(api.harnesses.list, {}));
+
+  useEffect(() => {
+    if (harnesses && harnesses.length === 0) {
+      navigate({ to: "/onboarding" });
+    }
+  }, [harnesses, navigate]);
+
+  if (isLoading || !harnesses || harnesses.length === 0) {
+    return <LoadingSkeleton />;
+  }
+
+  // ... rest of component
+}
+```
+
+## Key points
+
+- `beforeLoad` runs top-down through the route tree, before any child `beforeLoad` or component.
+- `throw redirect()` accepts the same options as `navigate()` (e.g., `replace: true`, `search: {}`).
+- If `beforeLoad` throws, child routes will not load at all.
+- Do NOT import `useUser` from Clerk just for auth checks in route components — use `context.userId` in `beforeLoad` instead.

apps/web/.env.example

@@ -6,3 +6,6 @@ CLERK_SECRET_KEY=sk_test_
 
 # Convex configuration, get this URL from your [Dashboard](dashboard.convex.dev)
 VITE_CONVEX_URL=https://your-project.convex.cloud
+
+# FastAPI backend URL
+VITE_FASTAPI_URL=http://localhost:8000

apps/web/biome.json

@@ -24,7 +24,10 @@
 	"linter": {
 		"enabled": true,
 		"rules": {
-			"recommended": true
+			"recommended": true,
+			"correctness": {
+				"useUniqueElementIds": "off"
+			}
 		}
 	},
 	"javascript": {

apps/web/package.json

@@ -15,7 +15,9 @@
   "dependencies": {
     "@clerk/tanstack-react-start": "^0.29.1",
     "@convex-dev/react-query": "^0.1.0",
+    "@harness/convex-backend": "workspace:*",
     "@t3-oss/env-core": "^0.13.8",
+    "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-devtools": "^0.7.0",
     "@tanstack/react-query": "^5.90.21",
@@ -27,15 +29,21 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "convex": "^1.31.7",
+    "geist": "^1.7.0",
+    "highlight.js": "^11.11.1",
     "lucide-react": "^0.561.0",
-    "nitro": "npm:nitro-nightly@latest",
+    "motion": "^12.34.3",
     "radix-ui": "^1.4.3",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-hot-toast": "^2.6.0",
+    "react-markdown": "^10.1.0",
+    "rehype-highlight": "^7.0.2",
+    "remark-gfm": "^4.0.1",
     "tailwind-merge": "^3.0.2",
     "tailwindcss": "^4.1.18",
     "tw-animate-css": "^1.3.6",
+    "use-sync-external-store": "^1.6.0",
     "vite-tsconfig-paths": "^6.0.2",
     "zod": "^4.1.11"
   },

apps/web/src/components/harness-mark.tsx

@@ -0,0 +1,26 @@
+export function HarnessMark({
+	size = 24,
+	className,
+}: {
+	size?: number;
+	className?: string;
+}) {
+	return (
+		<svg
+			width={size}
+			height={size}
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			className={className}
+			aria-hidden="true"
+		>
+			<path d="M7 4v16" strokeWidth="2.5" />
+			<path d="M17 4v16" strokeWidth="2.5" />
+			<path d="M7 12 C9.5 8, 14.5 8, 17 12" strokeWidth="2" />
+			<path d="M7 12 C9.5 16, 14.5 16, 17 12" strokeWidth="2" />
+		</svg>
+	);
+}