diff --git a/frontend/README.md b/frontend/README.md
index d6af7e3..ad80cda 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -1,32 +1,38 @@
-# React + TypeScript + Vite
+# Buckets — Frontend
-This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
+Standalone React SPA for the Buckets budgeting app. Talks to the Symfony +
+API Platform backend over a cookie-session API (`/api`).
-Currently, two official plugins are available:
+## Stack
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+- Vite + React + TypeScript (strict)
+- Tailwind 4 (`@tailwindcss/vite`) — dark-only "80s terminal" theme
+- oxlint (lint) + Prettier (format)
-## React Compiler
+## Development
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+The frontend runs as the `frontend` service in the project's compose stack
+(podman-compose, dev-only — defined in `compose.override.yaml`). Bring the stack
+up from the repo root (`dev-up`) and the Vite dev server is published on
+**http://localhost:5173**.
-## Expanding the Oxlint configuration
+The dev server proxies `/api` to the backend container (`http://php:80`) so the
+session cookie flows same-origin — no CORS in dev.
-If you are developing a production application, we recommend enabling type-aware lint rules by installing `oxlint-tsgolint` and editing `.oxlintrc.json`:
+Run commands inside the container:
-```json
-{
- "$schema": "./node_modules/oxlint/configuration_schema.json",
- "plugins": ["react", "typescript", "oxc"],
- "options": {
- "typeAware": true
- },
- "rules": {
- "react/rules-of-hooks": "error",
- "react/only-export-components": ["warn", { "allowConstantExport": true }]
- }
-}
+```
+podman exec buckets-budget_frontend_1 npm run build # tsc -b && vite build
+podman exec buckets-budget_frontend_1 npm run lint # oxlint
+podman exec buckets-budget_frontend_1 npm run format # prettier --write
+podman exec buckets-budget_frontend_1 npm run format:check # prettier --check
```
-See the [Oxlint rules documentation](https://oxc.rs/docs/guide/usage/linter/rules) for the full list of rules and categories.
+## Structure
+
+- `src/theme.css` — Tailwind import + the 80s terminal theme (OKLCH tokens, glow,
+ 7-segment font)
+- `src/components/ui/` — shared primitives (Button, Panel, DigitalProgressBar)
+- `src/components/layout/` — the app shell (AppLayout)
+- `src/lib/api.ts` — cookie-session API client (get/post/patch/delete, JSON-LD)
+- `src/types/api.ts` — Hydra/JSON-LD envelope types
diff --git a/frontend/public/favicon.svg b/frontend/public/favicon.svg
index 6893eb1..2ff84c7 100644
--- a/frontend/public/favicon.svg
+++ b/frontend/public/favicon.svg
@@ -1 +1,4 @@
-
\ No newline at end of file
+
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 8953049..8a8a123 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -3,6 +3,8 @@ import Button from './components/ui/Button'
import DigitalProgressBar from './components/ui/DigitalProgressBar'
import Panel from './components/ui/Panel'
+// Scaffold-only demo composition proving the primitives + theme render.
+// Replaced by real routed pages in the frontend feature tickets (#52–#56).
function App() {
return (
diff --git a/frontend/src/components/layout/AppLayout.tsx b/frontend/src/components/layout/AppLayout.tsx
index da6fc37..4f7fecf 100644
--- a/frontend/src/components/layout/AppLayout.tsx
+++ b/frontend/src/components/layout/AppLayout.tsx
@@ -7,7 +7,7 @@ interface AppLayoutProps {
export default function AppLayout({ children }: AppLayoutProps) {
return (