HANDOFF — arkashj.com

Last updated: 2026-04-26 Owner: Arkash Jain (arkash@benmore.tech) Repo: Personal-Website · Live: https://www.arkashj.com

This document is the single source of truth for working on the site. Read this before touching CLAUDE.md, README.md, or any plan in docs/superpowers/.

1. Project goal

The site is two things at once, and both must stay true:

1. A personal portfolio for Arkash Jain — AI researcher (Harvard Kirchhausen Lab, four published papers including SpatialDINO) turned forward deployed engineer (Head of FDE at Benmore Technologies).
2. A deliberate O-1 visa evidence hub. Every claim of extraordinary ability — papers, GitHub contributions, talks, press, awards, current employer — must have a canonical, crawlable URL on this site that points to authoritative external proof. USCIS adjudicators, recruiters, and search engines should all land on the same evidence trail.

Design and SEO decisions are made through that lens. If a page can't be defended as either portfolio surface or evidence anchor, it doesn't ship.

2. Current state at a glance

Tagged v1.0.0 is the legacy Pages Router snapshot. Everything since is the v2 App Router rebuild — see CHANGELOG.md for the full ship log.

3. Repo layout

Personal-Website/
├── app/            # Next.js App Router. One folder per route. Each route owns its page.tsx + opengraph-image.tsx.
├── components/     # React components (UI primitives, sections, embeds, layout, SEO, MdxContent).
├── lib/            # Pure data + helpers — no React. Single source of truth for content arrays.
├── content/        # MDX files: writing posts and knowledge articles, picked up by content.ts at build time.
├── docs/           # Specs, plans, architecture diagrams, this handoff.
├── public/         # Static assets — images, favicon.svg. Imported directly, not via next/image.
└── types/          # Shared TypeScript types.

Top-level config: next.config.js, tailwind.config.js, tsconfig.json, vercel.json, .eslintrc.json, .prettierrc.

app/ — routes

/ /about /research /experience /projects /work /writing /writing/[slug] /media /knowledge /knowledge/[domain] /knowledge/[domain]/[slug] /architecture /VC (redirect) /Volunteering (redirect). Each route folder also contains opengraph-image.tsx that calls lib/og.tsx for a dynamic PNG.

components/

ui/         Button, Card, Badge, StatBadge — design system primitives
sections/   Hero, PaperCard, ProjectCard, ExperienceCard, ThesisTracker, TradeLog, etc.
layout/     Nav, Footer
embeds/     Tweet, YouTube, LinkedInPost, Substack, Gist (+ index.ts barrel)
seo/        JsonLd factories (Person, Article, ScholarlyArticle)
architecture/  ASCII flow renderers for /architecture
MdxContent.tsx  themed MDXRemote wrapper used by all MDX routes

lib/ — data layer (no CMS)

4. How to add content

Everything is either a TypeScript array in lib/ or an MDX file under content/. No CMS, no DB, no admin UI.

Frontmatter contract for MDX:

---
title: 'Why FDE'
date: 2026-04-12
tags: [fde, careers]
description: 'One-line summary used in OG + meta description.'
---

5. Embeds

All rich embeds are RSC components that work inside MDX. They live in components/embeds/ and are wired into MdxContent.tsx via the components map (or imported directly in MDX).

<Tweet id="1234567890" />
<YouTube id="dQw4w9WgXcQ" />
<LinkedInPost urn="urn:li:share:1234567890" />
<Substack publication="arkash" slug="why-fde" />
<Gist user="ArkashJ" id="abc123def456" />

Tweet uses react-tweet (already in package.json). The others are thin iframe wrappers — no extra deps.

6. Design system

Color tokens (Tailwind theme — tailwind.config.js)

Typography

• Body: Geist Sans (var(--font-geist-sans))
• Mono / labels: Geist Mono (var(--font-geist-mono))

Both loaded in app/layout.tsx via geist package.

Sharp edges

borderRadius is overridden so rounded, rounded-md, rounded-lg, rounded-sm all map to 0. Only rounded-xl (2px) and rounded-full exist. This is intentional — do not add ad-hoc radii.

Infinite grid background

Defined in tailwind.config.js as bg-grid + bg-[length:64px_64px]. Applied subtly in app/globals.css.

Primitives

components/ui/: Button, Card, Badge, StatBadge. Use these instead of raw markup. Sections in components/sections/ compose them.

7. SEO infrastructure

The site is engineered to be the canonical answer for "Arkash Jain" across both classical search and AI answer engines.

• Person JSON-LD injected on every page via root layout (app/layout.tsx → components/seo/JsonLd).
• Article / ScholarlyArticle JSON-LD on every writing post and research entry.
• app/sitemap.ts enumerates static routes + every dynamic MDX file (writing posts, knowledge articles, knowledge domains) with per-file lastmod.
• app/robots.ts allows all crawlers, points at the sitemap.
• <link rel="me"> on root layout to LinkedIn, GitHub, Substack, Twitter — verifies cross-platform identity for Mastodon-style relationship graph and AI provenance.
• Per-route OG images via app/**/opengraph-image.tsx calling lib/og.tsx (Edge runtime, satori). Title pulls from page metadata.
• vercel.json sets security headers (CSP, HSTS, frame-deny, etc.).
• <link rel="canonical"> on every page via lib/metadata.ts.

8. Common commands

npm run dev              # http://localhost:3000
npm run build            # Production build (must pass — no ignoreDuringBuilds anymore)
npm run lint             # ESLint
npm run lint:fix         # ESLint --fix
npm run format           # Prettier write
npm run format:check     # Prettier check (CI gate)

vercel deploy            # Preview deploy
vercel deploy --prod     # Production deploy (Vercel bot also auto-deploys main)

gh pr create             # Open PR
gh pr merge --squash     # Merge

Pre-commit: Husky + lint-staged runs next lint --fix --file and prettier --write on staged files.

9. What's NOT done yet (open work)

• ffmpeg demo recordings for /work cards (placeholders removed; need real captures).
• Light mode — currently dark only. Tokens are theme-ready but no toggle.
• More MDX content — most knowledge domains have 1–2 articles; goal is 5+ each.
• Proposed pages not yet scaffolded: /press, /talks, /achievements, /coursework, /collaborators, /open-source, /uses.
• Tailwind v4 upgrade — deferred. v3 works; no urgency.
• Animations / page transitions — none currently. Consider Framer Motion or View Transitions API once content stabilizes.
• Per-page hand-tuned OG PNGs — currently all generated. Hero pages could benefit from custom art.

10. Planning docs (read these before big changes)

11. Onboarding checklist

For someone new to the repo:

1. Clone and install — git clone then npm install. Node 20+.
2. Run dev — npm run dev → open http://localhost:3000. Verify the homepage loads with the grid background and teal accents.
3. Skim the data layer — open lib/site.ts, lib/data.ts, lib/media.ts. Most edits start here.
4. Read this file end-to-end, then CHANGELOG.md, then the foundation plan in docs/superpowers/plans/.
5. Make a trivial content edit — add a tag to a paper in lib/data.ts or fix a typo in content/writing/why-fde.mdx. Confirm hot reload works.
6. Run the gates — npm run build && npm run lint && npm run format:check. All three must pass before opening a PR.
7. Open a PR to main — Vercel posts a preview URL automatically. Verify your change on the preview before requesting review.
8. Merge — Vercel auto-deploys to production within ~60s.

Quick reference — file → purpose

If something here is wrong, fix it in the same PR as the code change. This file goes stale fast otherwise.