docs: refresh README, architecture, spec and add agent teams proposal

- README: align env var table with real backend (OPENROUTER_API_KEY, HF_DATASET_ID, SPACE_ID,
PUBLISH_BASE_URL, ENABLE_PDF, OAUTH_SCOPES) and fix prerequisites
- ARCHITECTURE / SPECIFICATION: describe the new transformer pipeline, embed studio flow,
mobile TOC + CommentPopover; drop the deleted CommentsSidebar reference
- TESTS: announce the Playwright E2E suite as part of the stack and add 4.1.4 for the
upload rate limiter; note the split between fast hermetic suite and opt-in E2E
- Add AGENT_TEAMS_PROPOSAL.md to track the upcoming multi-agent collaboration design

Made-with: Cursor

README.md

@@ -13,25 +13,167 @@ hf_oauth_scopes:
 
 # Research Article Template Editor
 
-Collaborative real-time scientific article editor. Built with TipTap, Yjs, and Hocuspocus.
+A collaborative, real-time editor for web-native scientific articles. It lets multiple authors co-write a paper with rich text, math, citations, figures and interactive D3 embeds, then publishes the result as a static HTML page (or a PDF) aligned with the [research-article-template](https://github.com/huggingface/research-article-template).
 
-## Features
+![editor screenshot](./docs/screenshot.png)
 
-- Real-time collaborative editing (multiple cursors)
-- Rich text: headings, bold, italic, lists, blockquotes, code blocks
-- Export to MDX format
-- Dark theme
+## What it gives you
 
-## Development
+- **Real-time collaboration** over WebSocket (Y.js + Hocuspocus), with visible cursors and per-user selection colors
+- **Rich article authoring**: headings, lists, tables, code blocks with syntax highlighting, LaTeX math (KaTeX), footnotes, sidenotes, block quotes, callouts
+- **Research-specific blocks**: citations + bibliography (BibTeX), figures with captions, stacks / wide / full-width layouts, glossary terms, Mermaid/Wardley/architecture diagrams
+- **Interactive D3 embeds** authored inline: each embed is a self-contained HTML file the editor can generate and iterate on via an **AI-assisted "embed studio"**
+- **Comments & discussion** anchored on any selection
+- **Slash menu** (`/`) and drag/drop block handles, in the spirit of Notion
+- **Click-to-edit frontmatter**: title, subtitle, authors, affiliations, links, banner color
+- **Publishing pipeline**: one-click export to a standalone static HTML bundle, plus PDF generation (Puppeteer)
+- **Persistence**:
+  - Local mode: documents stored on disk under `DATA_DIR`
+  - HF mode: documents pushed/pulled from a Hugging Face dataset via OAuth
+- **Dark mode**, responsive layout (TOC drawer on mobile), live table of contents with scroll-spy
+- **AI chat side-panel** that can edit the article via structured tool calls (agent loop over the current TipTap doc)
+
+## Stack
+
+| Layer | Tech |
+|---|---|
+| Editor | React 18, TypeScript, TipTap v3, ProseMirror |
+| Collaboration | Y.js, Hocuspocus (WebSocket), y-tiptap |
+| Backend | Node.js, Express, Vite (dev proxy), Hocuspocus server |
+| Publishing | Custom TipTap-JSON → HTML renderer, Puppeteer for PDF |
+| AI | Vercel AI SDK v6 (`ai`, `@ai-sdk/react`), streaming tool calls |
+| Styling | Plain CSS with custom properties, no framework |
+| Storage | Local FS or Hugging Face datasets (via `@huggingface/hub`) |
+| Container | Single-image Docker build, runs on port 8080 |
+
+Around **3.6k LOC backend** and **9.5k LOC frontend** (TypeScript/TSX, excluding generated code).
+
+## Repo layout
+
+```
+collab-editor/
+├── backend/              # Express + Hocuspocus server, publisher, AI agent routes
+│   └── src/
+│       ├── server.ts             # Entry point
+│       ├── create-app.ts         # App factory (routes, middleware, Hocuspocus)
+│       ├── publisher/            # TipTap-JSON → HTML + PDF
+│       ├── agent/                # LLM agent (tool calls over the doc)
+│       ├── shared/               # Component defs shared with the frontend
+│       └── hf-storage.ts         # HF dataset sync
+├── frontend/             # Vite + React + TipTap editor
+│   └── src/
+│       ├── App.tsx               # Top-level shell
+│       ├── editor/               # TipTap editor + extensions + components
+│       ├── components/           # Shared UI pieces (TOC, Chat, Dialog, ...)
+│       ├── hooks/                # React hooks (agent chat, selection, ...)
+│       ├── styles/               # CSS layers (see docs/ARCHITECTURE.md)
+│       └── utils/
+├── docs/
+│   ├── ARCHITECTURE.md           # Deep dive on layers, data flow, CSS
+│   ├── SPECIFICATION.md          # Feature spec and contracts
+│   ├── TESTS.md                  # Testing strategy
+│   └── embed-studio.md           # How the AI-authored embeds pipeline works
+└── Dockerfile            # Production multi-stage build
+```
+
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for a diagram and the full tour.
+
+## Getting started
+
+### Prerequisites
+
+- Node.js 20+
+- An OpenRouter API key if you want the AI features (embed studio, chat agent)
+- A Hugging Face OAuth app (client id/secret) if you want login + HF dataset persistence
+
+### Local development
+
+Backend and frontend run as two separate processes in dev (Vite proxies `/api`, `/collab`, `/uploads`, `/published`, `/oauth`, `/auth` to the backend).
 
 ```bash
-# Backend
-cd backend && npm install && npm run dev
+# terminal 1 — backend (Express + Hocuspocus on :8080)
+cd backend
+cp .env.example .env          # fill in HF_TOKEN, OPENAI_API_KEY, ...
+npm install
+npm run dev
+
+# terminal 2 — frontend (Vite on :5678)
+cd frontend
+npm install
+npm run dev
+```
+
+Then open http://localhost:5678. Open a second tab or browser to see collaboration in action.
+
+### Production (Docker / HF Spaces)
 
-# Frontend (separate terminal)
-cd frontend && npm install && npm run dev
+The `Dockerfile` builds both frontend and backend into a single image listening on port 8080. This is the image used by the Hugging Face Space.
+
+```bash
+docker build -t collab-editor .
+docker run -p 8080:8080 --env-file backend/.env collab-editor
 ```
 
-Open http://localhost:5173. Open a second tab to see collaboration in action.
+Then open http://localhost:8080.
+
+## Scripts
+
+### Backend (`cd backend`)
+
+| Command | What it does |
+|---|---|
+| `npm run dev` | Start Express + Hocuspocus in watch mode |
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm start` | Run the compiled server |
+| `npm run test` | Unit + integration tests (Vitest) |
+| `npm run test:e2e` | End-to-end tests (Playwright) |
+
+### Frontend (`cd frontend`)
+
+| Command | What it does |
+|---|---|
+| `npm run dev` | Start Vite dev server on :5678 |
+| `npm run build` | Production bundle to `dist/` |
+| `npm run preview` | Preview the built bundle |
+| `npm run test` | Unit tests (Vitest) |
+| `npm run typecheck` | `tsc --noEmit` on the whole frontend |
+
+## Environment variables
+
+Copy `backend/.env.example` to `backend/.env` and fill the relevant values. Key ones:
+
+| Variable | Purpose |
+|---|---|
+| `OAUTH_CLIENT_ID` / `OAUTH_CLIENT_SECRET` | HF OAuth app for user login (required to edit when running on a Space) |
+| `OAUTH_SCOPES` | OAuth scopes (default `openid profile`) |
+| `OPENROUTER_API_KEY` | API key used by the AI agent (chat panel + embed studio) |
+| `OPENROUTER_MODEL` | Override the default OpenRouter model id |
+| `HF_TOKEN` | Server-side Hugging Face token (fallback when no user OAuth token is present) |
+| `HF_DATASET_ID` | Target HF dataset repo for document persistence (when not running on a Space) |
+| `SPACE_ID` / `SPACE_HOST` | Auto-set by HF Spaces; drive dataset id + secure cookies in production |
+| `DATA_DIR` | Where documents, uploads and published bundles are stored on disk (default: `./data`) |
+| `PUBLISH_BASE_URL` | Absolute base URL used when publishing (defaults to `http://127.0.0.1:${PORT}`) |
+| `ENABLE_PDF` | Set to `false` to disable Playwright-based PDF export |
+| `PORT` | Server port (default 8080) |
+
+## Testing
+
+- **Backend unit tests**: Vitest covers the publisher (HTML renderer, frontmatter, bibliography), storage, auth utilities.
+- **Backend E2E**: Playwright drives the full editor against a real backend.
+- **Frontend unit tests**: Vitest covers chat persistence and a handful of utilities.
+- **Type checking**: `npm run typecheck` in both workspaces.
+
+See [`docs/TESTS.md`](docs/TESTS.md) for the current strategy and gaps.
+
+## Known technical debt
+
+These are tracked explicitly so new contributors don't trip on them:
+
+- **`useAgentChat` / `useEmbedChat` still lack dedicated unit tests**; the rest of the stores (frontmatter, comments, embeds) are now covered.
+- **Bundle size warning**: the frontend bundle is over the 500 kB Vite warning threshold. Code-splitting the Mermaid / KaTeX / D3 stacks via dynamic imports would help.
+- **`addToolOutput` typing**: the ai-sdk v6 `ChatAddToolOutputFunction` is a generic over the tool name union. We currently cast to a plain signature at the two call sites because we don't export a typed tool registry yet.
+- **`backend/src/publisher/html-renderer.ts` is ~1000 LOC**: a per-node-type registry would make it more maintainable.
+
+## License
 
-The app uses a single shared document (`default`).
+Follow the upstream [research-article-template](https://github.com/huggingface/research-article-template) license.

docs/AGENT_TEAMS_PROPOSAL.md

@@ -0,0 +1,186 @@
+# Proposition - Passer d'un agent unique à une équipe d'agents
+
+> Réflexion inspirée de l'article [The Collaboration Gap](https://robotscooking.substack.com/p/the-collaboration-gap) (Adam Hyde, 2026) appliquée à `collab-editor`.
+
+## 1. Constat sur l'état actuel
+
+Le `collab-editor` est aujourd'hui structuré autour de **deux agents isolés** :
+
+| Agent | Fichier | Rôle |
+|---|---|---|
+| Article agent | `backend/src/agent/chat.ts` + `frontend/src/hooks/useAgentChat.ts` | Édite le TipTap doc via `applyDiff` / `replaceSelection` / `insertAtCursor` |
+| Embed agent | `backend/src/agent/embed-chat.ts` + `frontend/src/hooks/useEmbedChat.ts` | Génère les embeds D3 |
+
+Les deux ne se parlent pas. Ils ne partagent pas de contexte. L'utilisateur est le seul "orchestrateur", à la main, en switchant d'interface.
+
+C'est exactement le pattern "one human, one AI, one task" que l'article pointe comme limitant.
+
+## 2. Ce qu'on a déjà gratuitement (et que la plupart des setups multi-agents n'ont pas)
+
+| Brique | Fichier | Pourquoi c'est un atout |
+|---|---|---|
+| État partagé versionné (CRDT) | Y.js + Hocuspocus | C'est LE "shared board" de l'article, déjà construit, déjà résolveur de conflits |
+| Canal de messages ancrés | `frontend/src/editor/comments.ts` + `CommentsSidebar.tsx` | Communication latérale entre agents, visible par l'humain |
+| Undo groupé par tour | `UndoManager` + `startAgentBatch` | Rollback atomique d'une action d'équipe |
+| Tool calls structurés | `backend/src/agent/tools.ts` | Protocole déjà formalisé |
+| Frontmatter store réactif | `frontend/src/editor/frontmatter/frontmatter-store.ts` | État structuré séparé du corps, parfait pour un agent dédié |
+
+**Traduction** : on est mieux placés que Pure.Science pour implémenter ce que décrit Adam Hyde, parce que notre "bubble" existe déjà côté humain.
+
+## 3. Proposition d'architecture - 5 rôles
+
+Inspirée directement de Pure.Science (Wax, Ketty, Coco, Paige, Koda), mais adaptée à l'écriture scientifique web-native.
+
+### 3.1. Rôles
+
+| Agent | Rôle | Outils autorisés | Zones d'écriture |
+|---|---|---|---|
+| **Scout** | Topic Strategist : cadre le papier, propose l'angle | `setFrontmatterDraft`, `proposeOutline` (commentaire) | Commentaires uniquement |
+| **Archi** | Outliner / Structurer : gère TOC, hiérarchie, sections | `applyDiff` sur headings, `insertSection` | Headings, structure |
+| **Scribe** | Writer : rédige les paragraphes | `applyDiff`, `insertAtCursor` | Corps du texte |
+| **Biblio** | Literature Retriever : cherche des refs, pose des citations | `addCitation`, `addBibEntry`, `commentSuggestion` | Bibliography.bib + balises `[@key]` |
+| **Critic** | QA / Reviewer : relit, pointe incohérences, passe des commentaires | `comment`, `resolveComment`, `flagInconsistency` | Commentaires uniquement (read-only sur le doc) |
+
+**Point crucial** : seuls `Archi` et `Scribe` touchent au texte. `Critic` **ne peut pas éditer**, il commente - ça force la friction que décrit l'article et évite le "yes-man loop" des LLMs.
+
+### 3.2. Orchestrateur
+
+Un agent léger côté backend (nouveau fichier `backend/src/agent/orchestrator.ts`) qui :
+
+1. Reçoit le message de l'humain
+2. Lit l'état du doc (+ frontmatter + commentaires ouverts)
+3. Décide quel(s) agent(s) réveiller et dans quel ordre
+4. Tient un journal de tâches visible (équivalent du "board" dans l'article)
+
+L'orchestrateur n'édite jamais. Il **dispatche** et **attend**. Comme le facilitateur d'un Book Sprint.
+
+### 3.3. Code de conduite partagé
+
+Un prompt-système commun (nouveau `backend/src/agent/team-code-of-conduct.ts`) injecté dans **tous** les agents :
+
+```md
+1. Avant toute action, lis le board (commentaires ouverts + journal orchestrateur).
+2. Reste dans ton rôle. Si une tâche sort de ton périmètre, ping l'agent compétent via un commentaire typé.
+3. N'écrase pas le travail d'un autre agent sans laisser un commentaire justifiant le changement.
+4. Les désaccords se résolvent par commentaire ancré, pas par écrasement silencieux.
+5. Sois concis. Un message = une intention.
+```
+
+Directement dérivé du "code of conduct" Pure.Science.
+
+## 4. Communication latérale - piggyback sur les commentaires
+
+Plutôt qu'un bus de messages séparé, on étend le système de commentaires existant avec un champ `author` et `audience` :
+
+```ts
+interface AgentComment {
+  author: "scout" | "archi" | "scribe" | "biblio" | "critic" | "human";
+  audience: Array<"scout" | "archi" | "scribe" | "biblio" | "critic" | "human">;
+  kind: "suggestion" | "question" | "blocker" | "task";
+  anchor: { from: number; to: number };
+  body: string;
+}
+```
+
+Bénéfices :
+- L'humain voit **tout** dans la sidebar existante (`CommentsSidebar.tsx`)
+- Les agents s'adressent à un autre agent via `audience: ["scribe"]`
+- Rien à construire côté infra, juste étendre le schema
+
+## 5. UI - rendre l'équipe visible
+
+L'article insiste sur le fait que **la valeur de la collab est invisible si on ne la montre pas**. Proposition côté UI :
+
+### 5.1. Team activity timeline
+
+Un petit panneau dans `TopBar.tsx` ou sous le chat :
+
+```
+[Archi]  → created section "Methodology"       2s ago
+[Biblio] → suggested 3 citations in §2         5s ago
+[Critic] → flagged: unsupported claim in §3    8s ago
+[Scribe] → drafted paragraph in §1             12s ago
+```
+
+### 5.2. Curseurs colorés par agent
+
+On a déjà les curseurs multi-utilisateurs via `collaboration-cursor-v3.ts`. Chaque agent devient un "utilisateur virtuel" avec sa couleur et son nom de rôle. L'humain **voit en direct** où chaque agent travaille. Zero nouvelle infra.
+
+### 5.3. Quick actions par rôle
+
+Remplacer le `sendQuickAction` générique de `useAgentChat.ts` par un sélecteur de rôle :
+
+```
+Ask [ Scribe ▾ ] to: [ rewrite this paragraph ]
+```
+
+## 6. Plan d'implémentation progressif
+
+Par ordre de ROI, du plus petit au plus gros.
+
+### Étape 1 - Split sémantique sans nouvelle infra (2-3j)
+
+- Spécialiser le prompt actuel : le SYSTEM prompt passe de "tu es un assistant qui édite" à "tu es le Scribe, tu écris les paragraphes".
+- Ajouter un prompt `Critic` qui ne fait QUE passer des commentaires (pas de tool d'édition).
+- UI : un dropdown "Talk to [ Scribe / Critic ]".
+
+Valeur : on valide l'hypothèse qu'un agent read-only qui commente améliore la qualité perçue, avant de construire l'orchestration.
+
+### Étape 2 - Curseurs agents + timeline (2j)
+
+- Chaque agent = user Y.js virtuel avec couleur.
+- Timeline agrégée depuis les tool calls loggés.
+
+Valeur : rend la collaboration lisible, c'est le point central d'Adam Hyde.
+
+### Étape 3 - Biblio agent autonome (3-4j)
+
+- Outils `addCitation`, `searchArxiv`, `addBibEntry`.
+- Déclenchement automatique quand `Scribe` écrit une affirmation factuelle (via tool `requestCitation`).
+
+Valeur : premier cas de communication latérale agent→agent concrète.
+
+### Étape 4 - Orchestrateur (5-7j)
+
+- Nouveau route `/api/orchestrate` qui dispatche plutôt que de `/api/chat` directement.
+- Board visible dans le chat.
+
+Valeur : vrai multi-agent, mais seulement une fois les étapes 1-3 validées.
+
+### Étape 5 - Scout (cadrage initial) (3j)
+
+- Agent qui intervient uniquement au début d'un nouveau doc, à partir d'un prompt court "je veux écrire sur X".
+- Génère frontmatter + TOC + commentaires de cadrage.
+
+Valeur : onboarding d'un nouvel article 10x plus fluide.
+
+## 7. Métrique de succès
+
+Adam Hyde souligne qu'on ne sait pas benchmarker la collaboration. Proposition de 3 mesures simples et propres à l'éditeur :
+
+| Métrique | Comment | Pourquoi |
+|---|---|---|
+| **Commentaires résolus par session** | Compteur via le store de commentaires | Proxy de la qualité de la friction |
+| **Ratio d'édits rollback par l'humain** | Undo après action agent / total actions agent | Mesure l'alignement |
+| **Temps médian d'un article jusqu'à "publish"** | Log `published_at - created_at` côté backend | Mesure l'effet global |
+
+Pas de benchmark LLM abstrait : on mesure **sur le produit**.
+
+## 8. Risques et limites
+
+- **Coût tokens ×N** : chaque tour peut réveiller 2-3 agents. À mitiger avec un routing intelligent côté orchestrateur (ne pas réveiller `Biblio` si le message est "fix grammaire").
+- **LLMs d'accord avec tout** : le rôle `Critic` ne marche que si le prompt force la contradiction explicite. À itérer avec des exemples few-shot.
+- **UX du bruit** : si les 5 agents commentent en permanence, la sidebar devient illisible. Prévoir un mode "muet par défaut, opt-in par rôle".
+- **Complexité de debug** : logger impérativement le journal orchestrateur pour pouvoir rejouer une session.
+
+## 9. Ce que ça apporte à ton produit
+
+Aujourd'hui `collab-editor` est "un Notion-like pour papiers scientifiques avec un AI assistant". C'est bien, mais une dizaine de produits font ça.
+
+Avec cette architecture, tu deviens **le premier éditeur scientifique où une équipe d'agents spécialisés co-écrit avec l'humain**, en s'appuyant sur l'infra temps-réel Y.js que tu as déjà. C'est une proposition produit claire et différenciante, directement alignée avec la thèse de l'article :
+
+> "Les organisations qui investissent dans l'architecture de collaboration avec le même sérieux qu'elles investissent dans la capacité des modèles produiront de meilleurs résultats."
+
+## 10. Prochaine étape concrète suggérée
+
+Commencer par **l'étape 1** : forker `useAgentChat` en `useScribeChat` + `useCriticChat`, avec un simple toggle d'UI. C'est 2 jours de boulot, ça valide ou invalide l'hypothèse avant d'engager l'orchestrateur.

docs/ARCHITECTURE.md

@@ -29,37 +29,57 @@ The collab-editor is a collaborative article editor built for Hugging Face Space
 
 | Path | Description |
 |------|-------------|
-| `backend/src/server.ts` | Express server, routes, WebSocket setup |
+| `backend/src/server.ts` | Entry point: imports `createApp()`, starts listener, signal handlers |
+| `backend/src/create-app.ts` | Express app factory: routes, Hocuspocus, WebSocket, middleware |
 | `backend/src/publisher/` | HTML rendering, PDF generation, bibliography formatting |
 | `backend/src/publisher/html-renderer.ts` | Converts TipTap JSON to static HTML page |
 | `backend/src/publisher/extensions.ts` | Server-side TipTap extensions (mirrors frontend) |
 | `backend/src/shared/component-defs.ts` | Shared component definitions (single source of truth) |
+| `backend/src/utils.ts` | Shared utilities: `docPath()`, `sanitizeName()`, injectable `DATA_DIR` |
+| `backend/src/auth.ts` | OAuth flow, token extraction, user resolution |
+| `backend/src/hf-storage.ts` | HF dataset sync (push/pull documents and assets) |
 | `frontend/src/editor/` | TipTap editor, toolbars, components |
 | `frontend/src/editor/components/registry.ts` | Component registry (imports from shared defs) |
 | `frontend/src/styles/` | All CSS files |
-| `frontend/src/styles/_publisher.css` | Publisher-only CSS (injected into static HTML) |
-| `frontend/src/styles/_ui.css` | Editor chrome CSS (buttons, dialogs, drawers) |
 
 ## Styling architecture
 
 ### CSS layers
 
-The project uses three CSS layers:
+The project uses five CSS layers, loaded in this order by `main.tsx`:
 
-1. **Template CSS** (`_variables.css`, `_base.css`, `_layout.css`, `article.css`, `components/`)
-   - Defines the article's visual identity
+1. **Template foundation** (`_variables.css`, `_reset.css`, `_base.css`, `_layout.css`, `_print.css`, `components/*`)
+   - Defines the article's visual identity (typography, grid, components)
    - Uses CSS custom properties (`--text-color`, `--surface-bg`, `--primary-color`, etc.)
+   - Layout tokens centralize grid math (`--layout-toc-width`, `--layout-content-width`, `--layout-gap`, breakpoints)
    - Shared between the editor preview and the published output
 
-2. **Editor chrome CSS** (`_ui.css`)
-   - Styles the editor UI: toolbars, sidebars, dialogs, forms
+2. **Editor chrome** (`_ui.css`)
+   - Styles the editor UI: top-bar, sidebars, dialogs, chat panel, embed studio
    - Uses `--ed-*` custom properties for the dark editor theme
    - Only loaded in the editor, never in published output
 
-3. **Publisher CSS** (`_publisher.css`)
+3. **Design tokens** (`tokens.css`)
+   - Light/dark theming tokens for both editor and article
+   - Text, background, border, accent, code highlighting, danger, shadows
+   - Supports `data-theme` attribute and `prefers-color-scheme` media query
+   - Shared between editor and published output (injected by publisher)
+
+4. **Shared article styles** (`article.css`, `toc.css`)
+   - Article content styles shared between editor preview and published output
+   - `article.css` includes wrapper components (Note, Stack, Quote, Sidenote...), with editor-specific variants scoped by `.editor-app`
+
+5. **Editor-only styles** (`styles/editor/*.css`, 5 files)
+   - `_layout.css`: grid overrides (3-col symmetric, aligned with template), TOC drawer, responsive breakpoints (1100px collapse, 768px mobile)
+   - `_chrome.css`: ProseMirror editing visuals (placeholder, selection, cursors, comment marks, math editing)
+   - `_block-tools.css`: block handles (drag + add) and slash menu
+   - `_panels.css`: image upload card, footnote tooltip, citation panel
+   - `_hero-editable.css`: transparent click-to-edit inputs for FrontmatterHero
+
+6. **Publisher CSS** (`_publisher.css`)
    - Styles specific to the published static HTML page
-   - Footer layout, bibliography, footnotes, citation links, theme toggle
-   - Only injected by the HTML renderer, never loaded in the editor
+   - Theme toggle animations, wide/fullWidth breakout, sidenote float, lightbox, PDF link
+   - Only injected by the HTML renderer (backend), never loaded in the editor
 
 ### No CSS-in-JS
 
@@ -139,9 +159,15 @@ The `postProcess()` function uses `linkedom` for DOM manipulation instead of reg
 
 `GET /api/preview/:docName` renders the HTML without saving or uploading. Useful for testing the publisher pipeline.
 
+## Auth and security
+
+- AI chat routes (`/api/chat`, `/api/embed-chat`) are auth-guarded when OAuth is enabled
+- The `requireEditor` middleware checks cookie token and verifies write access
+- Published articles are served without auth (public)
+
 ## Testing
 
-Tests use Vitest. Run with `npm test` from `backend/`.
+Tests use Vitest + Supertest. Run with `npm test` from `backend/`.
 
 | Test file | What it covers |
 |-----------|----------------|
@@ -152,3 +178,5 @@ Tests use Vitest. Run with `npm test` from `backend/`.
 | `tests/utils.test.ts` | Path sanitization utilities |
 | `tests/auth.test.ts` | Token extraction, OAuth configuration |
 | `tests/hf-storage.test.ts` | HF dataset storage configuration |
+| `tests/persistence.test.ts` | Local file persistence, debounced save |
+| `tests/api-routes.test.ts` | API route integration tests (publish, auth status) |

docs/SPECIFICATION.md

@@ -4,7 +4,7 @@
 
 A collaborative, real-time scientific article editor deployed as a Hugging Face Space. Users write rich content (math, citations, custom components) in a TipTap-based editor synced via Yjs/Hocuspocus, then publish a self-contained static HTML article. An AI assistant helps with writing and editing.
 
-**Stack**: React 18 + MUI 9 + TipTap 3 + Yjs (frontend) / Express + Hocuspocus + Node 20 (backend) / Docker on HF Spaces.
+**Stack**: React 18 + TipTap 3 + Yjs (frontend) / Express + Hocuspocus + Node 20 (backend) / Docker on HF Spaces. No CSS-in-JS - all styling via vanilla CSS custom properties.
 
 **Relationship to `research-article-template`**: the CSS foundation, design tokens, and visual language come from the [research-article-template](https://huggingface.co/spaces/tfrere/research-article-template) project. The editor imports the template's CSS files (`_variables.css`, `_reset.css`, `_base.css`, `_layout.css`, component partials) and the publisher injects them inline into published HTML. The published output is designed to look identical to articles built with the Astro-based template.
 
@@ -152,7 +152,7 @@ flowchart LR
 ### 5.1 App Shell
 
 - **No router** - single view with conditional rendering
-- **Theme**: MUI `ThemeProvider` with dynamic primary color from `settings.primaryHue` (OKLCH color model)
+- **Theme**: CSS custom properties with dynamic primary color from `settings.primaryHue` (OKLCH color model, synced via Yjs settings)
 - **Layout**: top bar (undo/redo, settings, publish, user chip) + 3-column CSS grid (TOC / editor / comments)
 - **Chat**: floating button bottom-left, `ChatPanel` overlay
 - **Modals**: comment dialog, settings drawer, publish confirmation
@@ -198,7 +198,7 @@ Registry-based system for MDX-like custom components:
 | `rawHtml` | atomic | Raw HTML injection |
 | `mermaid` | atomic | Mermaid diagram (live preview) |
 
-- **Factory**: `createWrapperExtension(def)` / `createAtomicExtension(def)` generate TipTap nodes from registry definitions
+- **Factory**: `createComponentExtension(def)` generates TipTap nodes from registry definitions (handles both wrapper and atomic kinds)
 - **NodeViews**: `WrapperView` (editable content area + chrome), `AtomicView` (placeholder + field editor), `MermaidView` (textarea + SVG preview)
 - **Slash menu integration**: each component generates a slash menu item via `getComponentSlashItems()`
 
@@ -214,7 +214,7 @@ Registry-based system for MDX-like custom components:
 
 - **`TableOfContents`**: extracts headings from TipTap doc, scroll-based active state, collapsible sub-sections
 - **`ChatPanel`**: message list + quick actions on selection + input with streaming
-- **`CommentsSidebar`**: positioned comment threads with resolve/delete
+- **`CommentPopover`**: positioned comment popover anchored to the active thread (resolve/delete inline)
 - **`BubbleToolbar`**: floating toolbar on text selection (bold, italic, link, comment, etc.)
 - **`BlockHandle`**: drag handle for block-level nodes
 
@@ -222,25 +222,30 @@ Registry-based system for MDX-like custom components:
 
 ```
 styles/
-  _variables.css       # Design tokens, --primary-color, breakpoints, @custom-media
-  _reset.css           # Scoped reset (avoids MUI conflicts)
+  _variables.css       # Template tokens: --primary-color, breakpoints, @custom-media
+  _reset.css           # Scoped reset for article content
   _base.css            # Typography, scoped to article content
   _layout.css          # 3-column grid, .wide/.full-width helpers
   _print.css           # Print styles
-  _editor-tokens.css   # Editor-specific tokens (accents, syntax)
-  article.css          # .tiptap content styles (shared editor/published concept)
+  _ui.css              # Editor chrome: buttons, dialogs, drawers, spinner
+  tokens.css           # Design tokens (light/dark): text, bg, accent, code, danger, shadows
+  article.css          # .tiptap content styles (shared editor/published)
   toc.css              # Editor TOC overrides
   editing.css          # Editor-only: layout, cursors, slash menu
+  _publisher.css       # Published-only: theme toggle, wide/fullWidth, footer, lightbox
   components/
     _code.css          # Code blocks + syntax highlighting
     _table.css         # Tables
     _tag.css           # Tags
     _card.css          # Cards
     _mermaid.css       # Mermaid diagrams
+    _embed.css         # Embed containers
+    _embed-studio.css  # Embed studio overlay
     _hero.css          # Hero section (from template)
     _toc.css           # Base TOC styles (from template)
-    _button.css        # NOT imported in editor (MUI conflict)
-    _form.css          # NOT imported in editor (MUI conflict)
+    _button.css        # Buttons (template)
+    _form.css          # Form elements (template)
+    _footer.css        # Footer (template)
 ```
 
 The publisher reads these same CSS files server-side and injects them inline into published HTML, using `resolveCustomMedia()` to expand `@custom-media` queries into standard `@media` rules.
@@ -389,7 +394,7 @@ sequenceDiagram
 
 ## 8. Current Limitations and Known Issues
 
-- **No test suite**: zero tests across backend and frontend
+- **Test suite in progress**: P0 tests being added (see `docs/TESTS.md`)
 - **Single document**: only `"default"` document supported; no multi-doc
 - **Single-user token**: last OAuth token cached globally for all HF API calls
 - **No rate limiting** on `/api/chat` or `/api/citations/*`