AGENTS.md: the context an agent starts from (#293)

ddiff --git a/AGENTS.md b/AGENTS.md
nnew file mode 100644
iindex 0000000..919cd4d
---- /dev/null
++++ b/AGENTS.md
@@@ -0,0 +1,156 @@
++# AGENTS.md — OpenVibe.Design
++
++## Project overview
++
++The Design room: the theme studio where a person browses OpenVibe's themes, tries them on previews, edits
++one with WCAG contrast checks, uses it, submits it to the gallery and rolls back to an earlier setting;
++**Design Studio v1** (`/create`) where one prompt becomes three model variants; and the **Design Arena**
++where two outputs are judged blind at phone and desktop sizes and an Elo leaderboard per category ranks
++the designers with cost and time. Node.js/Express, PostgreSQL (or PGlite in development), CommonJS, **no
++build step**.
++
++- Service id `design`, port `5090`, origin `https://openvibe.design`, unit `openvibe-design.service`,
++  release root `/opt/openvibe.design`.
++- It stores no accounts and no tokens: the person's Network session lives in httpOnly cookies and their
++  theme lives in **OpenVibe.Network**; Arena rounds, entries, judgements and ratings live in
++  **OpenVibe.Bench**. The legacy `arena_*` tables remain only for historical account events/migration.
++- Sign-in is an OAuth 2 client of Network (`design`, authorization code + PKCE S256, state check, server-
++  side exchange). Every theme read/write is proxied to Network's `/api/themes` with the person's token.
++
++## What it owns
++
++- The studio UI and its derived token set, the contrast checks, previews (Live channel, Chat room, shop
++  grid), colour-vision views, gallery submission, history and restore.
++- The token files (`/tokens/<theme>.<ext>`) every tool can read, the icon/font/typeface endpoints, the
++  component registry, patterns and vectors, brand motion and the `changes` history.
++- Design Studio (`/create`, `/d/:id`): three model variants through AI route pins, an HTML sanitizer,
++  phone/tablet/desktop canvases, guest drafts (private cookie, max three) and per-day limits.
++- The Design Arena surface, its sanitized HTML in sandboxed CSP-capped iframes, blind voting and the
++  open JSONL dataset; Bench is the rating/storage authority.
++- The design-owned rows: designs, components, gallery/element records, deep-dive proposals, account-data
++  receipts and the migration's legacy tables.
++- The pages (`/`, `/studio`, `/t/:slug`, `/arena/*`, `/create`, `/d/:id`, `/developers`, `/brand`), the
++  MCP endpoint, the API and discovery files.
++
++Not owned: theme selection/storage (Network), Arena ratings/rounds (Bench), model execution (AI), the
++shared Frame/kit (`openvibe-shared`), identity.
++
++## Who calls it, and whom it calls
++
++- Callers: people in the browser; MCP clients; sites/tools reading `/tokens/*`, icons, fonts; services
++  with a Network service token audience `openvibe.design` and the route's capability.
++- Depends on: **Network** (SSO, `/api/themes`, projects/grants); **AI** (generate jobs, `ai.run.create`,
++  Design's client credentials); **Bench** (Arena rounds/entries/judgements/ratings, including
++  `bench.entry.create`); **Events** (account export/deletion); **Publishing** (SEO/SSR/index); PostgreSQL
++  and `openvibe-shared` for the Frame/kit/legal/SEO. The Bench scope must include `bench.entry.create` in
++  addition to the Arena capabilities.
++
++## Repository map
++
++- **Entry:** [server/index.js](server/index.js) — `createApp()`, listen, graceful stop.
++- **App:** [server/app.js](server/app.js) — helmet/CSP, `/auth`, `/internal/events`, `/internal/config`,
++  `/shared`, `/css`, `/js`, `/brand/motion`, `/changes`, `/api/v1/designs`, `/api/v1/gallery`, `/api`
++  (themes proxy), `/api/create`, `/api/v1/arena`, `/api/v1/brand`, `/tokens`, icons/fonts.
++- **Config/db:** [server/config.js](server/config.js), [server/db.js](server/db.js),
++  [server/settings.js](server/settings.js).
++- **Studio/tokens:** [server/themes.js](server/themes.js), [server/tokens.js](server/tokens.js),
++  [server/tokens/](server/tokens/) (`kit.js`, `formats.js`, `exports.js`), [server/typefaces/](server/typefaces/),
++  [server/vectors/svg.js](server/vectors/svg.js), [server/patterns/catalog.js](server/patterns/catalog.js),
++  [server/kit/](server/kit/).
++- **Arena/studio:** [server/arena/](server/arena/) (`ai.js`, `jobs.js`, `store.js`, `bench.js`,
++  `sanitize.js`, `kinds.js`), [server/designs.js](server/designs.js),
++  [server/create/](server/create/) (`api.js`, `options.js`, `billing.js`), [server/deepdive/](server/deepdive/).
++- **Elements/components:** [server/elements/](server/elements/), [server/components/store.js](server/components/store.js),
++  [server/publish.js](server/publish.js), [server/design-edit.js](server/design-edit.js).
++- **HTTP:** [server/http/](server/http/) — `pages.js`, `api.js`, `arena-api.js`, `design-api.js`, `tokens.js`,
++  `mcp.js`, `icons.js`, `fonts.js`, `brand-api.js`, `gallery-api.js`, `discovery.js`, `same-origin.js`.
++- **Browser:** [public/js/studio.js](public/js/studio.js) and the page scripts/CSS in [public/](public/).
++- **Deploy:** [deploy/systemd/openvibe-design.service](deploy/systemd/openvibe-design.service),
++  [deploy/nginx/openvibe.design.conf](deploy/nginx/openvibe.design.conf).
++
++## Commands
++
++```bash
++npm ci
++cp .env.example .env       # BASE_URL, OV_OAUTH_CLIENT_SECRET; Network URLs optional
++npm run dev                # http://localhost:5090
++npm test                   # test/run.js, PGlite, mock Network/AI/Bench
++npm test -- studio         # filter by file name
++ov test                    # the harness's sharded run of what the change reaches
++node --check <file.js>
++```
++
++## Database and migrations
++
++Design's own PostgreSQL database on the host's data role (ADR-035); embedded PGlite in development and
++tests. Async through `openvibe-sdk/db`; migrations `migrations/NNNN_*.sql` (through `0024_element_gallery.sql`)
++applied at boot; never edit an applied one, add a new number. Themes are not stored here — Network owns
++them; rounds/ratings are Bench's. The `arena_*` tables are legacy and must not be written.
++
++## Auth and security
++
++- People sign in through Network SSO; session tokens are httpOnly cookies and are only ever sent as the
++  `Authorization` header to the configured Network origin. Nothing renders or logs them.
++- A **theme write must come from this site's own origin** (`Origin` check); another site cannot make a
++  signed-in visitor change their theme.
++- `next` after sign-in is a path on this site only; control characters and backslashes are refused.
++- Model output is sanitized and rendered **only in sandboxed, CSP-capped iframes**; every dynamic value
++  in the placeholder views goes through the shared `esc`.
++- Service callers need a Network service token audience `openvibe.design` and the route's capability.
++- Secrets are environment-only; only variable names appear in code and docs.
++
++## Frontend loading model
++
++Server-rendered pages plus no-build browser scripts ([public/js/studio.js](public/js/studio.js) derives the
++token set from six colours); no SPA, bundler or transpiler. `openvibe-shared` supplies the Frame, kit and
++`/shared/*` from the pinned node_modules; `/tokens/*`, icons and fonts are served by Design. Readiness is
++truthful: `/api/ready` reports `degraded` (HTTP 200) when Network does not answer, and the pages and crawl
++files still serve.
++
++## Deploy
++
++`sudo ovhost deploy design` (checkout at `/opt/openvibe.design`, unit `openvibe-design.service` on
++`127.0.0.1:5090`, env `/etc/openvibe/design.env`). nginx
++[deploy/nginx/openvibe.design.conf](deploy/nginx/openvibe.design.conf) is installed with `ov-vhost-install`
++and allows GET/POST/PUT on `/api` and GET on `/auth`. Migrations run at boot; no secret in a command
++line, file or log.
++
++## Tests
++
++`npm test` runs each `test/*.test.js` in its own process with PGlite and in-process Network/AI/Bench
++mocks. It pins the theme proxy (token handling, 4xx pass-through, 502 on a Network failure), the Origin
++check, the WCAG gate and token derivation, the studio/previews, the Arena sanitizer and sandboxed frames,
++blind voting and Bench calls, designs/guest limits, account export/deletion and discovery. `ov test` runs
++the same.
++
++## Conventions
++
++- CommonJS, 4-space indent, single quotes, semicolons; factories with injectable config/db/clock/fetch/log.
++- Colours/tokens are data: derive them, never hard-code a token set in a page. WCAG contrast is a gate,
++  not a warning, except "lines against cards", which is advisory.
++- Errors are problem+json with stable codes; Network 4xx answers pass through, a Network failure is 502.
++- Model output is untrusted: sanitize, sandbox, escape, cap.
++
++## Pitfalls
++
++- **Network owns the theme.** Do not add a local theme store or a direct browser write; the proxy is the
++  only path, and the person's token never leaves the server header.
++- **The Origin check protects writes.** A same-site-but-not-own-origin POST must fail.
++- **The contrast checks gate "Use this theme".** Do not enable it when a required check fails; do not turn
++  the advisory "lines against cards" into a blocker.
++- **Arena output is untrusted HTML.** Keep the sanitizer and the sandboxed CSP iframe; never render model
++  HTML in the page's own document.
++- **Bench is the rating authority.** Do not add a local Elo table or count a vote twice; rounds/entries/
++  judgements go to Bench, and the legacy `arena_*` tables stay read-only.
++- **Guests are rate-limited and drafts are capped at three** in a private cookie; a signed-in design
++  belongs to its subject, not the cookie.
++- **Do not log, render or echo a token**, including in an error path.
++- **`/api/ready` degraded is not a failure** when Network is down; do not turn it into a 503 that removes
++  the studio from service.
++
++## Documentation
++
++- [README.md](README.md) — what the studio/Arena are, pages, token files, API/MCP, sign-in, config, deploy,
++  security.
++- [STATUS.json](STATUS.json) — the precise v2 summary.
++- OpenVibe.Contracts holds `design.*`/`bench.*` shapes; Network owns `themes`, Bench owns ratings.
ddiff --git a/CLAUDE.md b/CLAUDE.md
nnew file mode 100644
iindex 0000000..43c994c
---- /dev/null
++++ b/CLAUDE.md
@@@ -0,0 +1 @@
+[email protected]