diff --git a/README.md b/README.md
index e215bc4..18c025b 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,67 @@
-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).
+# portfolio
 
-## Getting Started
+Personal portfolio site. Next.js App Router frontend, PocketBase as the CMS,
+rendered with on-demand ISR — content is served static and revalidated by
+webhook when the CMS changes.
 
-First, run the development server:
+## Stack
+
+- **Next.js 16** (App Router, React 19, standalone output)
+- **TypeScript** (strict)
+- **Tailwind CSS v4**
+- **PocketBase** — headless CMS, fetched at build/runtime via a typed client
+- **Biome** — lint + format
+- **Vitest** + Testing Library — unit/component tests
+- **Storybook** (a11y + Vitest addons) — component workshop
+- **Yarn 4**
+
+Architecture follows [Feature-Sliced Design](https://feature-sliced.design/)
+adapted to Next.js (`src/{shared,entities,widgets}` + `app/`).
+
+## Rendering
+
+Pages are statically generated and served through ISR. There is no fixed TTL —
+PocketBase calls the `/api/revalidate` webhook after any content mutation,
+which purges the matching cache tag (`revalidateTag`). See
+[`app/api/revalidate/route.ts`](app/api/revalidate/route.ts).
+
+## Getting started
 
 ```bash
-npm run dev
-# or
+yarn install
 yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open http://localhost:3000.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+Without a reachable PocketBase, the app falls back to fixtures in
+[`app/api/collections/[collection]/records/route.ts`](app/api/collections/%5Bcollection%5D/records/route.ts).
 
-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.
+## Environment
 
-## Learn More
+```
+PB_URL             # internal PocketBase URL (server-side fetches)
+PB_PUBLIC_URL      # public PocketBase URL (image optimizer allowlist, build-time)
+REVALIDATE_SECRET  # shared secret for the /api/revalidate webhook
+```
 
-To learn more about Next.js, take a look at the following resources:
+`PB_PUBLIC_URL` must be present at `next build` time — `images.remotePatterns`
+is frozen into the build.
 
-- [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.
+## Scripts
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+| Command | Description |
+|---|---|
+| `yarn dev` | Dev server |
+| `yarn build` | Production build (standalone) |
+| `yarn start` | Serve the build |
+| `yarn test` | Run tests (Vitest) |
+| `yarn check` | Lint + format (Biome, writes fixes) |
+| `yarn check:ci` | Lint + format check (no writes) |
+| `yarn storybook` | Storybook on :6006 |
 
-## Deploy on Vercel
+## Deployment
 
-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.
+Built as a standalone Docker image; PocketBase reached over the internal
+Docker network. Content updates trigger the revalidation webhook — no rebuild
+needed.