diff --git a/AGENTS.md b/AGENTS.md index 8bd0e39..59b3dbe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,65 @@ +# Behavioral Guidelines (Karpathy) + +Behavioral guidelines to reduce common LLM coding mistakes. These must be followed for **all** work in this project. + +**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +## 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them — don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +## 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it — don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +## 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + # This is NOT the Next.js you know diff --git a/README.md b/README.md index 28367a2..2fd7e85 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,52 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# Film Intel -## Getting Started +Advanced movie insight you won't find in one click. Search any film and generate +ratings explained, skip guides, sensitivity warnings, international ratings, +production facts, and historical-accuracy breakdowns. -First, run the development server: +## Requirements + +- Node.js 22 +- A TMDB API key (https://www.themoviedb.org/settings/api) +- An LLM API key (OpenRouter or any OpenAI-compatible endpoint) +- PostgreSQL for caching generated insight cards (optional but recommended) + +Copy `.env.example` to `.env` and fill in the keys. + +## Development with Docker (recommended) + +Starts the app (with live reload) and the database, and runs migrations +automatically on first start: ```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev -``` - -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. - -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. - -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. - -## Learn More - -To learn more about Next.js, take a look at the following resources: - -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. - -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! - -## Deploy on Vercel - -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. - -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. - -## Development with Docker (recommended for full features) - -The project uses Postgres for caching generated movie insight cards. For the best experience (including persistent cache and automatic migrations): - -```bash -# Start everything (app + database) docker compose -f docker-compose.dev.yml up --build ``` - Open http://localhost:3000 -- The first time it will run DB migrations automatically. -- Source code is mounted for live reload (`npm run dev` inside the container). +- Source code is mounted for live reload (`npm run dev` inside the container) - Stop with `docker compose -f docker-compose.dev.yml down` -Environment variables (TMDB_API_KEY, LLM_API_KEY, etc.) are read from your `.env` file. - -If you prefer running without Docker: +## Development without Docker ```bash +npm install npm run dev ``` -> Note: Without the database the insight cards will still generate (they just won't be cached), thanks to graceful cache handling. +> Without a database the insight cards will still generate (they just won't be +> cached), thanks to graceful cache handling. Run `npm run db:migrate` against a +> reachable Postgres to enable caching. ## Production ```bash docker compose -f docker-compose.yml up --build ``` + +## Scripts + +- `npm run dev` — start the Next.js dev server +- `npm run build` — production build +- `npm run start` — serve the production build +- `npm run lint` — run ESLint +- `npm run db:migrate` — apply database migrations diff --git a/app/globals.css b/app/globals.css index 94d202c..b04b054 100644 --- a/app/globals.css +++ b/app/globals.css @@ -1,8 +1,12 @@ @import "tailwindcss"; :root { - --background: #020617; - --foreground: #f8fafc; + --background: #f9f6f0; + --foreground: #1c1917; + --card: #ffffff; + --card-border: #e7e5e4; + --muted: #57534e; + --accent: #b45309; } @theme inline { @@ -13,8 +17,8 @@ } body { - background: var(--background); - color: var(--foreground); + background: #f9f6f0; + color: #1c1917; font-family: var(--font-geist-sans), system-ui, sans-serif; } diff --git a/app/layout.tsx b/app/layout.tsx index 7e2fadf..0b4621a 100644 --- a/app/layout.tsx +++ b/app/layout.tsx @@ -27,7 +27,7 @@ export default function RootLayout({ lang="en" className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`} > - + {children} diff --git a/app/movie/[id]/page.tsx b/app/movie/[id]/page.tsx index 4586ae0..63066c7 100644 --- a/app/movie/[id]/page.tsx +++ b/app/movie/[id]/page.tsx @@ -32,7 +32,7 @@ export default async function MoviePage({ /> -