# Studio S1: Launch polish, metadata, and AI build playbook

This file does two jobs:

1. **Launch checklist** you run before promoting the long-scroll Studio site to production.
2. **Full prompt playbook** for how to direct AI (or humans) to ship strong frontend code and coherent design on this repo, and how a structured rule set was used so generated code stays consistent.

Source material: `DESIGN_DOC.md`, `.cursor/rules/main.mdc`, `.cursor/rules/frontend-design.mdc`, `PROMPT_PLAYBOOK.md`, and the agent or voice rules under `.cursor/rules/agent-and-voice.mdc`.

---

## Part 1: How structured AI generation was meant to work

Use this section as the **system-style brief** you paste or attach when starting a new AI session on this codebase.

### 1.1 Single sources of truth

- **`DESIGN_DOC.md`**: visual direction, sections, stack, agent architecture, directory map. If a prompt says "DESIGN_DOC Section X", open it before coding.
- **`lib/profile.ts`**: copy for employers, contact, featured projects, Ask scripts. Do not invent facts; align long prose with `prasad_deshpande_complete_cv.md` when those change.
- **`.cursor/rules/`**: enforced constraints (TypeScript, no em dashes, VoiceProvider boundary, frontend tokens).

### 1.2 Workflow the AI should follow

1. **Plan**: name files to touch, risks, and what "done" means (build passes, no new lint debt).
2. **Implement**: smallest diff that satisfies the request. No drive-by refactors or unrelated files.
3. **Verify**: `npm run lint`, `npx tsc --noEmit`, `npm run build` before you call the task finished.
4. **Commit**: conventional message (`feat:`, `fix:`, `chore:`, and so on) after a coherent unit of work.

### 1.3 What to tell the model every time (copy block)

You can paste the following when starting a feature or polish pass:

```text
You are working on the devpd portfolio (live domain: knowpd.com), a long-scroll Next.js 16 App Router site.

Non-negotiables:
- Read DESIGN_DOC.md for section-specific behavior before changing layout, agent, or motion.
- TypeScript strict, no `any`. Server Components by default; 'use client' only for state or browser APIs.
- Styling: Tailwind + tokens in app/globals.css. No random hex colors; use DESIGN_DOC Section 2.2 / CSS variables.
- Copy: no Unicode em dash (U+2014). Use commas, parentheses, or two short sentences.
- Voice and speech: never import Web Speech APIs outside components/agent/voice/. Use VoiceProvider only.
- Agent: tools and RAG per DESIGN_DOC Section 7; do not invent employers, metrics, or projects.

Frontend quality:
- Before a new UI component, decide: (1) aesthetic role, (2) spacing rhythm on the 4px scale, (3) motion (duration, easing, reduced-motion behavior).
- Checklist before merge: responsive at 320 / 768 / 1440, keyboard + visible focus, hover on interactive elements, prefers-reduced-motion respected, WCAG AA contrast, no em dashes in user-facing strings.

Deliver: minimal diff, run lint + tsc + build, then suggest a conventional commit message.
```

### 1.4 Why this structure works

- **Rules in repo** (Cursor rules) reduce drift: every edit inherits the same constraints without re-pasting the whole brief.
- **Design doc as canon** stops one-off components from breaking the editorial, blue-toned, typography-forward look.
- **Profile and corpus as facts** keep the Ask agent and the page honest for recruiters.
- **VoiceProvider indirection** keeps a swap to server TTS or another vendor possible without rewriting the Studio UI.

---

## Part 2: Design decisions (frontend-design skill, adapted)

Commit to the direction locked in **DESIGN_DOC.md Section 2**:

- Editorial, premium feel (Opal, Apple, Linear as references), not generic SaaS.
- Blue-toned surfaces, never pure black.
- Typography-forward: serif display + sans body; monospace for labels and tech.
- Generous whitespace; scroll as narrative.
- Avoid AI-slop: centered card stacks, purple gradients, default Inter everywhere, emoji-heavy UI.

### Aesthetic before code

For a new component, decide explicitly:

1. What this component adds to the site mood (example: quiet, technical, monospace-forward).
2. Spacing rhythm (example: 16px base, 24px between rows, 48px section break), using the **4px scale**: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128, 192. No one-off values like 14px or 22px.
3. Motion: easing `cubic-bezier(0.22, 1, 0.36, 1)`, hover ~180ms, entrances ~400 to 600ms, stagger ~60ms. **Pinned scroll (GSAP)** only where DESIGN_DOC allows (CCTA-style section), not everywhere.

### Motion and accessibility

- Respect **`prefers-reduced-motion`**: reduce or remove parallax, long entrance animations, and nonessential motion on the solar scene, neural canvas, and section entrances.
- Keyboard: full tab order, **visible focus rings** (for example 2px using accent tokens).

### Typography and color

- Display: Instrument Serif, tight tracking.
- Body: Geist Sans; labels and chips: Geist Mono.
- Prose width: about **68ch** where long text appears.
- Colors: only tokens from **`globals.css`** (`--bg-deep`, `--ink-primary`, accents, etc.). New colors require a DESIGN_DOC update, not ad hoc hex in components.

---

## Part 3: Engineering constraints (summary)

- **Stack**: Next.js 16 App Router, React 19, Tailwind v4, TypeScript strict.
- **No barrel `index.ts` re-exports** (per project convention).
- **No CSS-in-JS** beyond what Next requires; prefer Tailwind and CSS variables.
- **Named exports** except Next page/layout/route defaults.
- **Agent**: max tool iterations from env; tools defined in `lib/agent/agent-loop.ts`; RAG from `lib/knowledge/source/corpus.md`.
- **Docker / production**: `output: "standalone"` in `next.config.ts`; see `Dockerfile` and `docker-compose.yml`.

---

## Part 4: S1 launch checklist (run before production)

**Purpose:** final pass before promoting the long-scroll Studio site.

### Steps

1. Run **`npm run build`**. Fix TypeScript and ESLint until clean.
2. Run **Lighthouse** on the deployed URL. Fix quick wins on performance and accessibility.
3. Search user-facing copy for **Unicode em dashes (U+2014)**. Replace with commas, parentheses, or two short sentences.
4. **Keyboard:** full tab pass, visible focus rings on links, buttons, and Ask controls.
5. **`prefers-reduced-motion`:** confirm solar, neural canvas, and section entrances stay acceptable (no nausea, no essential info only in motion).
6. **Mobile Safari:** scroll, nav, Ask suggested prompts, **no surprise audio** (mic and TTS are user gestures).
7. **Open Graph:** `app/opengraph-image.tsx` (or static asset), metadata in `app/layout.tsx` wired to `NEXT_PUBLIC_SITE_URL`.
8. **`app/sitemap.ts`** and **`app/robots.ts`** point at the real domain (`SITE_DOMAIN` / env).
9. **README** reflects Studio layout, scripts (`dev`, `build`, `start`, `verify`, Docker), and env setup.

### Commit

```text
chore: launch polish and metadata
```

---

## Part 5: Where to go next

- **Deep agent behavior:** `DESIGN_DOC.md` Section 7, `lib/agent/agent-loop.ts`, `app/api/chat/route.ts`.
- **Voice swap later:** `components/agent/voice/types.ts` and implementations under `components/agent/voice/`.
- **New sections on the page:** DESIGN_DOC Section 4 plus matching anchors in `lib/profile` navigation data.

This playbook is **public** under `public/prompts/` so you can link it from README or share it as the "how we built this with AI" reference without exposing private env or keys.