rezozero · timothejoubert · Jun 4, 2026 · Jun 4, 2026 · Jun 9, 2026 · Jun 9, 2026
diff --git a/AI_CONTEXT.md b/AI_CONTEXT.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,4 +1,30 @@
-# CLAUDE.md
+# Nuxt Starter — AI Context
+
+Nuxt 4 / Vue 3 starter connected to a Roadiz CMS. SSR, CSS Modules, pnpm, ESLint (no Prettier).
+
+Read [`docs/GUIDELINES.md`](./docs/GUIDELINES.md) before starting any integration task and strictly follow its rules throughout.
+
+---
+
+## Documentation
+
+When making a structural change (new module, renamed convention, new env variable, changed workflow), update the relevant file in `docs/` before closing the task.
+
+---
+
+## Do
+
+- Follow existing conventions and repo structure before introducing anything new.
+- Limit edits to files involved in the task.
+- Use existing tokens, mixins, and variables — check `app/assets/scss/` before creating new ones.
+- Explain changes and the reason behind them.
+
+## Don't
+
+- Modify or commit secrets (`.env`, credentials).
+- Introduce global reformatting unrelated to the task.
+- Add new conventions without justification.
+- Use `display: none` / `visibility: hidden` on interactive or form elements.
 
 ## Translations (i18n)
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/README.md b/README.md
@@ -2,9 +2,24 @@
 
 Nuxt starter for Roadiz-driven sites and platforms, with UI stories, i18n, optimized images, and a production-ready Docker setup.
 
+## Stack
+
+- **Nuxt 4 / Vue 3 / TypeScript** — SSR
+- **CSS Modules + SCSS** — no Tailwind, no global utility classes
+- **@roadiz/types** — CMS content types
+- **pnpm** — package manager
+- **ESLint** — linting and formatting (no Prettier)
+
+Key modules: `@nuxt/image` · `@nuxtjs/i18n` · `@rezo-zero/nuxt-stories` · `@nuxtjs/sitemap` · Sentry
+
+## Prerequisites
+
+- Node `24.14.1`
+- PNPM `11.5.1`
+
 ## Quick start
 
-1) Duplicate `.env.sample` into `.env` and fill the required values.
+1) Duplicate `.env.sample` into `.env` — required variables are listed in the Environment section below.
 2) Install dependencies:
 
 ```bash
@@ -25,135 +40,26 @@ docker compose up -d
 pnpm stories
 ```
 
-## Architecture in 2 minutes
-
-- Dynamic routing via Roadiz in `app/pages/[...slug].vue`.
-- Pages come from a Roadiz web response and render through global blocks.
-- Stories are available on `/_stories` to preview components.
-- Maintenance page is generated via a dedicated build.
-
-Full details: `docs/architecture.md`.
-
-## Folder structure
-
-- `app/pages` Nuxt routes (catch-all for Roadiz)
-- `app/components` app components
-- `app/blocks` Roadiz blocks components
-- `app/assets` images, icons, styles, story fixtures
-- `server` Nitro server API and story assets
-- `i18n` locales and config
-
-## Prerequisites
-
-- Node `24.12.0`
-- PNPM `9.12.0`
-
 ## Environment (.env)
 
-Duplicate `.env.sample` into `.env`, then fill in:
-
 - `NUXT_PUBLIC_SITE_URL`, `NUXT_PUBLIC_SITE_ENV`
 - `NUXT_PUBLIC_API_URL` (if using a remote API)
 - `NUXT_PUBLIC_INTERVENTION_REQUEST_*` for the image provider
 - `XILOFONE_*` if you want to fetch translations
 
-The full list and usage details are in `docs/architecture.md`.
+Full list and usage details: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
 
-## Useful commands
+## Commands
 
 ```bash
-## Development
-pnpm dev
-## Stories (UI)
-pnpm stories
-## Production build
-pnpm build
-## Production preview
-pnpm preview
-
-## Lint and format style (CSS / SCSS / Vue files)
-pnpm lint:css
-## Lint fix (script and style)
-pnpm lint-fix
+pnpm dev            # start dev server
+pnpm stories        # start UI stories (requires .env.stories)
+pnpm build          # production build
+pnpm lint           # lint all
+pnpm lint-fix       # lint and auto-fix
+pnpm xilo           # fetch translations from Xilofone
 ```
 
-
-
-## i18n
-
-Translations come from Xilofone and can be fetched with:
-
-At the beginning of a project, import the translation files into Xilofone before running `pnpm xilo`.
-
-```bash
-pnpm xilo
-```
-
-nuxt-i18n docs: https://v8.i18n.nuxtjs.org/
-
-## API
-
-The application connects to an API using the `NUXT_PUBLIC_API_URL` environment variable.
-
-When the Node SSR process and the browser live in different network planes, set `NUXT_SERVER_API_URL` so SSR requests use a different URL than the browser. This happens in two common scenarios:
-
-**Local development** — both the API and Nuxt run in Docker, but the browser runs on the host machine:
-```dotenv
-# Browser reaches the API through the exposed Docker port
-NUXT_PUBLIC_API_URL=http://localhost:8080
-# Node SSR reaches the API directly inside the Docker network
-NUXT_SERVER_API_URL=http://api:8080
-```
-
-**Cloud/Kubernetes** — keep SSR traffic inside the cluster network:
-```dotenv
-NUXT_PUBLIC_API_URL=https://api.example.com
-NUXT_SERVER_API_URL=http://api.internal
-```
-
-When `NUXT_SERVER_API_URL` is absent, both SSR and browser use `NUXT_PUBLIC_API_URL`. The server URL is never exposed to the client bundle.
-
-> **Warning:** `NUXT_SERVER_API_URL` must only be used for data fetching. Never use it to build URLs that are rendered in HTML (image `src`, anchor `href`, etc.): server and client would produce different values, causing Vue hydration mismatches. Rendered URLs always use `NUXT_PUBLIC_API_URL`.
-
-## Image
-
-## Images
-
-Nuxt Image is configured with the Intervention Request provider.
-Docs: https://image.nuxt.com/
-
-## SVG
-
-Import an SVG as a component:
-
-```vue
-<script setup lang="ts">
-import IconCheck from '~/assets/images/icons/check.svg?component'
-</script>
-
-<template>
-    <IconCheck />
-</template>
-```
-
-For icons, use `VIcon` with assets in `app/assets/images/icons`.
-
-## Maintenance
-
-The maintenance build generates a static page:
-
-```bash
-pnpm generate:maintenance
-```
-
-## Monitoring
-
-Sentry is configured via `NUXT_PUBLIC_SENTRY_DSN`.
-
-## Sitemap
-
-Sitemap is generated by `@nuxtjs/sitemap` with `/api/sitemap` as a source.
-
 ## Docker build
 
 Node build:
@@ -168,6 +74,11 @@ Full build with bake:
 docker buildx bake
 ```
 
-## Contributing
+## Documentation
 
-See `CONTRIBUTING.md`.
+| File | What it covers |
+|------|----------------|
+| [`CLAUDE.md`](./CLAUDE.md) | Code conventions, AI guidance (auto-loaded by Claude Code) |
+| [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) | PR workflow, commit conventions, linting |
+| [`docs/GUIDELINES.md`](./docs/GUIDELINES.md) | Frontend code rules: DOM, CSS Modules, accessibility, Vue, images |
+| [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | Technical architecture: routing, blocks, cache, env variables |