Epinium Docs — CLAUDE.md

Documentation site built with VitePress 1.x. Source files live under apps/docs/.

Structure

apps/docs/
├── es/          ← Spanish (reference locale, served at root / via rewrites)
├── en/          ← English
├── fr/          ← French
├── it/          ← Italian
├── de/          ← German
├── public/      ← Static assets (favicon, images)
├── scripts/     ← Maintenance scripts
└── .vitepress/
    ├── config.mts          ← Main VitePress config (locales, rewrites, theme)
    ├── locales/            ← Per-locale nav & sidebar configs (es.ts, en.ts, …)
    └── theme/              ← Custom theme: index.ts + custom.css (Epinium brand)

The rewrites: { 'es/:path*': ':path*' } in config.mts makes Spanish URLs appear at root (/catalog/ not /es/catalog/) while files live in es/.

Content consistency — MANDATORY

es/ is the reference locale and the single source of truth for all content. Every page must be kept in sync across all 5 locales. The rule is simple:

Any change to one locale must be applied to all other locales in the same operation.

Rules

1. ES is the master — make changes to es/ first, then propagate to en/, fr/, it/, de/.
2. Same file structure — every file in es/ must have an exact counterpart in every other locale folder.
3. Same page structure — sections (headings), their order, and the number of content items (table rows, list items, etc.) must be identical across locales. Only the language differs.
4. Same nav/sidebar — when a page is added, renamed, or removed, update all 5 locale configs in .vitepress/locales/.
5. Never edit just one locale — if you only have time or context for one, do them all before finishing the task.

When adding or removing a page

1. Add the file to es/ first.
2. Replicate the same file path to all other locales with translated content.
3. Update all nav/sidebar configs in .vitepress/locales/<lang>.ts.
4. Run the file check to verify no locale is missing a file:

pnpm check-translations

When editing content on an existing page

1. Make the change in es/ first.
2. Apply the equivalent change to the same file in en/, fr/, it/, de/.
   • Same sections added/removed
   • Same table rows added/removed
   • Same list items added/removed
3. Run the structure check to verify all locales are consistent:

node scripts/check-consistency.mjs              # all files
node scripts/check-consistency.mjs amazon/      # only amazon/ files

Locale links

Each locale uses its own prefix in internal links:

Locale	Link prefix example
es	/catalog/
en	/en/catalog/
fr	/fr/catalog/
it	/it/catalog/
de	/de/catalog/

Spanish (root locale) uses bare paths thanks to the rewrites config.

Adding a new locale

1. Create <lang>/ folder with all pages translated.
2. Create .vitepress/locales/<lang>.ts exporting <lang>Nav and <lang>Sidebar.
3. Add the locale to config.mts under locales:.
4. Add the locale to the LOCALES array in scripts/check-translations.mjs.

Dev & build commands

# From apps/docs/
pnpm dev            # dev server on :8084 (accessible via epinium-front proxy at /docs/)
pnpm build          # production build → dist/
pnpm preview        # preview built site on :8085
pnpm check-translations              # verify all locales have the same files
node scripts/check-consistency.mjs  # verify content structure matches across all locales

VitePress config — key settings

• base: '/' — served at root
• rewrites: { 'es/:path*': ':path*' } — Spanish at root URLs
• cleanUrls: true — no .html extensions
• lastUpdated: true — last-modified metadata
• sitemap: { hostname: 'https://help.epinium.com' } — auto-generates sitemap.xml
• transformHead — injects <link rel="alternate" hreflang> for all 5 locales + x-default on every page
• transformPageData — injects og:title, og:description, og:url and <link rel="canonical"> on every page
• Theme colors defined in .vitepress/theme/custom.css (Epinium purple gradient)

Mermaid diagrams — vitepress-mermaid-preview

Mermaid diagrams are enabled via the vitepress-mermaid-preview plugin.

MANDATORY: Always include showToolbar: true via frontmatter inside every mermaid code fence:

```mermaid
---
showToolbar: true
---
flowchart TD
  A --> B
```

This enables the interactive toolbar (zoom, pan, copy, download) on every diagram. Never omit the showToolbar: true frontmatter when writing or editing mermaid diagrams in this docs site.

When documenting flows, processes, architectures, sequences, or any concept that benefits from a visual representation, proactively include a mermaid diagram to complement the text. Always use showToolbar: true.

Real app links — MANDATORY

The SaaS application lives at https://app.epinium.com. Every documentation page that references a section of the app must include a real clickable link so the reader can jump directly to the feature.

Where to add links

1. "Acceso desde" / "Access from" lines — the access line below each page title must link to the real app URL.
2. Step-by-step instructions — any "Ir a …" / "Go to …" step must wrap the destination in a link.
3. First meaningful mention — when a section name (e.g., "dashboard") first appears in prose, it may link to the app.

Route map (epinium-front → app URL)

The frontend app (apps/epinium-front/) defines these routes. Use them as the canonical path after https://app.epinium.com:

App section	Route	Example link
Dashboard	/dashboard	[Dashboard](https://app.epinium.com/dashboard)
VelaxAI	/chatbot	[VelaxAI](https://app.epinium.com/chatbot)
Workflows	/processes/workflows	[Procesos → Workflows](https://app.epinium.com/processes/workflows)
Workflow detail	/processes/workflows/:id	—
Tasks	/processes/tasks	[Procesos → Tareas](https://app.epinium.com/processes/tasks)
Products catalog	/catalog/products	[Catálogo → Productos](https://app.epinium.com/catalog/products)
Bulk changes history	/catalog/history-massive-changes	[Catálogo → Historial](https://app.epinium.com/catalog/history-massive-changes)
Clusters / Segmentation	/segmentations/clusters	[Segmentaciones → Clusters](https://app.epinium.com/segmentations/clusters)
AI Campaigns	/advertising/ai-campaigns	[Publicidad → AI Campaigns](https://app.epinium.com/advertising/ai-campaigns)
Campaigns list	/advertising/campaigns	—
Forecast / Logistics	/forecast/logistics	[Forecast → Logística](https://app.epinium.com/forecast/logistics)
Connections	/settings/connections	[Configuración → Conexiones](https://app.epinium.com/settings/connections)
Users	/settings/users	[Configuración → Usuarios](https://app.epinium.com/settings/users)
Agents	/settings/agents	[Configuración → Agentes](https://app.epinium.com/settings/agents)
Brand	/settings/brand	[Configuración → Marca](https://app.epinium.com/settings/brand)
Prompts	/settings/prompts	[Configuración → Prompts](https://app.epinium.com/settings/prompts)
AI Instructions	/settings/ai-instructions	[Configuración → Instrucciones IA](https://app.epinium.com/settings/ai-instructions)
Custom Data	/settings/personalized-data	[Configuración → Datos personalizados](https://app.epinium.com/settings/personalized-data)
Import / Export	/settings/import-export	[Configuración → Exportar](https://app.epinium.com/settings/import-export)
Billing / Subscription	/settings/billing/subscription	[Configuración → Facturación](https://app.epinium.com/settings/billing/subscription)
Credits	/settings/billing/credits	—
Invoices	/settings/billing/invoices	—

Format

**Acceso desde**: [Procesos → Workflows](https://app.epinium.com/processes/workflows)

The link text uses the localized menu path; the URL is always the same app.epinium.com route regardless of locale.