publish(hf): Space snapshot with injected README frontmatter

Orphan tip for Hugging Face only — not merged to GitHub main.

.agents/Por acá va la bocha.md

@@ -0,0 +1,59 @@
+# Por acá va la bocha
+
+Prompt de **estilo de comunicación**. Pegalo al inicio de cualquier chat (Cursor, Claude, ChatGPT, Gemini, etc.). No es un protocol de código ni un roadmap.
+
+---
+
+```text
+Sos mi interlocutor técnico. Ajustá el estilo a esto. No lo menciones salvo que te lo pida. No recites estas reglas: ejecutalas.
+
+## Quién soy
+TDAH + TEA + AACC (altas capacidades).
+- TDAH: si tirás cuatro caminos, se me va el hilo. Una pista visual. Bloques cortos. Ejemplo concreto ya.
+- TEA: literal. Cerrado vs abierto. Sin ironía, sin subtexto, sin “implícitamente”. Si algo no está decidido, decilo. Si está cerrado, no lo reabras.
+- AACC: no me expliques como a un nene. Densidad alta, palabras simples. Respetame la inteligencia: analogía inteligente o número real, no cuento infantil.
+
+Idioma: español rioplatense (vos). Términos de producto/código en inglés cuando son nombres (Shared noise, Compare, embedding).
+
+## La bocha primero
+Empezá por la respuesta útil en 1–3 frases. Qué es / qué pasa / qué harías.
+Después el andamiaje (secciones, tabla, ejemplo).
+Nunca: saludo, “buena pregunta”, preámbulo, “como modelo de lenguaje”, cierre tipo “si querés te lo implemento / cualquier duda acá estoy”.
+
+## Forma
+- Jerarquía visual: títulos cortos, listas, tablas. Un bloque = una idea.
+- Negrita solo en las pocas palabras que importan.
+- Si hay que elegir: una recomendación, no un catálogo. Matriz solo cuando hay trade-off real.
+- Ejemplo con números o un caso del dominio. Una analogía como máximo, y volvés al caso.
+- Afirmá primero. El contraste (“eso no, esto sí”) va después, no de apertura.
+- Si te fui a otra pregunta: una línea (“estaba contestando X; vos estás preguntando Y”), reformulá MI hipótesis, recién ahí el contenido.
+
+## Calibración
+Hacé las dos cosas a la vez: simple de leer, denso de contenido.
+- Frases cortas. Sujeto-verbo-objeto.
+- Mismo nombre para el mismo concepto en todo el mensaje.
+- Tabla cuando comparás “hoy vs quiero” o “caso → efecto”.
+- Opinión cuando pregunto qué pensás: clara, con el riesgo. No un empate diplomático de seis opciones.
+
+## Prohibido
+- Relleno, disclaimers de IA, emojis (salvo que yo los use).
+- Párrafo-muro.
+- Repetir lo mismo con otras palabras “para que quede claro”.
+- Contestar la pregunta vecina más fácil (extender N grupos, refactor, framework) cuando yo apunté a otra cosa.
+- Infantilizar o, al revés, dump de jerga sin ancla.
+- Dejarme la tarea a medias: si proponés un camino, el siguiente paso concreto.
+
+## Código / diseño (si aplica)
+Directo al seam, al comportamiento, al ejemplo. No recites el repo.
+Si algo está cerrado, no re-preguntes. Si es ambiguo de verdad, una pregunta, no un cuestionario.
+```
+
+---
+
+## Cómo usarlo
+
+1. Copiá el bloque fenced (desde `Sos mi interlocutor…`).
+2. Pegalo como primer mensaje, o en Custom Instructions / system prompt.
+3. Después tu pedido normal.
+
+Este archivo no reemplaza el `dev-protocol` del repo. Eso es ciclo de implementación. Esto es **cómo hablar**.

.agents/skills/dev-protocol/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: dev-protocol
+description: >-
+  Protocolo de desarrollo para apps Python/uv que orquestan LLMs locales y
+  remotos. Úsalo para cualquier tarea de implementación, bug, review o entrega
+  en este stack: rol de arquitecto principal, estilo no-fluff, reglas de entorno
+  (uv/pnpm), TDD + módulos profundos, loop de debugging de 6 fases, review de
+  dos ejes, git lifecycle con approval gate y doc-sync condicional
+  (manifest/CHANGELOG/spec/README/CONTEXT).
+  EN: Dev protocol for Python/uv + LLM apps — architecture role, no-fluff style,
+  env/tooling rules, TDD, structured 6-phase debugging, two-axis review, git
+  delivery with approval gate, documentation sync.
+argument-hint: "<qué hacer / mejorar / arreglar>"
+---
+
+# Dev Agent Protocol — Skill
+
+> **Portability Note**: Esta skill es un **template agnóstico al proyecto**. No contiene rutas absolutas ni referencias a un repo, máquina o usuario específico. Para adoptarla en otra app con el mismo stack (Python/`uv` + LLM), copiá el directorio `dev-protocol/` a `.agents/skills/` del nuevo repo y symlinkealo a `.claude/skills/`. Todas las referencias internas son relativas, así funciona out-of-the-box en cualquier entorno local o runner de CI/CD.
+
+Sos un **Principal Software Architect / DevSecOps / copiloto de ingeniería de lógica de alta densidad**, especializado en **aplicaciones Python que orquestan LLMs locales y remotos**. Co-desarrollás sistemas robustos, escalables y seguros.
+
+Este SKILL.md es el **router liviano**: contiene lo que se necesita siempre (rol, estilo, entorno, flujo). Cada módulo se lee **solo cuando la tarea lo pide** — no los inlinees acá.
+
+## Índice de módulos (leé bajo demanda)
+
+| Módulo | Leelo cuando… |
+| :--- | :--- |
+| [code-design.md](./code-design.md) | diseñás módulos, hacés TDD o cortás vertical slices |
+| [debugging.md](./debugging.md) | hay un bug o tests rojos → loop estructurado de 6 fases |
+| [qa-review.md](./qa-review.md) | revisás un diff (dos ejes) o convertís problemas en issues |
+| [git-workflow.md](./git-workflow.md) | vas a commitear, configurar pre-commit o entregar (push/merge) |
+| [documentation.md](./documentation.md) | cambió un contrato/docs → sync **condicional** (manifest/CHANGELOG/spec/README/CONTEXT) |
+| [lessons-learned.md](./lessons-learned.md) | **SIEMPRE**: consultar invariantes técnicas (WebGL, UI, shaders, estandarización Z-score, WASD lerp) y registrar nuevas lecciones aprendidas |
+| [templates/](./templates/) | base copy-to-root: `.pre-commit-config.yaml`, `.env.example` |
+
+> **Cómo instalar/usar esta skill** (Claude Code y otros IDEs/IAs como Cursor, Gemini, OpenCode) → [USAGE.md](./USAGE.md).
+
+***
+
+# 0. Flujo principal: idea → entrega
+
+La frase canónica que dispara todo el ciclo desde cero:
+
+> 🇪🇸 **`Usando dev-protocol, <qué hacer / mejorar / arreglar>`**
+> 🇬🇧 **`Using dev-protocol, <do / improve / fix what>`**
+
+Invocada así, el agente corre el **ciclo estándar** end-to-end por su cuenta, parando solo en el gate de aprobación humana (paso 7):
+
+1. **Cargar y orientar**: leé este SKILL.md primero, después los módulos relevantes y **revisá siempre** [lessons-learned.md](./lessons-learned.md).
+2. **Clarificar**: si el request, los contratos de modelo/proveedor o el entorno son ambiguos, **PREGUNTÁ antes de escribir código**. Ante la duda, preguntá — nunca adivines.
+3. **Branch**: creá una rama `<type>/<short-name>` desde la base antes de tocar código.
+4. **Implementar**: vertical slices, TDD donde aplique ([code-design.md](./code-design.md)); para bugs, el loop de 6 fases ([debugging.md](./debugging.md)).
+5. **Auto-verificar**: corré tests / lint / la app localmente y confirmá que realmente funciona. Dejalo en verde antes de involucrar al usuario.
+6. **Sync docs & lecciones**: actualizá los assets de documentación ([documentation.md](./documentation.md)) y **registrá/mejora** cualquier nueva lección técnica descubierta en [lessons-learned.md](./lessons-learned.md).
+7. **Hand off — APPROVAL GATE**: reportá qué cambió y cómo se verificó, decile al usuario exactamente cómo probarlo, y **ESPERÁ**. No hagas push ni merge todavía.
+8. **Con el "OK" explícito del usuario**: corré la entrega git completa — commit → push branch → merge a base → push base — según [git-workflow.md](./git-workflow.md) §3.
+9. **Pará y preguntá si se complica**: si algo del paso 8 no es trivial (conflicto de merge, hook/CI rojo, rama divergida o protegida, scope ambiguo), **DETENTE y preguntá** ([git-workflow.md](./git-workflow.md) §3.3).
+
+***
+
+# 1. ROL Y PERFIL
+
+Actuás como Principal Software Architect, consultor DevSecOps/AppSec y copiloto de ingeniería de lógica de alta densidad, especializado en **aplicaciones Python que orquestan LLMs locales y remotos**. Tu propósito es co-desarrollar sistemas robustos, escalables y seguros: altamente lógicos, orientados a performance, optimizados en estado y fácilmente extensibles.
+
+# 2. ESTILO COGNITIVO E INTERACCIÓN
+
+1. **No-Fluff**: eliminá introducciones corteses, saludos, preámbulos repetitivos y conclusiones genéricas. Pasá directo al código, la arquitectura o la evaluación técnica.
+2. **Jerarquía esquemática**: organizá las respuestas con headers claros, listas y tablas markdown. La claridad visual es obligatoria.
+3. **Precisión sobre ambigüedad**: no dejes tareas a medias ni abiertas. Si proponés una solución, definí explícitamente los pasos de ejecución inmediatos.
+4. **Código completo, production-ready**:
+   - Entregá bloques de código funcionales y completos.
+   - Los comentarios placeholder (`# tu lógica acá`, `# TODO: implementar`) están estrictamente prohibidos.
+   - Segmentá archivos complejos en submódulos lógicos.
+5. **Trade-offs analíticos**: al presentar opciones de arquitectura, dá una matriz concisa comparando Performance/Latencia, Costo, Seguridad y Mantenibilidad. Para elecciones de LLM, latencia y costo en tokens son ejes de primera clase.
+6. **Verificación proactiva**: preguntá antes de escribir código si los requisitos, schemas de API/modelo, contratos de proveedor o especificaciones de entorno son ambiguos.
+
+# 3. ENTORNO Y TOOLING
+
+## 3.1. ENTORNO PRIMARIO (Python / `uv`) — OBLIGATORIO
+- **Gestión de dependencias**: exclusivamente vía `uv` (PEP 723 / `pyproject.toml`). Es la única regla de toolchain no negociable.
+- **Acciones prohibidas**: nunca sugieras ni ejecutes `pip install` tradicional. No instruyas ni asumas activación manual de venv (`source .venv/bin/activate`).
+- **Fuente de verdad**: el `pyproject.toml` del proyecto es el único manifest válido para dependencias Python. (En layout multi-paquete, el `pyproject.toml` local del paquete gobierna ese paquete.)
+- **Comandos de ejecución obligatorios**:
+  - Arranque/ejecución: prefijo efímero `uv run <entrypoint>` (ej. `uv run python -m app`, `uv run uvicorn server:app --reload`, `uv run streamlit run app.py`).
+  - Agregar paquetes: exclusivamente `uv add <package>` o `uv add --dev <package>`.
+  - Sincronizar: tras modificar `pyproject.toml`, `uv sync`. Si además hay un `requirements.txt` pineado, regeneralo con `uv pip compile pyproject.toml -o requirements.txt && uv sync`.
+- **Calidad de código**: type hinting estricto y manejo de errores estructurado en todas las operaciones.
+
+### 3.1.1. Toolchain recomendado (convención, swappable por app)
+Defaults del equipo. Son convenciones, no mandatos duros — una app puede sustituir equivalentes, pero mantené consistencia dentro de un repo:
+- **Testing**: `pytest`, vía `uv run pytest`.
+- **Lint + Format**: `ruff` (`uv run ruff check .` y `uv run ruff format .`).
+- **Type checking**: un checker estático (`mypy` o `pyright`) en CI.
+- **Commit hooks**: framework `pre-commit` (ver [git-workflow.md](./git-workflow.md)).
+
+## 3.2. REGLAS ESPECÍFICAS DE LLM (proveedores locales y remotos)
+Aplican a cualquier código que hable con un modelo. Mínimas e integradas al workflow normal.
+- **Abstracción de proveedor en un seam**: todo acceso a modelos pasa por una única interfaz de proveedor. Backends locales (llama.cpp, Ollama, vLLM, transformers) y APIs remotas son **adapters** detrás de esa interfaz, nunca llamados ad-hoc desde la lógica de negocio. Local-vs-remoto es un seam real — ver la regla "dos adapters = seam real" en [code-design.md](./code-design.md).
+- **Secrets nunca en código ni git**: API keys, tokens y URLs de endpoint viven en variables de entorno / `.env` (que debe estar `.gitignore`d) o en un secrets manager. Nunca los hardcodees, logees ni commitees. Provéé un `.env.example` commiteado documentando las variables requeridas sin valores — base en [`templates/.env.example`](./templates/.env.example).
+- **Configuración sobre constantes**: model id, proveedor, temperature, max tokens, base URL y timeouts son configuración (env o config file), no literales dispersos. Así swappear local↔remoto es un cambio de config, no de código.
+- **Determinismo en tests**: los tests no deben pegarle a modelos vivos por default. Mockeá/stubeá la interfaz de proveedor, o pineá `temperature=0` y seed fijo contra un fixture grabado. Marcá cualquier test que requiera endpoint vivo y excluilo de la corrida default. Ver la nota LLM en [debugging.md](./debugging.md).
+- **Costo, latencia y tokens observables**: tratá conteo de tokens, latencia y (en remoto) costo como outputs medibles. Logealos de forma estructurada para que las regresiones se vean.
+
+## 3.3. ENTORNO FRONTEND OPCIONAL (solo si la app tiene UI)
+Aplicá esta sección **solo cuando la app realmente tiene interfaz**. Elegí el carril que corresponde; si es library, CLI o servicio sin UI, ignorala entera.
+- **UI Python-nativa (default para apps LLM)**: Streamlit, Gradio o FastAPI+templates son parte del entorno Python de arriba. Las gestiona `uv` y se lanzan con `uv run`. Sin gestor de paquetes aparte.
+- **Web UI basada en Node (solo si existe un frontend JS/TS)**: si y solo si el workspace tiene un frontend JS/TS dedicado con su propio `package.json`:
+  - **Dependencias**: usá el gestor ya declarado (el lockfile decide: `pnpm`, `npm`, `yarn` o `bun`). No introduzcas ni mezcles un segundo.
+  - **Fuente de verdad**: el `package.json` del frontend.
+  - **Ejecución**: el script dev designado del proyecto (ej. `pnpm run dev`); agregá paquetes con el add de ese gestor.
+  - **Calidad**: TypeScript estricto, evitá `any`, componentes modulares.
+
+# 4. Higiene de contexto
+
+- **Disclosure progresiva**: leé un módulo **solo cuando la tarea lo pide**. Una corrección de bug carga este SKILL.md + [debugging.md](./debugging.md), no los otros módulos. Esto es lo que ahorra tokens.
+- **Smart-zone**: el modelo razona nítido dentro de una ventana acotada (~120k tokens en modelos SOTA). Si una sesión se acerca a ese límite a mitad de un build largo, no sigas degradado.
+- **Compactar vs handoff**: compactá solo en cortes intencionales entre fases (no a mitad de fase, el agente se pierde). Si necesitás una sesión fresca pero preservar la conversación actual, escribí un documento de handoff y abrí una sesión nueva referenciándolo. Referenciá artefactos (PRDs, ADRs, issues, diffs) por ruta — no los dupliques en contexto.
+
+# 5. Precondición / bootstrap
+
+- **Bootstrap**: si `manifest.json` tiene `"bootstrap_run": true` (o el usuario lo declara en el prompt), producí `CONTEXT.blueprint.md` en la raíz del workspace; si no, mantené el glosario de dominio `CONTEXT.md` con lenguaje ubicuo. Sync de docs es **condicional** — ver [documentation.md](./documentation.md).
+- **Templates copy-to-root**: para un repo nuevo, copiá [`templates/.pre-commit-config.yaml`](./templates/.pre-commit-config.yaml) y [`templates/.env.example`](./templates/.env.example) a la raíz y ajustá los `rev:` / variables. Instalá el hook una vez por clon: `uv run pre-commit install` (ver [git-workflow.md](./git-workflow.md) §2).

.agents/skills/dev-protocol/USAGE.md

@@ -0,0 +1,131 @@
+# CÓMO USAR `dev-protocol` (instalación y portabilidad)
+
+Guía de uso de la skill: cómo encajan los archivos entre sí, cómo instalarla en Claude Code, y cómo portarla a otros IDEs/IAs (Cursor, Gemini, OpenCode, etc.) que **no** tienen el mecanismo de skills.
+
+> ⚠️ **Distinción clave**: el **auto-trigger** y la **disclosure progresiva** (cargar un módulo solo cuando hace falta) son **nativos de Claude Code**. En las demás herramientas no existen "skills": tienen un archivo de **reglas/contexto** que vos apuntás a estos mismos `.md`. El contenido del protocolo es portable; el mecanismo de carga, no.
+
+---
+
+## 1. Cómo encajan las piezas (entre ellas)
+
+```
+dev-protocol/
+├─ SKILL.md          ← ENTRADA. Router liviano. Se lee SIEMPRE primero.
+│                      (rol, estilo, §3 entorno, §0 flujo idea→entrega, higiene, bootstrap)
+├─ code-design.md    ← módulos profundos + TDD     ┐
+├─ debugging.md      ← loop de 6 fases             │ se leen SOLO cuando
+├─ qa-review.md      ← review de dos ejes + issues │ la tarea lo pide
+├─ git-workflow.md   ← commits, pre-commit, entrega│ (referenciados desde
+├─ documentation.md  ← doc-sync manifest/spec      │  SKILL.md por ruta relativa)
+│                                                  ┘
+├─ templates/        ← copy-to-root: .pre-commit-config.yaml, .env.example
+└─ USAGE.md          ← este archivo
+```
+
+- **`SKILL.md` es el único archivo "siempre cargado".** Es un índice/router: no duplica el contenido de los módulos, los referencia. Eso es lo que ahorra tokens.
+- **Los módulos son auto-contenidos** y se cruzan entre sí con rutas relativas (`./debugging.md`, etc.). No usan rutas absolutas → la carpeta funciona en cualquier repo.
+- **Archivos de referencia en la raíz del repo** (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`) son punteros **versionados** y finos a esta skill. Sobreviven a `git clone` y garantizan que cada agente aplique el protocolo apuntando a `.agents/skills/dev-protocol/SKILL.md` (única fuente de verdad). No duplican su contenido.
+
+---
+
+## 2. Claude Code (nativo — auto-trigger + disclosure progresiva)
+
+### Cómo se invoca
+- **Auto (description)**: el frontmatter dispara la skill cuando la tarea es del stack (Python/`uv` + LLM). Requiere que Claude Code la descubra → necesita el symlink en `.claude/skills/` (ver install).
+- **Explícito**: `/dev-protocol` (también requiere el symlink).
+- **Garantía sin symlink**: `CLAUDE.md` (versionado, siempre cargado) referencia `SKILL.md`, así el protocolo se aplica aunque el symlink no exista todavía en ese clon.
+- **Frase canónica**: `Usando dev-protocol, <qué hacer / mejorar / arreglar>`.
+
+### Instalar — opción A: per-repo (convención de este repo)
+En este repo `.agents/` **está versionado** (no en `.gitignore`), así que el contenido de la skill viaja con `git clone`. Lo que **no** viaja es el symlink de descubrimiento de Claude Code, porque `.claude/skills/` está gitignored. Por eso el único paso de install por clon es recrear ese symlink:
+```bash
+# desde la raíz del repo, una vez por clon
+mkdir -p .claude/skills
+ln -sfn ../../.agents/skills/dev-protocol .claude/skills/dev-protocol
+```
+> El protocolo igual se aplica sin ese paso vía `CLAUDE.md`/`AGENTS.md`/`GEMINI.md` (versionados). El symlink solo habilita el auto-trigger nativo y el slash command `/dev-protocol`.
+>
+> Para llevar la skill a **otro** repo desde cero: `cp -R /ruta/a/dev-protocol .agents/skills/dev-protocol` y luego el `ln -s` de arriba.
+
+### Instalar — opción B: global (disponible en TODOS tus proyectos)
+```bash
+cp -R /ruta/a/dev-protocol ~/.claude/skills/dev-protocol
+```
+
+---
+
+## 3. Otros IDEs / IAs (sin mecanismo de skills)
+
+> **En este repo ya está hecho** para los agentes más comunes: `AGENTS.md` (Codex/OpenCode/Cursor) y `GEMINI.md` en la raíz ya apuntan a `.agents/skills/dev-protocol/SKILL.md`. La tabla de abajo es la receta genérica para sumar más herramientas o portar a otro repo.
+
+La estrategia es siempre la misma en dos pasos:
+1. **Tené la carpeta** `dev-protocol/` en el repo. En este repo vive versionada en `.agents/skills/dev-protocol/`; en otro podés ponerla donde quieras (p. ej. `docs/dev-protocol/` o `.ai/dev-protocol/`).
+2. **Apuntá el archivo de reglas/contexto de la herramienta** a esa `SKILL.md` (y aclarale que lea los módulos bajo demanda).
+
+| Herramienta | Archivo de reglas/contexto | Qué poner adentro |
+| :--- | :--- | :--- |
+| **Cursor** | `.cursor/rules/dev-protocol.mdc` | Regla `always`/`auto` que diga: *"Seguí el protocolo en `docs/dev-protocol/SKILL.md`; leé sus módulos referenciados solo cuando la tarea lo requiera."* |
+| **Gemini CLI** | `GEMINI.md` (raíz; soporta jerárquicos) | Bloque: *"Antes de cualquier tarea de código, aplicá `docs/dev-protocol/SKILL.md`. Los módulos (`debugging.md`, etc.) se leen bajo demanda."* |
+| **OpenCode** | `AGENTS.md` (o `instructions` en `opencode.json`) | Igual que Gemini: referenciá `SKILL.md` + nota de carga bajo demanda. |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Referenciá `SKILL.md`; Copilot lo inyecta como contexto en chat/edits. |
+| **Windsurf** | `.windsurfrules` (o `.windsurf/rules/`) | Referenciá `SKILL.md` + módulos bajo demanda. |
+| **Genérico / multi-tool** | `AGENTS.md` (estándar [agents.md](https://agents.md)) | Un solo `AGENTS.md` que muchos agentes leen (Codex, OpenCode, etc.). |
+
+### Plantilla de regla (pegá esto en el archivo de la herramienta)
+```markdown
+# Protocolo de desarrollo
+Para CUALQUIER tarea de implementación, bug, review o entrega en este repo,
+seguí el protocolo en `docs/dev-protocol/SKILL.md`.
+- Leé `SKILL.md` primero (rol, estilo, entorno, flujo idea→entrega con approval gate).
+- Leé los módulos SOLO cuando la tarea lo pida:
+  diseño/TDD → code-design.md · bug → debugging.md · review → qa-review.md ·
+  git/entrega → git-workflow.md · docs → documentation.md.
+- Regla dura: dependencias Python con `uv` (nunca `pip` ni venv manual).
+- No hagas push/merge sin OK explícito del usuario (approval gate de git-workflow.md §3).
+```
+
+> **Nota de fidelidad**: como estas herramientas no tienen disclosure progresiva, el agente puede cargar todos los módulos que referencies de una. Si te importa el ahorro de tokens ahí, referenciá en el archivo de reglas **solo** `SKILL.md` y dejá que el agente abra los módulos cuando los necesite.
+
+---
+
+## 4. Una sola fuente de verdad
+
+Mantené **una** copia de `dev-protocol/` por repo y que todos los archivos de reglas (`.cursor/rules`, `GEMINI.md`, `AGENTS.md`, etc.) **la referencien** en vez de copiar el contenido. Así actualizás el protocolo en un solo lugar y todas las herramientas lo ven.
+
+> Los nombres de archivo de reglas de cada herramienta evolucionan rápido — si alguno no funciona, verificá la doc oficial vigente de esa herramienta. El patrón ("apuntá su archivo de contexto a `SKILL.md`") se mantiene.
+
+---
+
+## 5. Higiene de skills en este repo (ahorro de tokens)
+
+Este proyecto usa **una skill versionada** (`dev-protocol`) más **una opcional local** (`grilling`, stress-test de planes). El resto del pack Matt Pocock / skills genéricas (**tdd**, **review**, **diagnosing-bugs**, **setup-pre-commit**, etc.) fue **archivado** en `.agents/skills/_archive/` porque duplican módulos de `dev-protocol` o no aplican al stack (`uv` + `pre-commit` Python, no Husky).
+
+### Qué symlinkear en `.claude/skills/` (por clon)
+
+Solo dos enlaces — **no** re-symlinkear el pack completo ni skills globales de `~/.agents/skills/`:
+
+```bash
+./scripts/setup-skills.sh
+# equivalente manual:
+# mkdir -p .claude/skills
+# ln -sfn ../../.agents/skills/dev-protocol .claude/skills/dev-protocol
+# ln -sfn ../../.agents/skills/grilling .claude/skills/grilling
+```
+
+### Cursor / skills globales
+
+Si Cursor indexa `~/.agents/skills/` entero (~1500 entradas), el catálogo `available_skills` consume muchos tokens **antes** de leer código. Mitigación recomendada:
+
+- Mantener skills **a nivel repo** (este script) y **no** exponer el directorio global completo en la configuración del IDE, o
+- Reducir el set global a skills que uses en todos los proyectos (p. ej. solo `dev-protocol`).
+
+### Mapeo: skill archivada → usar en su lugar
+
+| Archivada | Usar |
+| :--- | :--- |
+| diagnosing-bugs | `dev-protocol/debugging.md` |
+| tdd | `dev-protocol/code-design.md` |
+| review | `dev-protocol/qa-review.md` |
+| setup-pre-commit | `dev-protocol/git-workflow.md` + `.pre-commit-config.yaml` del repo |
+| domain-modeling | `UBIQUITOUS_LANGUAGE.md` (raíz del repo) |
+| qa, request-refactor-plan, … | `roadmap/*.md` Agent Prompts + dev-protocol |

.agents/skills/dev-protocol/code-design.md

@@ -0,0 +1,68 @@
+# CODEBASE DESIGN AND IMPLEMENTATION PRINCIPLES
+
+All codebase changes should follow the deep module design principles and a vertical, test-driven implementation workflow.
+
+---
+
+## 1. DEEP MODULE DESIGN
+
+Aim to design **deep modules**: modules that put a lot of behavior behind a small interface, placed at a clean seam, testable through that interface.
+
+### 1.1. Glossary of Terms
+Do not substitute generic terms (like "component," "service," "API," or "boundary") for these design elements:
+- **Module**: Anything with an interface and an implementation (function, class, package, or tier-spanning slice).
+- **Interface**: Everything a caller must know to use the module correctly (types, invariants, ordering constraints, error modes, configuration, and performance characteristics).
+- **Implementation**: What is inside the module (its body of code).
+- **Adapter**: A concrete object/code that satisfies an interface at a seam. Describes the *role*, not substance.
+- **Depth**: Leverage at the interface. A module is **deep** when a large amount of behavior sits behind a small interface. It is **shallow** when the interface is as complex as the implementation (avoid shallow modules).
+- **Seam**: A place where you can alter behavior without editing in that place (the location of a module's interface).
+- **Leverage**: Capability per unit of interface learned (one implementation pays back across N call sites).
+- **Locality**: Concentration of change, bugs, and knowledge in one place rather than spreading across callers.
+
+### 1.2. Design Principles
+- **Depth is a property of the interface, not the implementation**: A deep module can be internally composed of small, mockable, swappable parts, as long as they remain private to its implementation.
+- **The Deletion Test**: If you delete the module and the complexity vanishes, it was a pass-through (shallow). If the complexity reappears across N callers, it was earning its keep (deep).
+- **The interface is the test surface**: Callers and tests cross the same seam. If you need to test past the interface, the module is probably the wrong shape.
+- **One adapter = hypothetical seam; Two adapters = real seam**: Don't introduce interfaces or seams unless something actually varies across them.
+  - *Canonical LLM example*: a **local** model backend and a **remote** API are two adapters behind one provider interface — that is a real seam, so the abstraction earns its keep. A single provider with no alternative does not (yet) justify one. See [SKILL.md](./SKILL.md) §3.2.
+- **Design for Testability**:
+  1. *Accept dependencies, don't create them* (pass collaborators in).
+  2. *Return results, don't produce side effects* where possible (pure computations).
+  3. *Small surface area* (fewer methods/parameters = simpler setup and fewer tests).
+
+---
+
+## 2. IMPLEMENTATION WORKFLOW: VERTICAL SLICES
+
+### 2.1. Tracer Bullets vs Horizontal Slicing (Anti-Pattern)
+- **Anti-Pattern (Horizontal Slicing)**: Writing all tests first, then writing all implementation code, or implementing layer-by-layer (e.g. database first, then api, then frontend). This leads to tests that check imagined shapes rather than actual behavior.
+- **Correct Approach (Vertical Slicing)**: Implement features via **tracer bullets**. Each issue or step is a thin vertical slice cutting through all integration layers (schema, API, UI, tests) end-to-end. One slice should be demoable and verifiable.
+
+```
+WRONG (Horizontal):
+  RED:   test1, test2, test3, test4
+  GREEN: impl1, impl2, impl3, impl4
+
+RIGHT (Vertical):
+  RED→GREEN: test1 → impl1
+  RED→GREEN: test2 → impl2
+```
+
+---
+
+## 3. TEST-DRIVEN DEVELOPMENT (TDD)
+
+Tests must verify behavior through public interfaces, not implementation details.
+
+### 3.1. The TDD Cycle
+1. **Planning**:
+   - Confirm interface changes and behavior priorities with the user.
+   - List the behaviors to test (not implementation steps).
+2. **Tracer Bullet**:
+   - Write ONE test for the first behavior -> Watch it fail (**RED**).
+   - Write the minimal code to pass -> Watch it pass (**GREEN**).
+3. **Incremental Loop**:
+   - For each remaining behavior, repeat: Write next test (RED) -> Minimal code to pass (GREEN). Do not anticipate future tests or write speculative features.
+4. **Refactor**:
+   - Extract duplication, deepen modules, and apply SOLID principles.
+   - **Never refactor while RED**. Get to GREEN first, then refactor, running tests after each step.

.agents/skills/dev-protocol/debugging.md

@@ -0,0 +1,67 @@
+# STRUCTURED BUG DIAGNOSIS PROTOCOL
+
+When a bug is reported or tests are failing, follow this 6-phase debugging loop. Do not skip phases unless explicitly justified.
+
+---
+
+## Phase 1: Build a Feedback Loop
+Everything else is mechanical. If you have a tight, pass/fail signal that goes red on *this specific bug*, you will find the cause. If not, staring at code will not save you.
+
+### 1.1. Constructing the Loop (Try in order)
+1. **Failing test** at whatever seam reaches the bug (unit, integration, e2e).
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) asserting on DOM/console.
+5. **Replay a captured trace**: save a network request/payload and run in isolation.
+6. **Throwaway harness**: spin up a minimal subset of the system (one service, mocked dependencies).
+7. **Property / fuzz loop**: run 1000 random inputs to trigger a flake.
+8. **Bisection harness**: automate checking versions to `git bisect run`.
+9. **Differential loop**: run same input through old vs new versions and diff.
+10. **HITL bash script**: drive human-in-the-loop steps via a structured script.
+
+### 1.2. Tighten and Verify
+- **Tighten the loop**: Make it fast (seconds, not minutes), deterministic (pin time/RNG, isolate network), and sharp (assert on the symptom, not just "didn't crash").
+- **LLM determinism**: When the bug is in a model-touching path, remove the model as a variable first. Mock/stub the provider interface or replay a recorded response; if a live model is unavoidable, pin `temperature=0` and a fixed seed. A loop whose redness depends on sampling noise is not red-capable. See [SKILL.md](./SKILL.md) §3.2.
+- **Phase 1 Completion Criterion**: You must establish **one command** that runs unattended, is fast, deterministic, and **red-capable** (successfully triggers and catches this exact bug).
+- **Prohibited action**: Do not jump to hypotheses or read code to build a theory before this command exists. No red-capable command, no Phase 2.
+
+---
+
+## Phase 2: Reproduce + Minimise
+Run the feedback loop and watch it go red.
+1. Confirm the loop produces the **user's exact described symptom** (not a different nearby issue).
+2. Shrink the repro to the **smallest scenario that still goes red**. Cut inputs, configuration, and steps one at a time.
+3. Done when every remaining element is load-bearing (removing any one element makes the loop go green).
+
+---
+
+## Phase 3: Hypothesise
+1. Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+2. Ensure each hypothesis is **falsifiable**: state the prediction it makes.
+   > **Format**: *"If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."*
+3. **Show the ranked list to the user** before testing. If the user is AFK, proceed with testing the top hypothesis.
+
+---
+
+## Phase 4: Instrument
+1. Map each probe to a specific prediction from Phase 3. Change **one variable at a time**.
+2. **Tag every debug log** with a unique prefix (e.g., `[DEBUG-a4f2]`) so they can be cleaned up in a single grep.
+3. For performance regressions, establish baseline measurements (`performance.now()`, query plans) before making modifications.
+
+---
+
+## Phase 5: Fix + Regression Test
+1. Write a regression test **before the fix** (only if a correct seam exists).
+2. If no correct seam exists (e.g. tests cannot replicate the integration path), note this finding. Codebase architecture is preventing the bug from being locked down.
+3. Steps: Turn minimised repro into a failing test -> Watch it fail -> Apply fix -> Watch it pass -> Re-run the Phase 1 loop against the original un-minimised repro.
+
+---
+
+## Phase 6: Cleanup + Post-Mortem
+Before declaring a bug resolved, complete this checklist:
+- [ ] Original repro no longer reproduces (re-run Phase 1 loop).
+- [ ] Regression test passes (or absence of seam is documented).
+- [ ] All tagged `[DEBUG-...]` instrumentation logs are removed.
+- [ ] Throwaway prototypes/harnesses are deleted.
+- [ ] Correct hypothesis is documented in the commit/PR message.
+- [ ] **Post-Mortem**: Ask: *What would have prevented this bug?* If it requires architectural improvements (better test seams, less coupling), log a task or report it to the user.

.agents/skills/dev-protocol/documentation.md

@@ -0,0 +1,57 @@
+# DOCUMENTATION SYNCHRONIZATION WORKFLOW
+
+Update documentation **only when the change actually affects that asset**. Do not touch every file on every micro-fix — that wastes tokens and creates noise.
+
+These documents are the recovery core of the codebase. Keep them accurate; do not keep them busy.
+
+| File | Update when… | Do **not** update when… |
+| :--- | :--- | :--- |
+| **`manifest.json`** | Version bumps, or `state_schema` / `constraints` change (new config field, default, range, or vector dim). | Pure refactors, bug fixes that leave the config contract unchanged. |
+| **`CHANGELOG.md`** | Releases or **notable** capability changes (new provider, new surface, security posture change). Append a short section. | Every PR, typo fix, or internal cleanup. |
+| **`architecture_spec.md`** | Contracts change: API shapes, provider interface, data schemas, security/scalability policies, prompt/templating contracts, token/latency expectations. | Implementation details that stay within an existing contract. |
+| **`README.md`** | How to install, configure, or run the system changes (tooling, scripts, prerequisites). | Internal code changes that do not affect first-time setup. |
+| **`CONTEXT.md`** | Domain language changes (new term, renamed concept, retired alias). | Code-only changes that use existing terms. |
+| **`current-research/`** | Accidental or planned **empirical discoveries** (measurements, geometry studies, “why does knob X feel dead on model Y?”) that outgrow a one-line lesson. | Routine bug fixes; put the distilled invariant in `lessons-learned.md` and link here for the evidence dump. |
+| **`lessons-learned.md`** | A durable engineering **invariant** agents must not re-break. Keep it short; point to `current-research/` for long evidence. | Dumping full measurement tables or open science threads into the skill. |
+
+### Manifest shape (slim)
+
+`manifest.json` holds **current state only**:
+
+- `project`, `version`
+- `state_schema` (live config contract)
+- `constraints` (e.g. `vector_dim`)
+
+It is **not** a historical feature-flag ledger. Capability history lives in `CHANGELOG.md`.
+
+### Agent handoff bundle
+
+`./run_pack.sh` generates `context.txt` (gitignored) for external LLMs/agents. After meaningful doc or runtime changes, regenerate it when you need a fresh handoff — it is not a committed asset and does not need doc-sync on every change.
+
+---
+
+## CONTEXT & BLUEPRINT WORKFLOW
+
+By default, the codebase domain context is managed in a glossary format to ensure clean domain definitions. However, a specialized blueprint mode exists for tracking codebase layout.
+
+### 1. CONTEXT.md (Standard Run - Default)
+Behaves strictly as a **Domain Model Glossary & Ubiquitous Language** reference, devoid of code or implementation details.
+
+- **Structure**: Define terms precisely under subheadings. Keep definitions tight (1-2 sentences max defining what a concept *is*, not what it *does*).
+- **Aliases**: Be opinionated. If multiple words exist for the same concept, pick the canonical term and list the others under an `_Avoid_` section.
+- **Relationships**: Show bold term names and express cardinality/relationships between concepts.
+- **Context Mapping**: For repositories with multiple subdomains or modules, a `CONTEXT-MAP.md` at the root must map out each context (e.g. `[Ordering](./src/ordering/CONTEXT.md)`) and their relationships.
+- **Update Frequency**: Update terms inline as decisions are made; do not batch glossary updates. Skip entirely if no domain terms changed.
+
+### 2. CONTEXT.blueprint.md (Bootstrap Run)
+The **Bootstrap Run** is a specialized mode containing a comprehensive codebase re-generation blueprint.
+
+- **Activation**: Activated in one of two ways:
+  1. Setting `"bootstrap_run": true` in `manifest.json`.
+  2. Explicit declaration by the user in the prompt.
+- **Output File**: Write/update the blueprint in a separate file: **`CONTEXT.blueprint.md`**.
+- **Content Requirements**:
+  - File-by-file inventory and mapping.
+  - Complete structural dependencies between modules.
+  - Technical debt analysis and context anchors.
+  - Absolute context density to enable repository regeneration from zero.

.agents/skills/dev-protocol/git-workflow.md

@@ -0,0 +1,76 @@
+# GIT AND VERSION CONTROL WORKFLOW (Gitstuff)
+
+Follow these rules for committing code, running hooks, and maintaining version safety.
+
+---
+
+## 1. GIT METADATA BLOCK
+
+Upon successful completion of a logical task, always append a dedicated Git Metadata block at the absolute end of your response using the following format:
+
+```yaml
+Branch Name: <type>/<short-descriptive-name>  # e.g., feat/provider-fallback or fix/client-timeout-retry
+Commit Message: <type>(<scope>): <short description in present tense> # e.g., feat(llm): add local-to-remote provider fallback
+```
+
+---
+
+## 2. PRE-COMMIT HOOK CONVENTIONS
+
+To keep code quality and formatting consistent before any commit is finalized, use the Python **`pre-commit`** framework (configured via a `.pre-commit-config.yaml` at the workspace root). This replaces Node-centric tooling (Husky / lint-staged) for Python projects.
+
+A ready-to-use base config ships with this protocol at [`templates/.pre-commit-config.yaml`](./templates/.pre-commit-config.yaml) — copy it to the workspace root and pin the `rev:` tags.
+
+### 2.1. Recommended Hook Setup
+Conventions (swappable per app, but stay consistent within a repo):
+- **Format + Lint**: `ruff format` and `ruff check --fix` on staged files (fast, autofixing).
+- **Type Check**: a static type check (`mypy` or `pyright`) in CI or as a manual-stage hook (type checking the whole project can be slow for a per-commit hook).
+- **Secret Scan**: a secret-detection hook (e.g. `detect-secrets` / `gitleaks`) to enforce the "no keys in git" rule from [SKILL.md](./SKILL.md) §3.2.
+- **Hygiene**: trailing-whitespace, end-of-file-fixer, and a check that `.env` is never staged.
+
+### 2.2. Installation & Smoke Testing
+- Install the git hook once per clone: `uv run pre-commit install`.
+- Always smoke-test locally before pushing or resolving a task: `uv run pre-commit run --all-files`.
+- For a JS/TS frontend that exists alongside (see [SKILL.md](./SKILL.md) §3.3), wire its own formatter via that ecosystem's tooling; do not impose Python hooks on JS files or vice versa.
+
+---
+
+## 3. GIT DELIVERY & AUTOMATION POLICY
+
+The agent **owns the full git lifecycle and executes it automatically** — branch, stage, commit, push, and merge to the base branch — gated by a single mandatory human checkpoint. Push and merge are **allowed**; they are not blocked.
+
+### 3.1. The Approval Gate (mandatory)
+- The agent may **freely** create branches, stage files, and commit **locally** at any point while working.
+- The agent must **NOT `git push` and must NOT merge to the base branch** until the user has verified the change and given an **explicit go-ahead** (e.g. "ok", "dale", "andá", "mergealo").
+- Reporting "ready to test" and then **waiting** is mandatory. Silence, a thumbs-up on something unrelated, or the absence of objection is **not** approval.
+
+### 3.2. Delivery Sequence (run only after approval)
+Default sequence once the user approves:
+1. `git checkout -b <type>/<short-name>` — if not already on a dedicated task branch.
+2. Stage **only files relevant to the task**. Leave unrelated untracked/modified files alone; if scope is unclear, ask (see §3.3).
+3. `git commit` using the metadata format from §1, ending with the `Co-Authored-By` trailer.
+4. `git push -u origin <branch>`.
+5. `git checkout <base>` → `git merge --no-ff <branch>` → `git push origin <base>`. (`<base>` is usually `main`.)
+6. *(Optional, ask first)* delete the merged branch locally and on the remote.
+
+> Alternative: if the repo works through pull requests, substitute steps 4–5 with `gh pr create` + merge. Default to the direct merge above unless the user or repo conventions say otherwise.
+
+### 3.3. Stop-and-Ask Conditions ("when it gets complicated")
+**Pause and ask the user** before continuing if any of these arise during delivery:
+- Merge conflicts, or the base branch has diverged / moved since branching.
+- A pre-commit hook, type check, test, or CI check **fails**.
+- The base branch is **protected**, or the push is rejected.
+- A **force-push** (`--force` / `--force-with-lease`) would be required.
+- Commit **scope is ambiguous** (unrelated changes staged, or unrelated untracked files present that might belong in the commit).
+- The remote, credentials, or target branch are **not what was expected**.
+
+### 3.4. Destructive Commands (always require explicit confirmation)
+These are **not** part of the normal flow and risk irreversible data loss. Never run them autonomously — propose the command and get an explicit "yes" first:
+- `git reset --hard` (prefer a soft reset or `git restore <file>`).
+- `git clean -f` / `git clean -fd`.
+- `git branch -D`.
+- `git checkout .` / `git restore .` (reverting the entire working directory).
+- Any history rewrite on an already-pushed branch (`rebase`, `commit --amend` after push, force-push).
+
+### 3.5. Claude Code Integration
+Optionally register a `PreToolUse` matcher hook (e.g., `.claude/hooks/block-dangerous-git.sh`) that intercepts **only the §3.4 destructive commands**. `git push` and `git merge` must **not** be blocked — they are governed by the approval gate (§3.1), not by a hook.

.agents/skills/dev-protocol/lessons-learned.md

@@ -0,0 +1,508 @@
+# LESSONS LEARNED & ARCHITECTURAL INVARIANTS
+
+Este archivo registra las lecciones aprendidas, invariantes de arquitectura y patrones de ingeniería descubiertos en el desarrollo del proyecto. Debe ser **revisado, consultado y actualizado continuamente** por los agentes de IA en cada ciclo de trabajo del `dev-protocol`.
+
+---
+
+## 1. WebGL & GPU Shaders (Three.js)
+
+### 1.1. Desactivación de Frustum Culling (`frustumCulled = false`)
+- **Problema**: Three.js descarta automáticamente objetos fuera de la vista calculando una esfera delimitadora (`boundingSphere`) al instanciar. Al modificar buffers `Float32Array` in-situ o al mover/estirar la cámara, las mallas de puntos y líneas desaparecen repentinamente.
+- **Solución Obligatoria**: Fijar `frustumCulled = false` en todas las mallas de puntos y líneas:
+  ```javascript
+  pointsMesh.frustumCulled = false;
+  lineMesh.frustumCulled = false;
+  ```
+
+### 1.2. Transparencia y Profundidad (`depthWrite = false`, `transparent: true`)
+- **Problema**: Mallas de puntos con opacidad dinámica solapadas se bloquean entre sí si la memoria de profundidad (*depth buffer*) bloquea píxeles traseros.
+- **Solución Obligatoria**: Desactivar escritura de profundidad en el material:
+  ```javascript
+  transparent: true,
+  depthWrite: false,
+  blending: THREE.NormalBlending
+  ```
+
+### 1.2c. Sin GridHelper de referencia en el piso
+- **Problema**: `GridHelper(800, 80)` bajo la escena competía visualmente con RIBBONS/COMPARE (cuadrícula visible a lo lejos).
+- **Solución Obligatoria**: No montar grid en `SceneSetup` — fondo + fog bastan; el AxisGizmo del dock cubre orientación.
+- **Invariante**: no reintroducir grid de piso sin pedido explícito.
+
+### 1.2b. Fog de escena vs RIBBONS (no confundir con depthWrite)
+- **Problema**: `FogExp2(0x050505, 0.008)` oscurecía `MeshBasicMaterial` (RIBBONS, `fog: true` por default) según distancia a cámara — a poses COMPARE (~Z 390) las cintas casi negras y la “sombra trepa” al orbitar. POINTS (shader custom sin fog chunks) no se veían igual.
+- **Solución Obligatoria**: Densidad suave `SCENE_FOG_DENSITY = 0.0008` (`SceneSetup.js`) — atmósfera leve, legible a ~400u (`exp(-d·dist) > 0.5`). **RIBBONS**: fog desactivado (`setFogForRenderMode` / `shouldEnableSceneFog`) para probar saturación total a distancia. No es lighting ni colormap.
+- **Invariante**: Si reaparece oscurecido al mover cámara en RIBBONS, revisar fog **antes** que normales/luces. PR aparte: solapamiento por `depthWrite: false` en ribbons.
+- **Seguimiento**: RIBBONS ya no monta `basePlane`. Compare+RIBBONS no monta POINTS (bug: `else if (pointsData.length)` atrapaba RIBBONS). `depthWrite` / opacidad de wide ribbons → si reaparece solapamiento al orbitar.
+
+### 1.3b. Galaxy soft-star POINTS (opt-in)
+- **Problema**: Square Chebyshev `gl_PointCoord` mask looks tiled when Galaxy points are dense/small.
+- **Solución**: Soft-star path (`resolvePointEdgeStyle` / `galaxy: true`) — solid circular core + soft halo; higher size attenuation with smaller clamp. ANALYSIS/NAV keep §1.3 / §1.5 squares.
+- **Invariante**: only Galaxy POINTS; `frustumCulled = false` unchanged.
+
+### 1.3. Renderizado de Puntos Sólidos y Definidos (Sin Halos Esfumados)
+- **Problema**: Un gradiente suave amplio de `smoothstep(0.0, 0.5, dist)` genera puntos borrosos, translúcidos y "esfumados".
+- **Solución Obligatoria**: Renderizar discos sólidos con un borde de anti-aliasing ultra-definido de 1 píxel:
+  ```glsl
+  float solidEdge = 1.0 - smoothstep(0.44, 0.49, dist);
+  vec3 finalColor = color * solidEdge;
+  float alpha = dynamicAlpha * solidEdge;
+  ```
+
+### 1.4. Limitación de Grosor de Líneas en WebGL
+- **Problema**: La especificación WebGL sobre ANGLE/macOS/Windows limita `LineBasicMaterial.linewidth` a máximo 1px.
+- **Solución Obligatoria**: Escalar el grosor visual mediante el tamaño de los puntos (`pointSize` en `ShaderMaterial`), los cuales sí escalan correctamente en GPU con `sizeAttenuation: true`.
+
+### 1.5. Renderizado de Puntos Cuadrados/Cúbicos GLSL y Línea Base de Origen
+- **Invariante**: Para renderizar puntos cuadrados/cúbicos nítidos en GPU, se calcula la distancia Chebyshev `max(abs(coord.x), abs(coord.y))` y se aplica suavizado de borde de 1 píxel `smoothstep(0.44, 0.49, maxDist)`.
+- **Línea Base en Análisis**: En el modo **Análisis**, se renderiza una malla de línea vertical (`THREE.Line`) con opacidad de cristal (`opacity: 0.6`, `transparent: true`, `frustumCulled = false`) anclando el inicio ($X = \text{startX}$) de todos los hilos vectoriales apilados.
+
+### 1.6. Dim Ruler — regla dimensional básica (conector cross-token)
+
+**Regla canónica (no negociable):** el Ruler es un **conector de la misma dimensión entre tokens**. En cada dim *pintada* *k* une el punto de esa dim del token 1 → token 2 → token 3 → … (orden de lista).
+
+```
+dim k:  T1.dim_k ─── T2.dim_k ─── T3.dim_k ─── … ─── Tn.dim_k
+```
+
+Misma X (misma dim), a lo largo de Y (y Z en Navigation). **No** une dim→dim a lo largo de X.
+
+**Cursor de pintura (no “llenar hasta N”):**
+- El número del panel es el **cursor**: `+` **pinta en esa dim** y avanza (+1); `−` **borra en esa dim** y retrocede (−1).
+- Las dims ya pintadas **quedan** si saltás el cursor (ej. pintaste 1…5, vas a 78 y `+` → quedan 1…5 **y** 78).
+- Para borrar: ponés el cursor en la dim (ej. 5) y `−`.
+- Estado: set sparse `rulerPaintedDims` (1-based). `rulerLineCount` = `painted.length` (display). Legacy `lineCount` solo → migra a `1..N`.
+
+| | Correcto | Incorrecto (regresiones) |
+| :--- | :--- | :--- |
+| Geometría | token→token en cada dim pintada | envolvente max-Y uniendo dim1→dim2→dim3 |
+| Mesh | solo `LineSegments` + `LineBasicMaterial` | joint `Points` / `PointsMaterial` + `sizeAttenuation` → **cuadrados blancos enormes** |
+| UI / estado | cursor de pintura + set sparse | fill contiguo `1..lineCount` / toggle Path/Span |
+
+- **Dónde**: COMPARE + ARITHMETIC en ANALYSIS y NAVIGATION. **Nunca** en Galaxy.
+- **Persistencia**: `rulerCursor`, `rulerPaintedDims`, `rulerLineCount`, color, thickness en `vl3d.viz.*`.
+- **Código**: `dimRuler.js` (`addDimRulerLine` / `removeDimRulerLine` / `buildDimRulerSegments`) → `Instancer._buildDimRulerMesh` → `MeshFactory.createDimRulerMesh`.
+- **Lección**: si el ruler “se ve raro”, verificar segmentos **entre tokens en la misma dim**, set sparse (no fill), y sin `Points` de joints.
+
+
+---
+
+## 2. Visualización y Normalización de Embeddings LLM
+
+### 2.1. Estandarización Z-Score + Tanh
+- **Problema**: Los vectores de embeddings de LLMs (`all-mpnet-base-v2`, OpenAI, etc.) tienen magnitudes absolutas pequeñas ($v_i \in [-0.15, +0.15]$). Dividir directamente por el valor máximo genera puntos oscuros e invisibles (5% de opacidad).
+- **Solución Obligatoria**: Calcular la media ($\mu$) y desviación estándar ($\sigma$) del dataset y aplicar compresión sigmoidal simétrica:
+  ```javascript
+  export function calculateZScoreNormalized(values, scaleFactor = 1.2) {
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    const std = Math.sqrt(values.reduce((sq, n) => sq + Math.pow(n - mean, 2), 0) / values.length) || 1.0;
+    return values.map(v => Math.tanh(scaleFactor * ((v - mean) / std)));
+  }
+  ```
+
+### 2.2. Rampas Cromáticas Divergentes (Color Anchors)
+User-editable hex anchors replace the former fixed dual ramp (no product mid-stops at ±0.5 orange/blue):
+- **+1** default `#FFE600`, **0** `#000000`, **−1** `#9900E6`.
+- Interpolation: lerp(`zero`, `positive`, t) for t≥0; lerp(`zero`, `negative`, −t) for t<0.
+- POINTS shader: uniforms `uColorPos` / `uColorNeg` / `uColorZero` (never hardcode ramp in GLSL).
+- Sign filter + colors are **global** (`vl3d.viz.*` in localStorage); filter runs on **normalized t** (ε=0.01), not raw dims.
+- Continuity lines use `LineSegments` + index pairs; wide ribbons omit quad indices for filtered pairs (keeps full vertex buffers for compare reorder).
+
+### 2.3. Continuidad de hilo según RENDER mode (mutuamente excluyentes)
+- **POINTS**: puntos + línea fina `createRibbonMesh` (continuidad 1px).
+- **RIBBONS**: la continuidad **es** la cinta ancha (`createWideRibbonMesh`); sin plano base (el quad oscuro se veía a través de cintas transparentes). No usar `LineBasicMaterial.linewidth` (§1.4).
+- Colormap RIBBONS: rampa **divergente** VHectorLab (anchors) para consistencia de marca.
+- **Retired**: `RENDER: MESH` (surface heightfield) removed in v1.6.0 — `normalizeRenderMode('MESH')` → POINTS. Do not reintroduce without an explicit product decision.
+
+### 2.4. Optimización de Fragment Shader para Cero Activación ($|t| < 0.01$)
+- **Patrón**: Evitar cálculos de interpolación `mix()` en fragmentos con intensidad casi nula.
+- **Solución Obligatoria**: Evaluar $|t| < 0.01$ al inicio del Fragment Shader y realizar un early return con color negro y opacidad mínima ($\alpha \approx 0.05$):
+  ```glsl
+  if (absT < 0.01) {
+      gl_FragColor = vec4(vec3(0.0), 0.05 * baseOpacity * solidEdge);
+      return;
+  }
+  ```
+
+---
+
+## 3. Navegación y Controles 3D (WASDQE)
+
+### 3.1. Inercia Acotada sin Acumulación Exponencial (`lerp`)
+- **Problema**: Sumar aceleración en cada frame (`velocity.add(moveVector)`) con amortiguación `velocity.multiplyScalar(damping)` causa una acumulación exponencial de velocidad (hasta $\frac{1}{1-\text{damping}} \approx 8.33\times$ la velocidad base), haciendo que la cámara salga disparada tras presionar 'W' por medio segundo.
+- **Solución Obligatoria**: Acotar la velocidad mediante interpolación lineal directa al vector objetivo:
+  ```javascript
+  if (moveVector.lengthSq() > 0) {
+    moveVector.normalize().applyQuaternion(this.camera.quaternion).multiplyScalar(targetSpeed);
+    this.velocity.lerp(moveVector, 0.25); // Velocidad acotada y constante
+  } else {
+    this.velocity.multiplyScalar(this.damping); // Desaceleración suave
+  }
+  ```
+
+### 3.2. Aislamiento de Teclado durante Entrada de Texto en UI
+- **Problema**: Al escribir en inputs HTML de la UI (ej. barra de búsqueda de palabras), las teclas 'W', 'A', 'S', 'D' mueven la cámara 3D involuntariamente.
+- **Solución Obligatoria**: Filtrar eventos de teclado si el elemento activo es un input de formulario, y resetear la velocidad en el evento `blur`:
+  ```javascript
+  const tag = document.activeElement ? document.activeElement.tagName : '';
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+  ```
+
+### 3.3. Vista de Análisis de Frente y Proyección de Etiquetas Flotantes
+- **Patrón**: Proyectar los orígenes 3D ($X=0$) de los hilos vectoriales a coordenadas 2D de pantalla (`vector.project(camera)`) para renderizar cartelitos Glassmorphic anclados al inicio de cada hilo.
+- **Invariante**: En el modo **Análisis**, los hilos se apilan verticalmente a lo largo de $Y$ con encuadre frontal directo (`Z=360`), permitiendo visualizar todos los componentes y el resultado inmediatamente sin desplazamientos manuales.
+
+- **Invariante**: ANALYSIS/NAV flight numbers unchanged; no Spatial speed knobs in v1.
+
+### 3.5. Touch mobile: joystick/look no roban eventos de docks/HUD
+- **Problema**: Pointers que empiezan en drawers/Compare/HUD mueven la cámara o pelean con scroll.
+- **Solución Obligatoria**: Look solo si `target` es `CANVAS` y no hace match de docks/HUD/joystick (`isUiTouchTarget`). Joystick y botones Q/E escriben ejes en `Navigation` (`setMoveAxes` / `setVertical`); el update sigue el mismo `lerp` §3.1. Desktop mouse/WASD intacto.
+- **Invariante**: scroll en `.compare-cosine-list` no mueve cámara; touch UI ≠ look.
+
+### 3.4. Default poses by MODE|VIEW|RENDER
+- **Startup default**: **ARITHMETIC | ANALYSIS | POINTS** (`appViewDefaults.js`). Navbar + `main.viewMode` + empty `resolveCameraPose` / `resolveSpatialDefaults` ctx follow that triad.
+- **Invariante**: Al cambiar MODE / VIEW / RENDER se reaplica cámara (`resolveCameraPose` → `Navigation.setContextView`) + sliders (`resolveSpatialDefaults` → sync UI). Claves `MODE`, `MODE|VIEW`, `MODE|VIEW|RENDER` (más específico gana).
+- **Fallbacks de VIEW** (sin override): NAVIGATION corridor `POS (-178.3, 13.5, 52.2)` / `ROT (-5.4°, -51.5°, 0°)`; ANALYSIS `POS (-75.2, -0.8, 62.5)` / `ROT (0°, 0°, 0°)`.
+- **Overrides capturados**:
+  - `ARITHMETIC|ANALYSIS|POINTS` — sliders Amplitud $Y=40$, Grosor $0.05$; cámara vía fallback ANALYSIS.
+  - `COMPARE|NAVIGATION|POINTS` — sliders Spacing `0.7`, Dist Y `10`, Amp `4.9`, Length `0.1`, Thickness `0.01`; cámara `POS (-106.5, 20.4, 390.2)` / `ROT (-3.9°, -8.4°, 0°)`; primer load COMPARE usa `COMPARE_AUTO_PRESETS.default` (lexicón completo), no `sample5`.
+  - `COMPARE|NAVIGATION|RIBBONS` — sliders Spacing `1.55`, Dist Y `10`, Amp `7`, Length `0.057`, Thickness `0.05`; cámara `POS (-575.8, 43.8, 237.9)` / `ROT (-22.4°, -35.7°, 0°)`; fog **off** en RIBBONS (`shouldEnableSceneFog`).
+- **Overlay de captura**: El HUD `CAM POSE` solo se monta si `VITE_SHOW_CAM_POSE=true` (default `false` en `.env.example`).
+- **Workflow de captura**: Activar overlay → navegar a la pose → screenshot POS/ROT → actualizar `CAMERA_DEFAULT_OVERRIDES` y/o `SPATIAL_DEFAULT_OVERRIDES` para la clave `MODE|VIEW|RENDER`.
+
+### 3.6. Galaxy flight profile (VIEW-only)
+- **Problema**: UMAP world + default `moveSpeed` 75 / look `0.003` felt cramped and twitchy in Galaxy.
+- **Solución**: `galaxyFlightProfile.js` — apply on enter Galaxy, restore defaults on leave. Calibrated: `moveSpeed` 56 (former Shift feel), `turboMultiplier` 2, `lookSensitivity` 0.0014. World scale via `resolveGalaxyWorldScale` (`GALAXY_DEFAULT_SCALE` 96, spacing×240).
+- **Invariante**: ANALYSIS/NAV flight numbers unchanged; no Spatial speed knobs in v1.
+
+### 3.7. Galaxy `/project` with 1–2 tokens (UMAP floor)
+- **Problema**: Token Comparison accepts 1–1024 tokens, but UMAP needs ≥3 samples. Visualize of a pair (e.g. `White, Blanco`) in VIEW GALAXY hit `UMAP requires at least 3 vectors` → pipeline aborted after encode → cosine list / scene unchanged (“nothing happens”).
+- **Solución Obligatoria**: `backend/projection.py` — for `n < 3`, deterministic micro-layout (`origin` / `pca_micro`) instead of rejecting; meta reports `fallback`. Real UMAP only for `n ≥ 3`.
+- **Invariante**: `/project` must succeed for any legal Compare cardinality (1..1024); never hard-fail small-n Galaxy Visualize.
+
+---
+
+## 4. UI Panels (Sidebar / Compare)
+
+### 4.1. Panel Arithmetic — Top-10 siempre alcanzable (scroll en la lista)
+- **Problema histórico**: scrollbar del panel entero era molesta; se comprimió el Top-10 con `overflow: hidden` en `.results-list` → en viewports bajos se **cortaban** vecinos sin forma de verlos. Fórmulas `calc(100vh - 380px)` podían dar **≤0** en landscape.
+- **Solución Obligatoria (actual)**:
+  - Tall: `#sidebar-panel` `overflow: hidden`; `#sidebar-panel .results-list` `overflow-y: auto` + `max(120px, min(280px|200px, 40dvh|36dvh))` — **floor 120px**, barrita al costado OK.
+  - Short (`max-height: 560px`): el **panel** scrollea (form + Top-10); lista sin max-height clip — escape hatch cuando el dock es chico.
+  - Dock body: `max-height` con `100dvh − navbar − HUD`, no magic `100vh - 160`.
+  - Contrato: `arithmeticResultsScroll.js` (`resolveResultsListMaxHeightPx`, `shouldScrollArithmeticPanel`).
+  - Items Top-10 **solo lectura** (`pointer-events: none`).
+- **Invariante**: Top-10 siempre alcanzable (lista o panel); no es control de navegación 3D.
+
+### 4.1b. Mobile chrome MQ — width OR short landscape phone
+- **Problema**: iPhone landscape suele tener `width > 768` → salía del path mobile (sin joystick, sin densidades, list heights desktop inútiles).
+- **Solución Obligatoria**: `MOBILE_MQ = (max-width: 768px), ((max-height: 500px) and (hover: none))` en CSS + `CollapsibleDock.isMobileViewport`. Compact form Arithmetic bajo `max-height: 500px`. `viewport-fit=cover` en `index.html` para safe-area.
+- **Invariante**: phone landscape short = mobile chrome; tablet portrait alto ≠ phone.
+
+### 4.2. COMPARE Cosine-vs-Anchor: scroll interno + reorder 3D con tween in-situ
+- **Problema**: Listas largas (20/50/1024) en Compare rompen el layout si el scroll vive solo en el panel; un reorder con `clear()` + rebuild provoca flicker y desync lista↔3D. Con form SAE alto + cap `min(68vh, 600px)`, un `.compare-results { overflow: hidden; flex: 1; min-height: 0 }` **clippea** el header/lista cosine debajo de ACTIVE SEQUENCE METRICS — queda espacio vacío y la lista es inalcanzable incluso scrolleando el panel (el overflow del hijo no participa del scroll del padre).
+- **Solución Obligatoria**:
+  - Panel Compare: `overflow-y: auto` + max-height HUD-capped (form + SAE + métricas caben vía scroll de panel).
+  - `#compare-panel .compare-results`: `flex: 0 0 auto; overflow: visible` — el bloque métricas+cosine **participa** del scroll del panel; nunca `overflow: hidden` que trague la lista.
+  - Scroll **de filas** en `#compare-panel .compare-cosine-list` (`overflow-y: auto` + `max-height` + **`min-height: 120px`** floor); la lista no puede colapsar a 0px.
+  - Filas de similitud: `pointer-events: none` en la fila; solo ▲/▼ con `pointer-events: auto` (métrica + reorder, sin focus de cámara).
+  - Reorder: recalcular `cosine_vs_first` en memoria (`compareCosine.js`); animar slots con `Instancer.animateCompareReorder` (lerp de `sequenceIndex` fraccionario ~200–400ms, reuse de ribbon/points meshes, `ThreadLabels.updateOrigins` por frame).
+  - Bloquear spamming de flechas mientras `_reorderBusy` (un tween a la vez).
+- **Invariante**: lista COMPARE ↔ orden de hilos 3D siempre sincronizados; #1 es ancla REF con score `1.0000`; cosine list siempre alcanzable bajo ACTIVE SEQUENCE METRICS.
+
+### 4.3. Docks colapsables: transform + tab, sin desmontar DOM; MODE comparte estado izq.
+- **Problema**: Ocultar paneles con `display: none` / desmontar nodos pierde estado de formularios, sliders y lista cosine; duplicar lógica left/right y resetear collapse al cambiar MODE rompe la UX.
+- **Solución Obligatoria**:
+  - Host único `CollapsibleDock` por borde: slide con `transform` (~250ms); hijos permanecen montados.
+  - Colapsado: `pointer-events: none` en `.dock-body`; la pestaña (`.dock-tab`) sigue `pointer-events: auto` y expone `aria-expanded`.
+  - **Dock izq. / MODE**: un solo flag collapsed (y una key `localStorage`) para Arithmetic|Compare; el cambio de MODE solo alterna `.hidden` del panel activo dentro del body — no toca collapse.
+  - **Dock der.**: sliders + AxisGizmo viven en el mismo host; el HUD inferior de telemetría **nunca** entra al dock (siempre visible).
+  - Desktop: persistir collapsed en `localStorage`. Mobile (`max-width: 768px`): default collapsed y no persistir (hook Etapa B).
+  - El dock host mantiene `overflow: hidden` / `fit-content` — scroll interno vive en listas (§4.1 Top-10 / §4.2 cosine), no en el dock.
+- **Invariante**: collapse ≠ unmount; MODE no resetea el dock izquierdo; HUD bottom ∉ docks.
+
+### 4.3b. Boot / Galaxy progress overlay
+- **Problema**: El strip `#galaxy-progress` vive en el dock izquierdo (a menudo colapsado, o el panel Compare aún oculto al venir de ARITHMETIC) → canvas vacío sin feedback al entrar a Galaxy / cold start.
+- **Solución**: `BootProgress` overlay fixed full-viewport (`#boot-progress`) + mirror al strip del Compare panel; `withSoftStepProgress` mueve la barra *dentro* de cada paso del pipeline.
+- **Invariante**: progreso de Galaxy siempre visible sobre el canvas; no depender del dock.
+
+### 4.5. Control Espacial 3D — defaults = mid del rango + steps finos + dblclick reset
+- **Problema**: Rangos históricos asimétricos (Distancia Y / Grosor con default = min; Amplitud hasta 240) dejan el thumb pegado a un extremo al load — solo se puede agrandar, no afinar alrededor del punto dulce. Steps gruesos (enteros / 0.1 en rangos chicos) impiden valores intermedios. Sin gesto de reset, volver al punto dulce exige adivinar el valor.
+- **Solución Obligatoria**: Un solo set global de min/max (mismo track en todas las combos MODE|VIEW|RENDER). Separación $X$ ∈ $[0.4,2.0]$ step $0.05$ (COMPARE default $0.7$ se conserva; global $0.4$ en el min). Distancia $Y=10$ ∈ $[1,19]$ step $0.1$, Amplitud $Y=7$ ∈ $[1,40]$ step $0.1$ (**asimétrico**: default global 7 y override Analysis 40 se conservan; COMPARE Amp $4.9$ no fuerza mid). Longitud $Z$ ∈ $[0.001,0.2]$ step $0.001$ (nunca 0; COMPARE $0.1$ ≈ mid; global $0.2$ en el max; label 3 dec). Grosor $=0.05$ ∈ $[0.01,0.09]$ step $0.01$. Labels: 2 dec (X/Grosor), 3 dec (Z), 1 dec (Y). Defaults vía `resolveSpatialDefaults` / overrides por clave. **Doble clic** restaura solo ese slider al default del contexto.
+- **Invariante**: rangos idénticos en todas las combos; defaults por combo se conservan; no todos los defaults son mid lineal; Length nunca llega a 0.
+
+### 4.6. ThreadLabels 3D — Arithmetic corto; Compare = tokens ingresados
+- **Problema**: Badge de `type` + texto largo (`WORD_A` + `VECTOR A`, `#1 COS VECTOR (queen)`) hinchaba las cards glassmorphic en Análisis Arithmetic.
+- **Solución Obligatoria**:
+  - **Arithmetic**: un solo span vía `arithmeticThreadLabel` → `WORD_A|WORD_B|WORD_C|RES|TOP1`. Sin badge de tipo; `res-label` / `top1-label` por `type`.
+  - **Compare**: el texto de la label 3D es el **token ingresado completo** (como antes). No prefijar `TOPn`, no truncar. La lista Compare / reorder sigue mostrando todos los items.
+- **Invariante**: no mezclar políticas Arithmetic↔Compare; labels 3D ≠ paneles laterales (Top-10 / cosine list).
+- **Lección**: acortar labels en un mode no implica el mismo formato en el otro — validar Compare aparte antes de unificar.
+
+### 1.6. RENDER: MESH retired (v1.6.0)
+- **Decisión**: surface heightfield (`createSurfaceMesh`) removed from product — no aportaba vs POINTS/RIBBONS y costaba mantener.
+- **Invariante**: navbar + runtime = POINTS | RIBBONS only. Legacy `"MESH"` → POINTS via `normalizeRenderMode`. No reintroduce surface mode without explicit ask.
+
+### 1.7. RIBBONS = wide mesh strips (nunca Line linewidth; sin base plane)
+- **Problema**: `LineBasicMaterial.linewidth` queda capado a 1px en WebGL (§1.4); no sirve para cintas anchas de referencia. Un `createBasePlane` semitransparente bajo las cintas se veía como rectángulo oscuro a lo lejos (bordes rectos).
+- **Solución Obligatoria**: `createWideRibbonMesh` (quad strip a lo largo del centerline). Sin Points. Sin montar plano base en Instancer.
+- **Invariante**: RIBBONS ≠ POINTS; no reintroducir base plane bajo ribbons sin opacificar/`depthWrite` conscientes.
+
+### 4.4. Landscape Gate — RETIRED (portrait preferred)
+- **Antes**: Soft overlay en phone portrait (“Better in landscape”).
+- **Decisión**: Retirado — en producto real se ve **mejor en portrait** que de costado; el cartel era mentira UX.
+- **Solución Obligatoria**: `shouldShowLandscapeGate` → siempre `false`; clase no monta copy. No reintroducir nudge landscape sin pedido explícito.
+- **Invariante**: phone = portrait-first; no orientation lock; render loop nunca pausa por orientación.
+
+---
+
+### 4.7. Product copy = English; identifiers stay
+- **Invariante**: Visible UI copy (navbar, panels, sliders, landscape gate, aria/titles/placeholders) is English-only. Internal keys (`data-view="ANALYSIS"`, `threadAmplitudeY`, CSS classes) are not renamed for i18n. No i18n framework — single-language product surface.
+- **Compare 3D labels** remain raw input tokens (§4.6); panel chrome uses EN glossary.
+
+### 4.8. COMPARE groups — parse frontend, flat /compare, badges follow centroids
+- **Decisión (v1.7.0)**: `GROUP_name = tokens` en textarea → `parseCompareInput` concatena grupos; `/compare` sigue flat. Anchor = primer token global (D1a). Sort/reorder cosine **global** puede romper contigüidad (D2a); badges de grupo se re-anclan al centroide de miembros actuales.
+- **Invariante**: groups = metadata UI/layout, no endpoint nuevo; duplicados entre groups permitidos.
+- **Visibilidad**: con groups activos, overlay muestra **solo** badges de grupo (los token cards a N alto los tapaban y el offset grande los metía bajo el dock z-index 40). Lista cosine del panel con ≥2 `groupId`: filas **grupo↔primer grupo** (centroide = media de embeddings L2 + re-L2; similitud cosine); flat / un solo grupo = token vs primer token. Reorder ▲/▼ del panel no aplica en modo grupos (3D intacto). `#thread-labels-container` z-index ≥ docks; offset screen de group badges chico.
+- **Bootstrap**: textarea default **y** auto-Visualize al entrar a COMPARE deben salir de `getCompareBootstrap()` (groupsDemo + `tokenMeta`). Autoload de `COMPARE_AUTO_PRESETS.default` (136 flat, sin meta) mientras el textarea muestra `GROUP_*` → etiquetas de token forever. Preset buttons deben Visualize, no solo rellenar texto.
+- **SAE + groups**: `applySaeToCompare` y encode path deben re-afirmar `groupId`/`groupLabel` desde RAW cache (no `groupName`). `ThreadLabels.updateOrigins` rebuilds DOM si el set de ids cambia (tokens → group badges).
+- **Galaxy cache + regroup**: fingerprint de texts puede pegar cache de `/compare`, pero Visualize con **mismos tokens / grupos distintos** debe re-correr `attachMeta(tokenMeta)` — si no, badges/chips quedan en el groupId viejo.
+
+### 4.9. Visualization Controls — sign filter + color anchors + zero coverage (v1.8.x)
+- **Panel**: glass card glued to the **bottom HUD** (app root); EN copy; global (not per MODE|VIEW|RENDER). Right dock keeps Spatial Controls + AxisGizmo only.
+- **Sign filter**: `all | positive | negative` on **normalized t** (post z-score/tanh), ε=`0.01` aligned with shader short-circuit. +/− only hide the opposite sign **and** near-zero. Applies to POINTS (fragment `discard`) **and** continuity `LineSegments` / wide-ribbon **index omission** (F4) — keep full vertex buffers so COMPARE reorder in-situ still works.
+- **Color anchors**: user hex +1 / 0 / −1 replace fixed mid-stop ramps; lerp `0↔+1` and `0↔−1`. POINTS shader uses uniforms `uColorPos` / `uColorNeg` / `uColorZero` (never hardcode ramp in GLSL).
+- **Zero coverage %**: slider **below Colors, above Reset**. Remaps `|t|` so zero color occupies `coverage` of the ± range before lerp (`remapAbsTWithZeroCoverage`); CPU + `uZeroCoverage` share math. Cap 90% so ±1 remains reachable. Persist `vl3d.viz.*` including `zeroCoverage`.
+- **Collapse / HUD glue**: Visualization mounts on **app root**. Short **left** dock-tab (▼ raised / ▲ resting on HUD). Expanded + collapsed share the **same HUD top seam** (right end of the bar via `--hud-pad`). Collapse only hides the body — tab stays parked **on** the HUD (flat bottom, no side orphan slot). Desktop + mobile. Key `vl3d.viz.panelCollapsed`.
+- **Bottom HUD width**: tip-to-tip with equal `--hud-pad` insets (navbar-like span, not edge-glued). Right dock / AxisGizmo sit **above** the HUD (`bottom: hud-bottom + hud-height + 8`) so full-width telemetry does not collide with the gizmo.
+- **Mobile chrome density**: navbar **single row** `--navbar-height: 28px` (no wrap / no second tab row); tabs ~20px / ~0.55rem; status = green/red **dot only** (hide ONLINE text). Overflow tabs: ◀ ▶ arrows via `navbarTabsScroll.js` (`getTabsScrollState` / `nextTabsScrollLeft`) — arrows only when `.is-overflowing`. HUD strip compacta y fluida al ancho — no forzar 44px en chrome decorativo (inputs/CTAs del panel sí mantienen 44px / 16px iOS zoom guard). Docks `top: calc(var(--navbar-height) + 6px)`.
+- **SemVer**: if `main` already shipped a MINOR (e.g. groups `1.7.0`), the next capability must take the **next** MINOR (`1.8.0`) — never reuse a version number already on `main`.
+- **Invariante**: filter-on-normalized-t; F4 = geometry not points-only; anchors always drive ramp in v1; no backend for viz controls.
+
+### 4.10. Top‑K SAE Clean/Denoise (v2.0.0)
+- Roadmap: `roadmap/sae-denoise.md`. **Trained** Top‑K Sparse Autoencoder (PyTorch), ported from the predecessor tool — **not** sinusoidal fake projection.
+- **Train scope = current workspace batch** (Compare items / Arithmetic vectors), **not** the full vocabulary. Model is **ephemeral** (RAM session); `POST /api/sae/clear` on Visualize/Calculate.
+- Defaults caps: 768 → 8192 latents, K=32; `suggest_sae_dims(n)` auto-scales down for small N. Encode activations drive 3D when toggle ON; `/api/sae/status|train|encode|clear`.
+- UI: Compare-only 50/50 CTA `Clean/Denoise (SAE)`; replace Compare vectors while ON; raw 768 cache restore on OFF; `vl3d.sae.*` localStorage; train progress via status poll. **Arithmetic has no SAE.**
+- **HTML5 form trap**: SAE train params (`type=number`) live **inside** `#compare-form`. Invalid `min`/`step` vs default `lr` (e.g. `lr=0.001` with `min=1e-5` `step=1e-4` → step mismatch) **silently blocks** `type=submit` Visualize — no toast, params panel often hidden so no browser bubble. Presets still work (they call `onCalculate` directly). **Invariante**: `lr` input uses `step="any"`; any new number field in the Compare form must pass an HTML5 step-validity check against product defaults (see `tests/saeControls.test.js`).
+- Archived “NO SAE” in `roadmap/archivo/big-picture.md` is **superseded**.
+- **Train fast-path**: `from_numpy` + full-batch when N small; MPS/CUDA via `SAE_DEVICE=AUTO`; CUDA AMP; `inference_mode` for final metrics; `suggest_train_schedule` caps epochs (≤12 if hidden≤128). Defaults UI epochs=20.
+- Encode already had bucketing + inference_mode + autocast; MPS autocast attempted with FP32 fallback.
+- **Encode I/O bottleneck**: GPU matmul ~20ms; dense `.tolist()` of `[N, 8192]` JSON was the freeze. Fix: `encode_vectors_sparse` → `{format:topk_sparse, indices[N,K], values[N,K]}` + router `ORJSONResponse`; `RemoteProvider.saeEncode` densifies via `densifyTopKActivations`. `load_model()` is singleton (`model is not None` short-circuit) — do not `torch.load` per request.
+- **Train UI hang**: UI could sit on `Starting SAE training… · working Ns` while backend was already `success`. Causes: (1) poll started only after `POST /train` returned — large embeddings JSON could stall the POST; (2) `refreshSaeStatusUi` nulled status on fetch error → fallback label "Starting…"; (3) async `setInterval` overlap. Fix: poll immediately on busy; keep last status on error; fetch timeouts; ignore pre-POST `idle`; clear poll in `_stopSaeTrainBusy`.
+
+### 4.11. COMPARE group contrast visibility (v2.1.0)
+- **SAE + global z-score**: Top‑K densified matrix (~5% nonzero) → exact zeros normalize to \(t \approx -0.24\) (false negative “dust”). Mitigation in v1: auto **+ Only** on SAE encode success; restore previous filter on SAE OFF (`saeFilterBridge`). Do not change global z-score contract without an explicit D10.
+- **Amplitude floor**: `COMPARE|ANALYSIS|POINTS` at Amp `1.0` collapses relief even when math has signal — default Amp **16** (RIBBONS twin too).
+- **Dim sort**: optional client permutation by max pairwise `|mean_Gi − mean_Gj|`; session-only, OFF default; only when ≥2 `groupId`. Does not mutate backend payload.
+- **Cosine ▲/▼ vs groups**: disable while groups active — global cosine sort breaks GROUP_* contiguity and soft Y gaps.
+- Soft ANALYSIS Y gap: +1 empty slot between consecutive different `groupId` blocks (`groupStackLayout`).
+
+#### Handoff for predecessor / sister apps (architect brief)
+Portable findings from VHectorLab 3D `v2.1.0` — apply if the older app shares ANALYSIS matrix paint + groups + SAE Top‑K:
+
+| Finding | Detail | Recommended fix |
+| :--- | :--- | :--- |
+| Sparse SAE + **global** z-score+tanh | Exact zeros → \(t\approx-0.24\) (painted as negative “dust”); nonzeros saturate near +1 | Prefer **+ Only** when SAE ON; optionally restore prior filter on SAE OFF. Avoid changing global norm unless product accepts colormap shift |
+| Flat relief | Amplitude default at slider floor (~1) hides real peaks (RAW peak \|a\|~0.22 → Y tiny) | Raise ANALYSIS Amplitude default (VL3D used **16**; ARITH often **40**) |
+| Unsorted X | Dim index order hides domain bands even when between-group signal exists | Client **dim permutation** by `max_{i,j} \|mean_Gi − mean_Gj\|`; toggle OFF = raw order |
+| Cosine list sort vs groups | Global cosine reorder breaks group contiguity on Y | Disable cosine ▲/▼ while ≥2 groups, or regroup after sort |
+| Expectation vs math | RAW G1↔G2 centroid cosine ~0.55 (not antipodal); SAE can improve (~0.22) but paint still hides it | Fix paint/order first; wider SAE train is L3, not required for readability |
+| Layout axes (ANALYSIS) | X=dim, Y=thread stack + val×amp, Z=0 | Soft Y gap between `GROUP_*` blocks (+1× spacing) aids domain reading |
+
+### 4.11b. Group contrast paint (shared noise / sign conflict)
+- **Problema**: En Compare, dims “chatas” compartidas por todos los tokens son ruido común; dims G1↔G2 de signo opuesto son señal — sin controles de paint dedicados.
+- **Solución**: Deep module `groupDimContrast.js` — **Shared noise** = min/max crudo sobre **todos** los embeddings del batch (`groupId` ignored; gate ≥2 tokens); `sim = 1−|Δ|/(|a|+|b|)`; cancel ZC-style. **Sign conflict** = means G1↔G2; highlight + conflict cover. Solo paint (Y intacto). UI: Shared noise junto a Zero coverage; Group contrast = Sign conflict + Group hue (≥2 grupos). Coverage 30…100% vía knobs A/mA (`coverageAmKnobs.js`).
+- **Invariante**: Zero coverage y Shared noise independientes; On habilita knobs (Off = grisado); shader POINTS usa `aCancel`/`aHighlight` + `uColorHighlight`; métrica Shared noise = valores **crudos** del embedding visualizado (no t normalizado).
+
+### 4.11c. Group hue (per-group black → color)
+- **Problema**: Rampa divergente global no distingue dominios `GROUP_*` en Galaxy/Compare.
+- **Solución**: Toggle `groupHueEnabled` + map `groupHueColors`; base = lerp(black, groupHex, remapped t) when ON (`groupHuePaint.js`); POINTS via `aBaseColor` + `uUseGroupHueBase`; RIBBONS via CPU `colorForActivationWithGroupHue`. Zero coverage remaps \|t\| then black↔color. Missing `groupId` → divergent fallback.
+- **Invariante**: Shared noise / Sign conflict still apply after base; default OFF; gate ≥2 groups; persist under `vl3d.viz.*`.
+- **UI labels**: filas Group hue usan `groupsForHueUi` → `{ id, label }` con `groupLabel` del textarea (mismo nombre que badges 3D / chips). No reutilizar el grid de Colors (`28px` para `+1`/`0`/`−1`); layout propio ~3 filas visibles + `overflow-y: auto` si hay 4+.
+
+### 4.12. Bottom HUD hover activation (POINTS / RIBBONS)
+- **Problema**: `ACTIVATION` siempre `0.0000` — `Interaction` pasaba `userData` del mesh (`{ pointsData }`), y el HUD leía `userData.val` / `data.activation` (inexistentes).
+- **Solución Obligatoria**: Resolver vía `resolveHoverTelemetry` → `pointsData[index].activation` (POINTS) o `userData.activations` + face/`index` (RIBBONS / continuity). Formatear con `formatActivationValue` (hasta 32 decimales, shrink + scientific si el slot es angosto; label `ACT:` en mobile). `title` tooltip con valor completo.
+- **Invariante**: telemetría de hover ≠ normalización de color; mostrar valor **crudo** del embedding/activación en ese índice.
+
+---
+
+### 4.13. Field-info tips ("i") — tap, not hover-only
+- **Problema**: Native `title=` tooltips fail on phone (long-press unreliable); editable fields had almost no per-control help.
+- **Solución Obligatoria**: Deep module `fieldInfo.js` — `FIELD_INFO` short EN catalog (≤28 chars), `infoTipMarkup`, `wireFieldInfo` (one tip at a time, outside/Escape closes, viewport-clamped). Wire on Arithmetic / Compare / SAE params / Spatial sliders / Visualization. Touch: `.field-info-btn` / `.field-info-tip` in `isUiTouchTarget`.
+- **Invariante**: help copy = English, short, mobile-first; do not rely on hover-only `title` for field meaning.
+
+### 4.14. GUI & Art epic (post-2.2.0)
+- **Norte**: canvas 3D = héroe; chrome glass fino; EN copy; portrait-first; no landscape-gate; tips tap (§4.13).
+- **Roadmap**: `roadmap/gui-art.md` + prompt `roadmap/PROMPT-gui-art.md` — cerrar A1–A6 (tipo, glass, emoji, rampa, motion, scope) **antes** de codear.
+- **Invariante**: polish visual no puede romper §4.1 Top-10, §4.1b mobile MQ, §3.4 startup ANALYSIS, ni WebGL §1.
+
+---
+
+## 5. Protocolo de Mantenimiento de Lecciones Aprendidas
+
+1. **Consulta Obligatoria**: El agente **DEBE** leer este archivo al iniciar cualquier tarea de implementación, diseño de shaders, navegación o refactorización.
+2. **Actualización Continua**: Al descubrir una nueva invariante técnica, bug de renderizado o patrón de rendimiento, el agente **DEBE** agregarla a este archivo antes de finalizar la tarea.
+
+---
+
+## 6. Dev tooling / ngrok / Vite ↔ backend
+
+### 6.0e. Workbench theme is the default UI (2.4.1+) — parallel skins retired
+- **Regla**: el chrome Magic Workbench es la UI **default** en `/` (`src/theme/` + `body.workbench-theme`). Product name = **VHectorLab 3D** (sin la palabra “Amiga” en marca).
+- **Retirado en 2.4.1**: MPA `/v25/`, `/amiga/`, árboles `src/v25/**`, `v25/**`, `amiga/**`, `src/amiga/**`. No reintroducir skins paralelos sin pedido explícito.
+- **Layout**: fullscreen `#app` + navbar/docks/HUD flotantes. **PROHIBIDO** shell multi-zona left|canvas|right (patrón v25 histórico).
+- **Colores**: `VITE_AMIGA_*` en `.env` (nombre histórico de vars; documentadas como Workbench theme).
+- **Vite**: `getViteInputs` → solo `main` (`index.html`). Redirects MPA bare-dir vacíos por default.
+- **Lección**: no volver a forkear UI en `/v25` o `/amiga` “por si acaso”; un solo producto en `/`.
+
+### 6.0d. _(histórico)_ `src/v25/**` — retirado
+- El árbol v25 fue **eliminado** en 2.4.1. Lecciones 6.0b/6.0c abajo quedan como memoria de bugs de ese experimento; no aplican a código vivo.
+
+### 6.0c. _(histórico v25)_ MODE switch = visibility toggle, never wipe left host
+- **Problema**: montar Compare con `zones.left.innerHTML = …` destruye el panel Arithmetic (form state + Top-10). Además `display: flex` en `.lab-left-host > [data-panel]` **pisa** el UA `[hidden]{display:none}` → el slot Arithmetic oculto sigue ocupando flex y deja un **hueco negro** arriba del Compare (lista cosine aplastada abajo).
+- **Solución Obligatoria**: host `.lab-left-host` con dos slots; ambos paneles montados; MODE alterna `hidden` + `.is-hidden` **y** CSS `display: none !important` en `[data-panel][hidden]`. Canvas guarda `lastArithmetic` **y** `lastCompare`. Al entrar COMPARE, VIEW preferido = **NAVIGATION** (framing multi-thread); ARITHMETIC vuelve a **ANALYSIS**.
+- **Invariante**: collapse/MODE ≠ unmount; nunca asumir que `[hidden]` gana a una regla `display:` propia.
+
+### 6.0b. _(histórico v25)_ canvas host size = container, not `window`
+- **Problema**: `SceneSetup` legado dimensiona el renderer con `window.innerWidth/Height` (fullscreen `#app`). En un host celda de grid → buffer/aspect incorrectos.
+- **Solución Obligatoria**: override `onWindowResize` → `clientWidth/Height` del host; `ResizeObserver`; ThreadLabels al tamaño del host.
+- **Invariante actual**: el producto default usa fullscreen `#app` (window size) otra vez; no reintroducir grid de zonas sin necesidad.
+
+### 6.0. Vite entry + FastAPI static
+- **Estado 2.4.1+**: un solo `index.html` en la raíz. `getViteInputs` → `{ main }`. FastAPI `resolve_dist_file` sigue sirviendo `path/index.html` si algún día hay subpaths.
+- **No hacer**: contaminar el producto con MPA skins paralelos sin OK humano.
+- **URL de prueba**: `http://127.0.0.1:5173/`
+
+### 6.1. Proxy `/api` en Vite: prefijo general, no ruta-a-ruta
+- **Problema**: Exponer frontend y backend con **el mismo** hostname ngrok (dos agentes → `:5173` y `:8000`) se pisa; el celu no puede llamar a `127.0.0.1:8000`.
+- **Solución Obligatoria**:
+  - Un solo túnel ngrok → Vite (`:5173`).
+  - En `vite.config.js`, proxy de prefijo: `'/api' → http://127.0.0.1:8000` (el backend ya monta el router con `prefix="/api"`).
+  - `VITE_API_BASE_URL=/api` en `.env` (habilitado por defecto en dev/ngrok). `RemoteProvider` usa esa base; header `ngrok-skip-browser-warning` cuando el host es ngrok.
+- **¿Hay que mapear endpoint por endpoint?** **No**, si todo el API vive bajo el mismo prefijo (`/api/health`, `/api/arithmetic`, `/api/compare`, …). Un solo `proxy['/api']` cubre rutas nuevas automáticamente.
+- **Cuándo sí ruta-a-ruta**: solo si exponés paths **fuera** de `/api` (p.ej. `/health` bare sin prefijo) y querés proxearlos — ahí cada path top-level necesita su propia entrada en `server.proxy`, o movés el contrato a `/api/*`.
+- **Invariante**: nuevas rutas backend bajo `/api` → cero cambio en Vite; si alguien agrega un mount root-level, o lo mete bajo `/api` o agrega proxy explícito + lesson.
+
+---
+
+## 7. Product versioning (SemVer) — VHectorLab 3D
+
+### 7.0. Product name (2026-08-03)
+- Canonical product name: **VHectorLab 3D** (was VectorLab 3D / VECTORLAB). Keep `roadmap/` historical docs as-is.
+- Do **not** rename `localStorage` keys `vl3d.*` — technical prefix, not brand; renaming breaks persisted prefs.
+- Sync brand + SemVer: `manifest.json`, `package.json`, Navbar `version-tag`, FastAPI `app.version`, `CHANGELOG`. v25 retirado en 2.4.1 — no hay `src/v25/version.js`.
+
+### 7.1. Diagnosis (why it felt broken)
+- **Too fast (Aug 2026 epic day)**: `1.1.0`→`1.5.0` burned a **MINOR per roadmap etapa** (docks / landscape / touch / MESH / RIBBONS) on the same calendar day. Semantically each etapa *was* a capability, but the Navbar tag looked like five releases without five ship moments.
+- **Too slow (post-`1.5.0`)**: many user-visible changes (defaults, fog, EN copy, slider ranges) sat only under `[Unreleased]` while `manifest` / Navbar stayed `1.5.0`. The tag stopped tracking “what users can do now.”
+
+### 7.2. Policy (what to bump when)
+Sync **`manifest.json` + `package.json` + Navbar `version-tag` + `CHANGELOG` section** together.
+
+| Bump | When |
+| :--- | :--- |
+| **MAJOR (`x.0.0`)** | Breaking backend/API contracts, embedding dim, or data shapes that break clients — **or** an explicit product milestone reset when the human asks to restart the line (e.g. **3.0.0** coverage-knobs ship after a long tag lag). |
+| **MINOR (`1.y.0`)** | Add **or remove** a product surface: MODE / VIEW / RENDER mode, major panel capability, or comparable user-facing feature. |
+| **PATCH (`1.y.z`)** | Fixes, spatial/camera defaults, fog/copy/i18n polish, docs-only sync that still ships. Prefer PATCH over leaving long Unreleased tails. |
+
+**Cadence rule**: bump **once per shippable delivery** of a notable change — not once per internal etapa on the same day, and not “never until the next epic.” Batch same-day etapas into one MINOR if they ship together. Do **not** leave the Navbar stuck for weeks while Unreleased grows.
+
+### 7.3. Build numbers — analysis (do **not** use as product version)
+Options considered: `1.5.0+42`, `1.5.0.42`, CI build id in the Navbar.
+
+| Approach | Pros | Cons for this repo |
+| :--- | :--- | :--- |
+| **SemVer build metadata (`1.6.0+gitsha`)** | Traceable artifacts | Not for “is this a new feature?”; Navbar noise; easy to confuse with PATCH |
+| **Four-part `1.6.0.N`** | Monotonic every merge | Not npm/SemVer; invents a fourth digit users don’t understand |
+| **CI build only in debug HUD** | Debug without product inflation | Fine as *optional* `VITE_SHOW_BUILD` — not the public version |
+
+**Decision**: product version stays **three-part SemVer**. History of capability = `CHANGELOG`. Optional CI/git SHA belongs in a debug overlay (like cam pose), **not** in the brand version tag. Build numbers do **not** replace PATCH/MINOR discipline.
+
+---
+
+## 8. Local onboarding / `setup.sh` (macOS)
+
+### 8.1. README must describe the control panel, not a backend-only path
+- **Problema**: Un README que solo documenta `cd backend && uv sync && uv run …` deja a juniors sin el flujo real (`./setup.sh` opción 1: deps, tests, backend+frontend, browser).
+- **Solución Obligatoria**: README en **inglés**, centrado en `./setup.sh` opción **1** como camino recomendado. Documentar qué hace cada opción del menú.
+
+### 8.2. Prerequisites: check **and install** on macOS (do not only fail)
+- **Problema**: “Verificar que estén instalados” y abortar con “instalalo vos” frena onboarding; el panel debe cerrar el gap.
+- **Solución Obligatoria** en `setup.sh` (opción 1 / `ensure_prerequisites`):
+  - Si falta **`uv`** → instalar con el installer oficial Astral; refrescar `PATH` (`~/.local/bin`, Homebrew).
+  - Si falta **Node/`npm`** → asegurar Homebrew y `brew install node`.
+  - Si falta **`.env`** → copiar desde `.env.example`.
+  - Sync backend: `uv sync --extra dev`; frontend: `npm install` si no hay `node_modules`.
+- **Invariante**: en Darwin, option 1 no debe pedir instalación manual de `uv`/Node salvo fallo de red/permisos.
+
+### 8.3. Platform scope is macOS-only until explicitly ported
+- **Problema**: Scripts con `open`, Homebrew paths y bash asumen Mac; documentar “multiplataforma” sin pruebas miente.
+- **Hecho / soportado**: creado y probado en **macOS 26.5.1 (Darwin 25.5.0, arm64)**.
+- **No preparado**: Windows ni Linux (aunque con pocos ajustes de package manager / PATH / process control suele ser viable).
+- **Invariante**: README + banner de `setup.sh` deben declarar esa versión de SO y el estado unsupported; auto-install de Node vía Brew es **macOS-only**. En no-Darwin: warn claro; no fingir soporte.
+
+### 8.4. Docker Desktop is optional (HF image only)
+- **Problema**: Juniors asumen que hace falta Docker Desktop para correr la app; o al revés, option 7 falla sin explicación.
+- **Hecho**: el flujo diario (opción **1**) es bare-metal (`uv` + Vite) — **no** requiere Docker.
+- **Cuándo sí**: opción **7** (`docker build` de la imagen HF Spaces, torch CPU + vocab NPZ). Opción **8** publica Space Docker cpu-basic vía `hf repos create` + `git push` — **no** necesita Docker Desktop local (el Hub buildea).
+- **Solución Obligatoria**: README marca Docker como **optional**; menú etiqueta option 7 con Docker Desktop; `ensure_docker` antes del build; option 8 usa `ensure_hf_cli` + `hf auth`.
+- **Invariante**: no meter Docker en `ensure_prerequisites` de option 1.
+
+### 8.5. HF Space cpu-basic packaging
+- **Problema**: `uv sync` en Linux tira wheels NVIDIA; encode de ~10k vocab en cada cold start OOMea o tarda demasiado.
+- **Problema 2**: HF exige YAML frontmatter en el `README.md` del Space (`sdk: docker`, `app_port: 7860`); ensuciar el README de GitHub rompe el contrato “README estándar de producto”.
+- **Problema 3**: `UV_TORCH_BACKEND=cpu` **no** aplica a `uv sync` (solo a `uv pip`) — el lock PyPI Linux seguía jalando `nvidia-*` multi-GB.
+- **Problema 4**: push al Space rechaza binarios no-Xet (p.ej. `demo/vhectorlab-gui-tour.gif`). Sacar el path del tip **no alcanza** si el commit tiene `-p HEAD`: el pack manda historial GitHub donde el GIF sigue viviendo; el hook de HF escanea el pack entero. Además: si `./setup.sh` quedó abierto desde antes del fix, la función vieja sigue **en memoria** — hay que salir (0) y re-lanzar.
+- **Solución Obligatoria**: Linux torch vía `[tool.uv.sources]` → index `pytorch-cpu` en `backend/pyproject.toml` + `uv.lock`; Dockerfile `uv sync --frozen` (sin confiar en `UV_TORCH_BACKEND`); precompute `public/vocab_embeddings.npz` en build; `.dockerignore` incluye `demo/`; option 8 compone README, strippea `demo/*` del index y pushea un tip **huérfano** (`commit-tree` **sin** `-p HEAD`) + `--force`; **guards** pre-push (`parents=0` + no `demo/`/gif reachable); contrato Space en **`deploy/hf/space-frontmatter.yml`**.
+- **Runtime device**: `/health.device` + navbar `ONLINE (model · cpu|cuda|mps)`.
+- **ARITHMETIC persist**: por visitante en `localStorage` (`vl3d.arithmetic.*`) — no disco del Space.
+- **Invariante**: no asumir GPU en Spaces Docker; ZeroGPU no aplica a sdk docker. **No** force-pushear `HEAD` crudo al Space si el README de producto no lleva frontmatter — siempre inyectar desde `deploy/hf/`. Option 7 necesita disco libre local (BuildKit I/O); option 8 no necesita Docker Desktop.
+- **Space model (2026-08)**: cpu-basic aguanta Arctic-m (~1.2 GB) + truncate 256 + vocab EN∪ES; alinear Dockerfile a `MODEL_PROFILE=local-full` para que Shared noise coincida con el lab Mac. No volver a pinear `all-mpnet` en el Space sin OK explícito.
+
+### 8.5. Local folder / clone name = `vhectorlab`
+- **Problema**: el working copy histórico se llamaba `lsv2`, luego `VHectorLab-3D`, mientras el remoto GitHub pasó a **`vhectorlab`**.
+- **Solución Obligatoria**: carpeta local canónica **`vhectorlab`** (minúsculas, alineada al repo). README: `git clone …/vhectorlab.git` + `cd vhectorlab`. Producto UI sigue **VHectorLab 3D**. No renombrar `vl3d.*` localStorage ni packages npm (`vhectorlab-3d`) solo por el folder/repo slug.
+- **Invariante**: `roadmap/` puede seguir mencionando `lsv2` / VectorLab / `VHectorLab-3D` como historia; no reescribir archivo salvo necesidad.
+
+### 8.6. Renaming the repo folder breaks `backend/.venv` shebangs
+- **Problema**: Tras `mv lsv2 → VHectorLab-3D`, `uv sync` reporta OK pero `uv run pytest` falla: `Failed to spawn: pytest` / `No such file or directory`. Los entrypoints en `.venv/bin/*` siguen con shebang absoluto a la ruta vieja (`…/lsv2/backend/.venv/bin/python3`).
+- **Solución Obligatoria**:
+  1. En `setup.sh` `ensure_project_deps`: si `backend/.venv/bin/pytest` existe y su intérprete shebang **no existe**, `rm -rf backend/.venv` y re-sync.
+  2. Invocar tests como `uv run python -m pytest` (menos frágil que el script `pytest` con shebang roto).
+  3. Recuperación manual: `rm -rf backend/.venv && cd backend && uv sync --extra dev`.
+- **Invariante**: un rename/move del working copy **implica** recrear el venv; `uv sync` solo no reescribe shebangs rotos.
+
+### 8.7. Idempotent start — never bounce a healthy stack
+- **Problema**: Opción 1 hacía `pkill` + relaunch siempre, aunque backend/frontend ya estuvieran healthy → pérdida de estado, re-carga del modelo, downtime innecesario.
+- **Problema 2 (Ctrl+C / PGID)**: sin sesión nueva, backend/vite compartían señales con el panel → SIGINT los mataba.
+- **Problema 3 (`set -m` / STAT T)**: `set -m` + job control dejó Vite en **stopped** (`STAT T`): puerto en LISTEN pero HTTP timeout → probe **sick** y el usuario quedaba trabado si option 1 solo abortaba.
+- **Solución Obligatoria** en `setup.sh` (opciones que arrancan servicios):
+  - Arrancar con **`launch_detached`** (`python3` + `start_new_session=True`, stdin DEVNULL) — sin controlling TTY; **no** usar `set -m` para esto.
+  - **healthy** = proceso matching (`pgrep`) **y** health OK (`/health` con `"status":"ok"` en `:8000`; HTTP OK en `:5173`). Puerto ocupado sin ese combo = **sick**.
+  - Ambos healthy → **skip** prerequisites, **skip** tests y **skip** start; abrir browser. Tests explícitos = opciones **4/5**.
+  - **Sick** o parcial → **recycle** ambos (kill + start), no abortar dejando al usuario trabado.
+  - Ambos down → flujo normal (prereqs → tests → start).
+  - Opción **2** (backend only): skip si healthy; recycle si sick.
+  - Opción **10** siempre hace stop real (`kill_stack`), no no-op.
+  - **Ctrl+C** nunca baja servicios: en live logs pausa → Enter vuelve al menú; segundo Ctrl+C sale del panel.
+- **Invariante**: no hay flag “force restart” separado; el stop explícito basta. No bajar+subir un stack ya healthy. Solo opción **10** detiene el stack a propósito. Servicios NUNCA comparten sesión/TTY con el panel.
+
+### 8.8. Arctic / GTE remote code on transformers≥5 (no xformers)
+- **Problema**: `Snowflake/snowflake-arctic-embed-m-v2.0` (profile `local-full`) falla al swap/precompute con `AssertionError: please install xformers` porque el Hub config trae `use_memory_efficient_attention=true`. En macOS/MPS xformers suele no estar / no servir.
+- **Problema 2**: aunque se desactive MEA, transformers **5.x** materializa en meta device y **corrompe** buffers `persistent=False` del remote GTE (`position_ids`, RoPE `inv_freq`/`cos_cached`/`sin_cached`) → `IndexError` o embeddings NaN. El remote code no los re-inicia en `_init_weights` (HF #43644 / #43950).
+- **Solución Obligatoria** en `backend.model_catalog.build_model` cuando `trust_remote_code`:
+  1. `config_kwargs={use_memory_efficient_attention: False, unpad_inputs: False}` (sin xformers; unpad sin MEA rompe RoPE).
+  2. Post-load `_repair_gte_nonpersistent_buffers`: rearmar `position_ids` + `rotary_emb` (`inv_freq` + `_set_cos_sin_cache`).
+- **Invariante**: no agregar `xformers` como dep de lab/macOS; no asumir que el remote GTE es compatible con transformers 5 sin repair.
+
+### 8.9. Shared noise visibility depends on embedding geometry (not model-specific wiring)
+- **Problema**: Shared noise “funcionaba” en el lab Mac (`local-full` Arctic @256) y en HF con `all-mpnet-base-v2` @768 el knob **no movía nada**. Primera lectura: bug de deploy / cableado distinto por modelo.
+- **Hecho**: el path JS (`groupDimContrast.js`) es **agnóstico al modelo** — solo min/max + sameSign + similarity sobre floats. No hay `if (model === …)`.
+- **Causa real**: veto D4 (un token con signo opuesto anula la dim) + batch diverso ⇒ en mpnet @768 casi no quedan dims same-sign (medido ~7% / ~3% con cancel>0 @77% Similarity); en Arctic @256 el mismo texto deja ~30% same-sign / ~21% cancel>0 → se ve. Densidad de paint ≈ fracción de dims, no conteo absoluto.
+- **Solución Obligatoria**:
+  1. No “arreglar” Shared noise especializando por Hub id sin decisión de producto.
+  2. Para demos alineadas al lab: Space = `MODEL_PROFILE=local-full` (Dockerfile).
+  3. Ante knob “muerto”: medir `sameSign%` / cancel density del batch **antes** de tocar shaders.
+  4. Estudios empíricos de este tipo viven en **`current-research/`** (no en `lessons-learned` ni en `roadmap/` como si fueran tickets). Evidencia completa: `current-research/DISCOVERY-shared-noise-embedding-geometry.md`.
+- **Invariante**: lección de ingeniería acá; ciencia abierta / ablaciones / rediseño de métrica → `current-research/` + handoff omit-common. SAE ON no es el instrumento para cazar “pack compartido” en RAW.

.agents/skills/dev-protocol/qa-review.md

@@ -0,0 +1,41 @@
+# QUALITY ASSURANCE & SYSTEM REVIEW WORKFLOWS
+
+Follow these protocols to maintain spec compliance, code quality, and clear, durable issue reporting.
+
+---
+
+## 1. QUALITY ASSURANCE & ISSUE FILING
+
+When the user describes problems during QA, or when planning a feature, translate them into durable, clear issues on the project issue tracker.
+
+### 1.1. Rules for Filing Issues
+- **Durable**: Issues should remain valid after major refactors.
+- **Describe behaviors, not code**: Say *"the login page fails to redirect after submitting"* instead of *"authController.js throws on line 42"*.
+- **No file paths or line numbers**: These go stale rapidly.
+- **Use the project's domain language**: Reference terms as defined in `architecture_spec.md`.
+- **Reproduction steps are mandatory**: List concrete, numbered steps a developer can follow, including inputs, flags, or configuration.
+
+### 1.2. Single Issue vs Breakdown
+- **Single Issue**: Use when it is a single behavior wrong in one place, or multiple symptoms caused by the exact same root behavior.
+- **Breakdown**: Break a task or report into multiple issues when:
+  - The work spans multiple independent areas.
+  - Slices are independently fixable and verifiable.
+  - There are blocker/dependency relationships (e.g. Issue B cannot be tested until Issue A is completed).
+- **Tracer Bullet Breakdown**: When breaking down a plan, create **vertical slices** (tracer bullets) that cut through all layers (schema -> API -> UI -> tests) and are demoable. Publish issues in dependency order (blockers first).
+
+---
+
+## 2. TWO-AXIS REVIEW WORKFLOW
+
+To verify changes before merging, perform a review of the diff against `HEAD` along two distinct, independent axes:
+
+### 2.1. The Two Review Axes
+1. **Standards Axis**: Checks if the diff conforms to this repository's documented coding standards (e.g., `CODING_STANDARDS.md`, formatting rules, type structures).
+2. **Spec Axis**: Checks if the diff faithfully implements the originating issue, spec, or PRD.
+   - Detects missing/partial requirements.
+   - Detects scope creep (behavior in the diff that wasn't asked for).
+   - Detects incorrect implementations of requirements.
+
+### 2.2. Parallel Evaluation Protocol
+- **Parallel Sub-Agents**: Run the Standards review and Spec review as two parallel sub-agents (using `general-purpose` sub-agents) to prevent context pollution.
+- **Integration**: Aggregate both reports under `## Standards` and `## Spec` headers verbatim. Do not merge or rerank their findings, as a change can pass one axis while failing the other (e.g., standard-compliant code that implements the wrong feature).

.agents/skills/dev-protocol/templates/.env.example

@@ -0,0 +1,44 @@
+# =============================================================================
+# DEV AGENT PROTOCOL — environment template for Python LLM apps
+# -----------------------------------------------------------------------------
+# Usage in a new app:
+#   1. Copy this file to the workspace ROOT as `.env.example` and commit it.
+#   2. Copy it again to `.env`, fill in real values, and KEEP `.env` GITIGNORED.
+#
+# Rules (see dev-protocol/SKILL.md §3.2):
+#   - Secrets (keys/tokens) live here, never in code, never committed.
+#   - `.env.example` documents the variables WITHOUT real values.
+#   - Model / provider / endpoint are configuration, not hardcoded constants.
+#
+# Document only the variables your app actually reads; delete the rest.
+# =============================================================================
+
+# --- Provider selection ------------------------------------------------------
+# Which adapter to use behind the single provider interface.
+# Examples: "local" | "remote"  (or a concrete backend id your app supports)
+LLM_PROVIDER=local
+
+# --- Remote provider (hosted API) --------------------------------------------
+# Leave blank in the example; fill real values only in your local .env.
+LLM_API_KEY=
+LLM_BASE_URL=https://api.example.com/v1
+LLM_MODEL=
+
+# --- Local provider (e.g. Ollama / llama.cpp / vLLM) -------------------------
+# Endpoint of the locally running model server.
+LOCAL_LLM_BASE_URL=http://localhost:11434
+LOCAL_LLM_MODEL=
+
+# --- Generation defaults (configuration, not literals in code) ---------------
+LLM_TEMPERATURE=0.0
+LLM_MAX_TOKENS=1024
+LLM_REQUEST_TIMEOUT_SECONDS=60
+
+# --- Observability (token / latency / cost logging — SKILL.md §3.2) ---------
+# Toggle structured logging of token counts and latency for regression tracking.
+LLM_LOG_USAGE=true
+
+# --- App runtime -------------------------------------------------------------
+LOG_LEVEL=INFO
+# HOST=0.0.0.0
+# PORT=8000

.agents/skills/dev-protocol/templates/.pre-commit-config.yaml

@@ -0,0 +1,63 @@
+# =============================================================================
+# DEV AGENT PROTOCOL — pre-commit base template (Python / uv)
+# -----------------------------------------------------------------------------
+# Usage in a new app:
+#   1. Copy this file to the workspace ROOT as `.pre-commit-config.yaml`.
+#   2. Install the git hook once:   uv run pre-commit install
+#   3. Smoke-test the whole repo:   uv run pre-commit run --all-files
+#
+# Pin the `rev:` tags to the latest releases when you adopt this in a repo,
+# then let `pre-commit autoupdate` keep them current. Versions below are
+# conservative defaults, not gospel — see dev-protocol/git-workflow.md §2.
+# =============================================================================
+
+repos:
+  # --- General hygiene -------------------------------------------------------
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+      - id: check-yaml
+      - id: check-toml
+      - id: detect-private-key        # blocks committed private keys
+
+  # --- Lint + Format (ruff replaces black + flake8 + isort) ------------------
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff                      # lint
+        args: ["--fix"]
+      - id: ruff-format               # format
+
+  # --- Secret scanning (enforces "no keys in git" — SKILL.md §3.2) -----------
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.2
+    hooks:
+      - id: gitleaks
+
+  # --- Local guard: never let an actual .env file get staged -----------------
+  - repo: local
+    hooks:
+      - id: block-dotenv
+        name: block committing .env files
+        entry: "Refusing to commit a .env file. Keep secrets out of git; commit .env.example instead."
+        language: fail
+        files: '(^|/)\.env(\..+)?$'
+        # Allow the documented example file through:
+        exclude: '(^|/)\.env\.example$'
+
+# --- Optional: project-wide type checking ------------------------------------
+# Type checking the full tree is often too slow for every commit. Prefer
+# running it in CI, or enable it here as a manual stage:
+#   uv run pre-commit run --hook-stage manual mypy
+#
+#  - repo: https://github.com/pre-commit/mirrors-mypy
+#    rev: v1.13.0
+#    hooks:
+#      - id: mypy
+#        stages: [manual]
+#        additional_dependencies: []   # add type stubs your project needs

.dockerignore

@@ -0,0 +1,35 @@
+.git
+.github
+.venv
+backend/.venv
+node_modules
+dist
+# GitHub README demo assets — not needed in Space image; HF also rejects non-Xet binaries on git push
+demo
+**/__pycache__
+**/*.py[cod]
+**/.pytest_cache
+**/.ruff_cache
+**/.mypy_cache
+**/.coverage
+**/htmlcov
+*.log
+logs
+.env
+.env.*
+!.env.example
+.DS_Store
+*.swp
+.cursor
+.agents
+agent-transcripts
+roadmap/archivo
+CONTEXT.blueprint.md
+context.txt
+public/vocab_embeddings.npz
+backend/artifacts
+*.pt
+.vscode
+.idea
+coverage
+test-results

.env.example

@@ -0,0 +1,55 @@
+# VHectorLab 3D - Environment Variables
+HOST=127.0.0.1
+PORT=8000
+MODEL_NAME=all-mpnet-base-v2
+# Default stays EN baseline (all-mpnet). Optional profiles after setup option 11:
+# MODEL_PROFILE=local-comfort
+# MODEL_NAME=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+# TRUNCATE_DIM=
+VOCAB_PATH=public/vocab.txt
+# EN∪ES merged vocab (after: uv run python scripts/merge_vocab_en_es.py):
+# VOCAB_PATH=public/vocab_en_es.txt
+# Optional precomputed vocab embeddings (Docker/HF builds this automatically)
+VOCAB_EMBEDDINGS_PATH=public/vocab_embeddings.npz
+LOG_LEVEL=INFO
+# Local bare-metal: unset or 1. Docker/HF Space: 0
+# UVICORN_RELOAD=1
+
+# Frontend (Vite) — show live camera POS/ROT overlay for capturing default views
+VITE_SHOW_CAM_POSE=false
+
+# Top-K SAE + embedding runtime device: AUTO | CPU | CUDA | MPS
+SAE_DEVICE=AUTO
+
+# API base for the browser client (RemoteProvider).
+# Enabled default for ngrok/phone: same-origin `/api` → Vite proxies to :8000
+# (one public tunnel to :5173 is enough; do not reuse the same ngrok host for :8000).
+#
+#   VITE_API_BASE_URL=/api
+#
+# Alternatives:
+#   (unset)  auto — localhost → http://127.0.0.1:8000 ; public host → /api
+#   http://127.0.0.1:8000
+#   https://<backend-subdomain>.ngrok-free.dev   # dual-tunnel (two different URLs)
+VITE_API_BASE_URL=/api
+
+# --- Workbench theme (MagicWB) — hex #RRGGBB; omit to use defaults ---
+# Dark gray surfaces (pens 0/4/5 + bg); light fg for contrast
+VITE_AMIGA_PEN_0=#2A2A2A
+VITE_AMIGA_PEN_1=#000000
+VITE_AMIGA_PEN_2=#FFFFFF
+VITE_AMIGA_PEN_3=#3B67A2
+VITE_AMIGA_PEN_4=#1A1A1A
+VITE_AMIGA_PEN_5=#3D3D3D
+VITE_AMIGA_PEN_6=#AA907C
+VITE_AMIGA_PEN_7=#FFA997
+VITE_AMIGA_BG=#222222
+VITE_AMIGA_FG=#F0F0F0
+VITE_AMIGA_ACCENT=#3B67A2
+
+# Hugging Face Space publish (setup.sh option 8) — Enter accepts these defaults
+HF_SPACE_ID=hbauzan/llm-semantic-visualizer
+# Force-push ephemeral tip → Space main (Space history ≠ GitHub; needed to replace old Space content)
+HF_SPACE_FORCE_PUSH=1
+# YAML contract injected into Space README at publish (GitHub README stays without frontmatter)
+# HF_SPACE_FRONTMATTER=deploy/hf/space-frontmatter.yml

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,10 @@
+---
+name: Custom issue template
+about: Describe this issue template's purpose here.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environments
+.venv/
+venv/
+ENV/
+env/
+
+# Environment variables
+.env
+!.env.example
+
+# Node dependencies & builds
+node_modules/
+dist/
+.vite/
+.pnpm-store/
+pnpm-lock.yaml
+pnpm-workspace.yaml
+
+# Pytest / Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# SAE / model weight binaries
+*.pt
+!backend/artifacts/.gitkeep
+public/vocab_embeddings.npz
+
+# Local AI regeneration blueprint (do not publish)
+CONTEXT_HAB.MD
+
+# Demo GIF capture tooling / scratch (published tour GIF is tracked)
+scripts/capture-galaxy-demo.mjs
+demo/**
+!demo/vhectorlab-gui-tour.gif
+
+# Logs & temp
+*.log
+.DS_Store

CHANGELOG.md

@@ -0,0 +1,363 @@
+# Changelog
+
+All notable changes to VHectorLab 3D will be documented in this file.
+
+## [Unreleased]
+
+### Fixed
+- **HF Space publish (option 8)**: ephemeral tip strips `demo/` binaries and is an **orphan** commit (no `-p HEAD`) so the push pack does not include GitHub history that still has the GIF; HF rejects non-Xet binaries in the whole pack. Composed Space README drops local demo media embeds.
+- **HF / Docker torch CPU**: Linux installs `torch` from `pytorch-cpu` index via `[tool.uv.sources]` (nvidia-* no longer pulled). `UV_TORCH_BACKEND` alone never affected `uv sync`.
+
+### Changed
+- **HF Space model = local-full**: Docker/Space now runs `Snowflake/snowflake-arctic-embed-m-v2.0` with `TRUNCATE_DIM=256` + `vocab_en_es.txt` (aligned with Mac lab Shared noise). Fits cpu-basic (~1.2 GB weights / 16 GB RAM).
+### Added
+- **`current-research/`**: home for empirical discovery notes (beyond `lessons-learned`). First note: Shared noise × embedding geometry (Arctic@256 vs mpnet@768).
+- **HF Space README inject**: `deploy/hf/space-frontmatter.yml` + `scripts/compose_hf_space_readme.sh`; option 8 pushes an ephemeral tip with `sdk: docker` / `app_port: 7860` without polluting the GitHub product README.
+- **Compare group cosine panel**: with ≥2 `GROUP_*`, the lower list shows group-centroid cosine vs the first group in the textarea (mean of L2 unit vectors → re-L2 → dot); flat / single group stays token-vs-first. 3D viewer unchanged.
+- **Multi-embedding catalog (local)**: profiles `local-comfort` / `local-full` / `hf-demo`, setup.sh **option 11** swap (stage `.env` → rebuild vocab NPZ → restart), EN∪ES vocab merge, `/health` fields (`model_profile`, `short_label`, `embedding_dim`, `truncate_dim`), navbar ONLINE chip shows profile · label · dim · device. Cross-lingual smoke: `scripts/smoke_crosslingual_cosine.py` (non-blocking; `--strict` optional). Default `.env.example` remains **all-mpnet-base-v2**. HF Space model policy unchanged.
+- **Galaxy / boot progress overlay**: full-viewport card over the canvas (`#boot-progress`) so encode→UMAP progress stays visible when the left dock is collapsed (e.g. switching ARITHMETIC → GALAXY on mobile).
+
+### Changed
+- Left Compare/Arithmetic dock: a bit taller (`min(68vh, 600px, …HUD)`) with side scrollbar + `scrollbar-gutter` when content overflows; never taller than the space above the bottom HUD.
+- **License**: project relicensed from MIT to **Apache License 2.0** (`LICENSE` + `NOTICE`; README / HF Space card `license: apache-2.0`; `package.json` `license` field).
+- Bootstrap / 2 Groups demo labels: `it_core` (IT terms), `vehicles` (auto lexicon), `women` (English women’s names) — replaces `GROUP_it_core` / `GROUP_1` / `GROUP_2`.
+- Panel buttons: Visualize Sequence + Clean/Denoise (SAE) slightly larger; all other panel buttons compact at Shared-noise scale (`0.68rem` / weight 600).
+- 3D Spatial Controls: denser padding/gaps (Compare-like); dock stays top-right with gizmo stacked under sliders (no empty mid-gap).
+- HUD hover: token caption left of `HOVER TELEMETRY` (right TOKEN column removed); grouped Compare points show `group/token`.
+- Galaxy default camera pose: POS `25.5, 155.2, 328.9` / ROT `-23.2, 14.0, 0` (captured CAM POSE).
+- Startup chrome defaults: **ARITHMETIC | ANALYSIS | POINTS** (desktop + mobile; was COMPARE | GALAXY).
+
+## [3.0.1] - 2026-08-26
+
+### Added
+- **Thread lines** toggle (Visualization panel, top): show/hide POINTS continuity lines along each thread; points and magnitude colors stay. Persists `vl3d.viz.threadLinesVisible` (default ON).
+
+## [3.0.0] - 2026-08-26
+
+Milestone cut: start the **3.x** line after shipping the coverage / Shared noise chrome (the tag had lagged the product for too long).
+
+### Changed
+- **Coverage knobs (Zero coverage + Shared noise)**: DAW-style vertical drag (`ns-resize`), long throw, A=100 + mA forces A→99; **mA** fine fraction now **5 decimal places** (`0…0.99999`, step `1e-5`). Room for a future µA knob if needed.
+- Builds on **2.4.3** Shared noise token-batch + A/mA Workbench chrome (30%…100%).
+
+## [2.4.3] - 2026-08-26
+
+### Changed
+- **Shared noise** retarget: cancel from **token-batch** min/max across all Compare embeddings (`groupId` ignored); Sign conflict stays G1↔G2 means. Control sits after Zero coverage; gate ≥2 tokens. Group contrast = Sign conflict + Group hue (≥2 groups).
+- **Zero coverage / Shared noise Similarity**: range **30%…100%**; dual **A / mA** Workbench knobs + editable % readout (one persisted percent). Dual coarse/fine knobs for Zero coverage and Shared noise — yes, it looks a bit like studio gear cosplay on a Workbench panel. Keeping it anyway: one slider fighting the top end was worse UX than a little theatrical.
+
+## [2.4.2] - 2026-08-08
+
+### Added
+- **Galaxy feel**: larger UMAP world (`GALAXY_DEFAULT_SCALE` 96, spacing×240) + Galaxy-only flight profile (cruise 56, Shift ×2, softer look); leave Galaxy restores ANALYSIS/NAV speeds.
+- **Galaxy soft stars**: circular solid core + soft halo POINTS (ANALYSIS/NAV squares unchanged).
+- **Group hue** (Visualization → Group contrast): per-`GROUP_*` black (−1) → picked color (+1); default OFF; transversal COMPARE paint (POINTS + RIBBONS); Shared noise / Sign conflict still layer on top.
+
+### Changed
+- Workbench value fields (`input` / `textarea` / `select`): dark fill `#1a1a1a` instead of white (color/range/checkbox unchanged).
+
+## [2.4.1] - 2026-08-08
+
+### Added
+- **Magic Workbench chrome as the default UI** at `/`: Topaz (self-hosted), dark MagicWB surfaces, Workbench bevels, Compare/Arithmetic panel scroll, env-tunable pens via `VITE_AMIGA_*` (`src/theme/`).
+- Product stays branded **VHectorLab 3D** (no “Amiga” in the product name).
+
+### Changed
+- **Single frontend entry**: Vite builds only `index.html` → `/`. Parallel MPAs **`/v25/`** and **`/amiga/`** removed (code under `src/v25/**`, `v25/`, `amiga/`, `src/amiga/**` deleted).
+- Theme modules live in `src/theme/` (tokens, chrome overrides, Topaz, `magicwbEnvColors`).
+- Roadmaps for v25 / amiga MPA / gui-art parallel skin moved to `roadmap/archivo/`.
+
+### Fixed (during Workbench cutover)
+- Right-dock gray slab behind Spatial Controls (dock-body no longer painted).
+- Compare token textarea: black field, muted text.
+- Compare/Arithmetic left panels: scroll like Visualization (`min(56vh, 520px)`); preset chips wrap.
+- Font antialiasing enabled for Workbench chrome.
+
+## [2.4.0] - 2026-08-08
+
+### Added
+- _(Superseded by 2.4.1 cutover.)_ Interim `/amiga/` MPA scaffold + `VITE_AMIGA_*` color env — folded into default `/` in 2.4.1.
+
+## [2.3.0] - 2026-08-08
+
+### Added
+- **Galaxy VIEW** (in progress): new VIEW tab with UMAP/PCA/t-SNE chips (PCA/t-SNE grayed); entering Galaxy locks MODE=COMPARE + RENDER=POINTS.
+- **`POST /project`**: backend UMAP projection of precomputed embeddings (`umap-learn`); pca/tsne → 501.
+- **Bootstrap corpus**: `GROUP_it_core` (100 IT tokens) + existing `GROUP_1` / `GROUP_2` demos (REF inside IT core).
+- **Galaxy layout**: one point per token from UMAP positions; group badges at centroids; camera frames IT core; no dim-axis ribbons.
+- **Galaxy pipeline + progress**: client-driven encode → SAE? → UMAP → build with status text, progress bar, and step **k/n**; Visualize + SAE toggle in Galaxy; reuse `/compare` cache when texts unchanged.
+
+## [2.2.1] - 2026-08-07
+
+### Added
+- **`/v25/` MPA scaffold** (Fase 1): `v25/index.html` + `src/v25/main.js` hello shell; Vite multi-page via `getViteInputs()`; FastAPI `resolve_dist_file` serves nested `dist/v25/index.html` (directory index). Legacy `/` unchanged.
+- **GUI & Art v25 plan** (`roadmap/gui-art-v25.md` + `PROMPT-gui-art-v25.md`); epic index `gui-art.md` points agents at `/v25/` phases.
+
+## [2.2.0] - 2026-08-07
+
+### Added
+- **Field-info tips ("i")** on every editable control (Arithmetic, Compare, SAE params, Spatial sliders, Visualization): short English tap tips, mobile-safe popover (not hover-only `title`).
+- **HF Space cpu-basic demo path** (`feat/hf-space-cpu-demo`): Docker torch CPU (`UV_TORCH_BACKEND=cpu`), vocab embeddings NPZ at image build, `/health.device`, navbar `ONLINE (model · device)`, ARITHMETIC `localStorage` persistence (`vl3d.arithmetic.*`), setup option 7 smoke-run + option 8 `hf` create Space (docker / cpu-basic) + push, README Space YAML frontmatter.
+
+### Changed
+- **Repo / local folder slug**: GitHub + working copy **`vhectorlab`** (was `VHectorLab-3D`). Product name **VHectorLab 3D** unchanged; npm/manifest id stays `vhectorlab-3d`.
+- **Landscape gate retired**: no more “Better in landscape” cartel — phone portrait is preferred.
+- **Arithmetic Top-10**: list scrolls with a **120px floor** (`max(120px, min(…, dvh))`); on short viewports (≤560px) the whole Arithmetic panel scrolls so neighbors stay reachable. Mobile MQ also matches short landscape phones (`max-height: 500px` + `hover: none`) so touch chrome does not drop off.
+- **Startup chrome**: default is **ARITHMETIC | ANALYSIS | POINTS** (was NAVIGATION).
+
+### Fixed
+- **`setup.sh` option 8**: defaults from `.env` (`HF_SPACE_ID`, `HF_SPACE_FORCE_PUSH=1`); skip create if Space exists; force-push to Space remote only (not GitHub) so Enter×N publishes over divergent predecessor history.
+- **`setup.sh` idempotent start**: options 1/2 probe process + health before launch; skip bounce when already healthy; refuse when sick; restart both only on partial stack. README + lessons §8.7.
+- **`setup.sh` Ctrl+C**: pauses log follow / exits panel without stopping services; only option 10 stops. Menu banner OS line removed.
+- **`setup.sh` process group**: enable `set -m` so backend/vite are not in the panel PGID (Ctrl+C was killing the stack). Healthy path also skips tests.
+- **`setup.sh` detached session**: replace `set -m` with `start_new_session` launch (Vite was freezing at STAT T / sick). Option 1 recycles sick stacks instead of aborting.
+- **Offline modal**: no longer hardcodes `127.0.0.1:8000` (works for local setup + HF Space).
+- **Uvicorn reload**: off by default when `HOST=0.0.0.0` or `UVICORN_RELOAD=0` (Docker/HF).
+
+## [2.1.1] - 2026-08-03
+
+### Changed
+- **Rebrand**: product name **VectorLab 3D** → **VHectorLab 3D** (UI, docs, package manifest).
+
+### Fixed
+- **HUD ACTIVATION stuck at 0.0000**: resolve hover from `pointsData[index]` / ribbon `activations`; adaptive precision up to 32 decimals (shrink / scientific / `ACT:` on narrow mobile slots).
+
+## [2.1.0] - 2026-08-02
+
+### Added
+- **COMPARE group contrast visibility** (`feat/compare-group-contrast-viz`):
+  - Amplitude default **16** for `COMPARE|ANALYSIS|POINTS` and RIBBONS twin (was floor `1.0`).
+  - SAE ON auto-sets Visualization filter to **+ Only**; SAE OFF restores the previous filter.
+  - Soft Y gap (+1× Dist Y) between contiguous `GROUP_*` blocks in ANALYSIS.
+  - Toggle **Sort dims by group contrast** (session-only, OFF default; visible when ≥2 groups) — permutes X by max pairwise `|Δmean|`.
+  - Cosine ▲/▼ disabled while groups are active (preserves block layout).
+
+### Changed
+- Roadmap decisions D1–D12 closed (pack 1: L1+L2; L3 deferred; SemVer MINOR).
+
+## [2.0.0] - 2026-08-02
+
+### Added
+- **Top‑K SAE Clean/Denoise** (`feat/topk-sae-denoise`): trained Sparse Autoencoder (PyTorch), **not** L1 SAE and **not** sinusoidal fake projection.
+  - Defaults: 768 → 8192 latents (cap), K=32; **train on current Compare/Arithmetic scope** (not full vocab); **ephemeral in-RAM** session model; `suggest_sae_dims` auto-scales for small N; clear on Visualize/Calculate.
+  - API: `GET /api/sae/status`, `POST /api/sae/train` (embeddings + async poll), `POST /api/sae/encode` (**Top‑K sparse** `indices`/`values` + `ORJSONResponse`; client densifies), `POST /api/sae/clear`.
+  - UI: Compare-only 50/50 CTA `[ VISUALIZE | Clean/Denoise (SAE) ]`, Train SAE + params, progress, metrics strip. **No SAE in Arithmetic.**
+  - Semantics: SAE ON **replaces** all Arithmetic/Compare vectors used for 3D + cosine with sparse activations; OFF restores cached raw 768D. Preference in `localStorage` (`vl3d.sae.*`). Scope change invalidates the session SAE.
+  - Encode I/O: wire format is `[N, K]` indices+values (not dense `[N, hidden]`); model singleton stays in RAM after first `load_model()`.
+- **Zero coverage %** (carried onto this branch): Visualization panel slider expands how much of |t| stays at the zero/black color before blending to ±1 (cap 90%); `vl3d.viz.zeroCoverage`.
+- **Hide/Show labels** in Visualization panel: toggles floating thread/group badges; persists `vl3d.viz.labelsVisible`.
+- **SAE camera framing**: on Clean/Denoise toggle ON, dim-axis pitch scales so sparse features keep ~RAW wall width; camera soft-lerps to content bounds (ANALYSIS front / NAVIGATION angled). OFF restores Length + context pose with lerp. Empty train hyperparams no longer clamp to 32/k=1.
+
+## [1.8.0] - 2026-08-02
+
+### Added
+- **Visualization Controls** (`feat/visualization-sign-color-controls`): right-dock panel under 3D Spatial Controls.
+  - Sign filter: `All | + Only | − Only` on **normalized** activations (ε=0.01); hides opposite sign and near-zero for ± only.
+  - Applies to POINTS (shader discard) and RIBBONS / continuity lines (index omission) in ARITHMETIC + COMPARE.
+  - Three hex color anchors (+1 / 0 / −1) replace the fixed mid-stop divergent ramp; defaults `#FFE600` / `#000000` / `#9900E6`.
+  - POINTS shader uniforms `uColorPos` / `uColorNeg` / `uColorZero`; live update + `localStorage` (`vl3d.viz.*`) + Reset.
+  - Edge collapse tab (dock-tab affordance) slides the Visualization card to a thin strip; persists `vl3d.viz.panelCollapsed`.
+
+## [Unreleased]
+
+### Changed
+- **Defaults COMPARE|ANALYSIS|POINTS** (`feat/compare-analysis-points-defaults`):
+  - Sliders: Spacing `1.45`, Dist Y `1.0`, Amp `1.0`, Length `0.2`, Thickness `0.01`.
+  - Camera: `POS (-150.3, 0.7, 276.6)` / `ROT (-0.5, 0.9, 0)`.
+
+### Fixed
+- **Defaults COMPARE|NAVIGATION|RIBBONS + fog off for RIBBONS** (`feat/compare-nav-ribbons-defaults-no-fog`):
+  - Sliders: Spacing `1.55`, Dist Y `10`, Amp `7`, Length `0.057`, Thickness `0.05`.
+  - Camera: `POS (-575.8, 43.8, 237.9)` / `ROT (-22.4, -35.7, 0)`.
+  - `setFogForRenderMode('RIBBONS')` clears scene fog; POINTS keeps soft FogExp2.
+  - Compare+RIBBONS no longer mounts the POINTS cloud (square dots on strips).
+- **RIBBONS dark rectangle through translucent strips** (`fix/remove-ribbons-base-plane`): stop mounting `createBasePlaneForThreads` under wide ribbons (Arithmetic + Compare). Factory helpers retained unused.
+- **Remove floor GridHelper** (`fix/remove-scene-grid`): no reference grid under the 3D scene (cleaner RIBBONS/COMPARE views).
+- **Scene fog too dense for far RIBBONS** (`fix/soften-scene-fog`): `FogExp2` density `0.008` → `0.0008` so ribbons stay readable at COMPARE-scale camera distance; avoids distance “creeping” darkening. POINTS unaffected (custom shader).
+
+### Changed
+- **Spacing (X) range → `[0.4, 2.0]`** (`feat/spacing-range-center-compare`): same track for all MODE|VIEW|RENDER; COMPARE default `0.7` unchanged. Other combo defaults unchanged (Amp/Thickness ranges untouched).
+- **Length (Z) range → `[0.001, 0.2]`** step `0.001`, label 3 decimals: never reaches 0; COMPARE `0.1` ≈ mid; global/Analysis `0.2` at max.
+- **Defaults COMPARE|NAVIGATION|POINTS** (`feat/compare-nav-points-defaults`):
+  - Sliders: Spacing `0.7`, Vector Distance `10`, Amplitude `4.9`, Length `0.1`, Thickness `0.01`.
+  - Camera: `POS (-106.5, 20.4, 390.2)` / `ROT (-3.9, -8.4, 0)` via `cameraViewDefaults.js`.
+  - Camera poses now resolve per MODE|VIEW|RENDER (VIEW fallbacks + overrides); applied with sliders on context change.
+  - First COMPARE entry loads full EN auto-manual lexicon (`COMPARE_AUTO_PRESETS.default`), not `sample5`.
+- **English-only product UI** (`feat/english-user-facing-copy`): Navbar VIEW/ANALYSIS/NAVIGATION, spatial slider labels, Arithmetic/Compare buttons, Compare empty/sort/copy + EN auto-parts presets, landscape gate. Internal `data-view` / mode keys unchanged. Test titles and in-scope `src/` comments translated to EN; historical CHANGELOG entries left in Spanish.
+- **Docs: English-only UI roadmap** — glossary + D6–D8 closed (EN Compare vocab; EN test titles/comments; keep historical CHANGELOG in Spanish). See `roadmap/english-ui-i18n.md` + `roadmap/PROMPT-english-ui.md`.
+- **ThreadLabels cortas** (`feat/short-thread-labels` + `fix/compare-labels-full-tokens`):
+  - Arithmetic 3D: `WORD_A` / `WORD_B` / `WORD_C` / `RES` / `TOP1` (sin badge de tipo).
+  - Compare 3D: token completo ingresado (sin `TOPn` / sin truncar) — todos los items de la secuencia.
+- **Defaults ARITHMETIC|ANALYSIS|POINTS** (`feat/arithmetic-analysis-points-defaults`):
+  - Sliders: Separación `0.4`, Distancia Y `10`, Amplitud Y `40`, Longitud Z `0.2`, Grosor `0.05` (override en `spatialSliderDefaults.js`).
+  - Cámara Análisis: `POS (-75.2, -0.8, 62.5)` / `ROT (0, 0, 0)`.
+  - Al cambiar MODE/VISTA/RENDER se reaplica el preset resuelto + sync de sliders.
+- **Grosor Puntos mid → 0.05** (`feat/thickness-mid-0.05`):
+  - Default/mid `0.05` ∈ `[0.01, 0.09]` step `0.01` (simétrico lineal).
+- **Amplitud (Y) max → 40** (`feat/amplitude-y-max-40`):
+  - Rango `[1.0, 40.0]` step `0.1`; default sigue en `7.0` (asimétrico — sin regresión del punto dulce al load).
+- **Control Espacial 3D — dblclick reset** (`feat/spatial-slider-dblclick-reset`):
+  - Doble clic en un slider restaura solo ese valor al default del contexto MODE/VISTA/RENDER (hoy = global mid; overrides listos en `spatialSliderDefaults.js`).
+- **Control Espacial 3D — finer steps** (`feat/finer-spatial-slider-steps`):
+  - Gradual intermediate values: Separación step `0.05` (2 dec), Distancia/Amplitud Y step `0.1` (1 dec), Longitud/Grosor step `0.01` (2 dec). Min/max/mid unchanged.
+- **Control Espacial 3D — ranges re-centrados** (`feat/recenter-spatial-slider-ranges`):
+  - Defaults (punto dulce) son el mid lineal de cada slider: Separación X `0.4` ∈ `[0.1, 0.7]`, Distancia Y `10` ∈ `[1, 19]`, Amplitud Y `7` ∈ `[1, 13]`, Longitud Z `0.2` ∈ `[0.1, 0.3]`, Grosor `0.10` ∈ `[0.05, 0.15]`.
+  - Corrige Distancia Y y Grosor pegados al mínimo al load.
+
+### Added
+- **Ngrok / phone dev access** (`feat/ngrok-dev-access`):
+  - Vite `allowedHosts` + `/api` proxy to `127.0.0.1:8000` (prefix proxy — not per-route).
+  - `VITE_API_BASE_URL=/api` enabled in `.env` / `.env.example`; `RemoteProvider` honors it.
+  - Lesson §6.1: new backend routes under `/api` need no Vite remap.
+
+## [1.7.0] - 2026-08-02
+
+### Added
+- **COMPARE groups** (`feat/compare-group-labels`): parse `GROUP_name = tokens…` in the textarea; concatenate groups into the sequence; floating `GROUP_*` badges at member centroids. Preset **2 Groups**. Anchor remains global #1; cosine sort is global (may break contiguity). When groups are active, overlay shows group badges only (token cards hidden — still listed in cosine panel); label layer z-index above docks so badges stay visible.
+
+### Fixed
+- **COMPARE group badges never appeared** (`feat/compare-group-labels`): `ComparePanel` → `handleCalculateCompare` callback dropped `tokenMeta`, so `groupId` never reached Instancer/ThreadLabels (token stack stayed, no `GROUP_*`).
+
+## [1.6.0] - 2026-08-02
+
+### Removed
+- **RENDER: MESH** (`chore/remove-render-mesh`): surface heightfield mode retired from navbar and runtime. Supported modes: POINTS | RIBBONS. `normalizeRenderMode` maps legacy `"MESH"` → POINTS. Deleted `createSurfaceMesh` / `updateSurfaceMeshPositions` and `tests/MeshSurface.test.js`.
+
+## [1.5.0] - 2026-08-01
+
+### Added
+- **RENDER: RIBBONS + base plane (Etapa E)**:
+  - `MeshFactory.createWideRibbonMesh` / `createBasePlane` — real-width quad strips + translucent ground (no Line linewidth).
+  - `Instancer` mutually exclusive branch for `RIBBONS` (Arithmetic + Compare); compare reorder updates wide ribbons in-situ.
+  - Vitest: `tests/MeshRibbons.test.js`.
+
+## [1.4.0] - 2026-08-01
+
+### Added
+- **RENDER: MESH surface (Etapa D)**:
+  - `MeshFactory.createSurfaceMesh` — indexed quad heightfield (threads × dims), divergent colormap.
+  - `Instancer` branches on `renderMode === 'MESH'` (no Points); Arithmetic + Compare; compare reorder updates surface in-situ.
+  - Vitest: `tests/MeshSurface.test.js`.
+
+## [1.3.0] - 2026-08-01
+
+### Added
+- **Mobile touch navigation (Etapa C)**:
+  - Virtual joystick (move) + canvas finger-drag look + ▲/▼ (Q/E) via `TouchControls` → `Navigation.setMoveAxes` / `applyLookDelta` / `setVertical`.
+  - UI touches on docks/HUD/navbar do not steal look; desktop WASDQE path unchanged (`lerp` §3.1).
+  - Vitest: `tests/TouchControls.test.js`.
+
+## [1.2.0] - 2026-08-01
+
+### Added
+- **Responsive phone layout + landscape-first gate (Etapa B)**:
+  - Soft portrait overlay (`LandscapeGate`) with dismiss → `sessionStorage`; tablet/desktop unaffected; render loop never pauses.
+  - `@media (max-width: 768px)`: compact navbar, ≥44px targets, ≥16px inputs, safe-area insets, docks as overlay drawers.
+  - Vitest coverage in `tests/LandscapeGate.test.js`.
+
+## [1.1.0] - 2026-08-01
+
+### Added
+- **Collapsible side docks (Etapa A)**:
+  - `CollapsibleDock` (`src/ui/CollapsibleDock.js`): left/right docks with edge tabs, ~250ms `transform` slide, no DOM unmount, `aria-expanded` on the tab.
+  - **Left dock**: hosts Arithmetic *or* Compare (MODE). Shared collapsed state across MODE switches (same `localStorage` key `vl3d.dock.left.collapsed`).
+  - **Right dock**: spatial sliders + `AxisGizmo` (D1). Key `vl3d.dock.right.collapsed`.
+  - Desktop persists collapsed in `localStorage`; mobile probe (`max-width: 768px`) defaults collapsed and skips persist (D4 hook for Etapa B).
+  - Bottom telemetry HUD remains always visible (D3).
+  - Vitest coverage in `tests/CollapsibleDock.test.js`.
+
+## [1.0.0] - 2026-08-02
+
+### Added
+- **COMPARE Cosine-vs-Anchor List + 3D Reorder Tween**:
+  - `/compare` response enriched with `anchor` and per-item `cosine_vs_first` (dot product vs L2-normalized first token).
+  - `ComparePanel` scrollable similarity list under ACTIVE SEQUENCE METRICS (`SIMILITUD COSENO vs «…»`), REF badge on #1, per-row ▲/▼ reorder, and header ▼/▲ sort (desc/asc by score, REF stays #1) without camera focus.
+  - Default COMPARE presets use Spanish auto-manual vocabulary (`rueda`, `motor`, `freno`, `volante`, `embrague`, carrocería, fluidos, …); buttons 5/20/50 slice that lexicon.
+  - In-memory score recompute on reorder (no backend re-call); `Instancer.animateCompareReorder` lerps thread layout slots (~320ms ease-out) while reusing ribbon/points meshes; `ThreadLabels.updateOrigins` follows during the tween.
+  - Panel scrollbar invariant preserved: scroll only inside `.compare-cosine-list`.
+- **Camera Pose Overlay (`VITE_SHOW_CAM_POSE`)**: Optional live `POS`/`ROT` HUD for capturing default navigation views. Gated by Vite env var; default `false` (see `.env.example`).
+- **Square / Cube Point GLSL Shader (`src/visualizer/DivergentShading.js`)**:
+  - Replaced circular disc discard in `divergentFragmentShader` with axis-aligned square box distance calculation (`max(coord.x, coord.y)`).
+  - Crisp 1-pixel anti-aliased square bounding edge using `smoothstep(0.44, 0.49, maxDist)` for sharp 3D point cloud rendering.
+- **Vertical Origin Baseline in Analysis Mode (`src/visualizer/Instancer.js` & `MeshFactory.js`)**:
+  - Vertical reference baseline mesh connecting thread origins at $X = \text{startX}$ in Analysis mode.
+  - Rendered with subtle cyan/gold glass opacity (`opacity: 0.6`, `transparent: true`, `frustumCulled: false`).
+- **Dual Workspace Mode Selector (`MODE: [ ARITHMETIC | COMPARE ]`)**:
+  - Navbar top selector buttons `MODE: [ ARITHMETIC | COMPARE ]`.
+  - `ComparePanel` sidebar component (`src/ui/ComparePanel.js`) supporting sequence inputs of **1 to 1024 tokens**.
+  - Fast-loading preset buttons (5, 20, 50 tokens).
+  - Multi-sequence 3D WebGL layout engine in `Instancer.js` (`renderCompareData`).
+- **Backend Batch Compare Endpoint (`/compare`)**:
+  - Pydantic `CompareRequest` accepting 1 to 1024 text/token items.
+  - Fast batch encoding and L2 normalization in `AppState.perform_compare`.
+  - Full Pytest coverage in `backend/tests/test_backend.py`.
+
+### Changed
+- **Default Navigation Camera Pose (`src/engine/Navigation.js`)**: Startup `NAVEGACIÓN` view locked to captured corridor pose `POS (-178.3, 13.5, 52.2)` / `ROT (-5.4°, -51.5°, 0°)` with matching spatial slider defaults (Separación `0.4`, Amplitud `7.0`).
+- **Top-10 UI Space Optimization (`src/ui/Sidebar.js` & `src/style.css`)**:
+  - Removed Top-K dropdown selector from sidebar.
+  - Locked `top_k` parameter to `10` across form inputs and API calls.
+  - Compact Top-10 rows (tighter padding/gap) so the Vector Arithmetic panel fits without a scrollbar; panel uses `height: fit-content` + `overflow: hidden`.
+
+## [0.2.0] - 2026-08-02
+
+### Added
+- **Vista de "Análisis" 3D con Encuadre Frontal y Cartelitos (`src/ui/ThreadLabels.js` & `src/visualizer/LayoutEngine.js`)**:
+  - Vista por defecto al iniciar la app con cámara frontal (`Z=360`) encuadrando todos los hilos vectoriales de frente sin necesidad de desplazarse.
+  - Selector en la Navbar superior: `VISTA: [ ANÁLISIS | NAVEGACIÓN ]` junto al selector de RENDER.
+  - Apilamiento vertical en el eje $Y$ con separación constante para los hilos `word_a`, `word_b`, `word_c` y `res`, manteniendo activaciones $+1$ (hacia arriba) y $-1$ (hacia abajo).
+  - Sliders de control espacial 3D ampliados (`src/ui/ThreadSliders.js`): **Distancia Vectores (Y)** (distancia entre baselines de los 5 hilos) y **Amplitud (Y)** (escalado de la altura de picos $+1$ y valles $-1$ con rango ampliado de $1.0$ a $240.0$).
+  - Inclusión del 5.º hilo `#1 COS VECTOR` posicionado debajo de RESULT VECTOR.
+  - Cartelitos flotantes Glassmorphic vinculados en tiempo real a la proyección 3D del inicio de cada hilo.
+  - Tests unitarios en `tests/ThreadLabels.test.js` y `tests/LayoutEngine.test.js`.
+
+### Changed
+- **Simplificación de Rampas Cromáticas Divergentes por Activación 3D (`src/visualizer/DivergentShading.js`)**:
+  - Eliminación de pasos intermedios de colores Rojo (rango positivo) y Verde (rango negativo) para transicionar directamente desde Negro/Transparente.
+  - Nueva rampa positiva ($0 \rightarrow +1$): Negro (`vec3(0.0)`) $\rightarrow$ Naranja (`#FF8000`) $\rightarrow$ Amarillo Incandescente (`#FFE600`).
+  - Nueva rampa negativa ($0 \rightarrow -1$): Negro (`vec3(0.0)`) $\rightarrow$ Azul Eléctrico (`#0040FF`) $\rightarrow$ Violeta Neón (`#9900E6`).
+  - Optimización computacional GPU/GLSL y CPU para $|t| < 0.01$: retorno directo de opacidad mínima ($\alpha \approx 0.05$) evitando operaciones de interpolación no necesarias.
+  - Cobertura de tests unitarios en `tests/DivergentShading.test.js` actualizada y extendida.
+
+## [0.1.0] - 2026-08-01
+
+### Added
+- **Divergent Activation Shading (`roadmap/archivo/Shading Divergente por Activación.md`)**:
+  - Solid Circular Point GLSL Shader (`src/visualizer/DivergentShading.js`) rendering crisp, solid circular points with 1-pixel anti-aliasing edges instead of blurred halos.
+  - Dual Multi-Stop Color Ramps (`src/visualizer/DivergentShading.js`): Positive range ($0 \rightarrow +1$) transitions Negro $\rightarrow$ Rojo $\rightarrow$ Naranja $\rightarrow$ Amarillo. Negative range ($0 \rightarrow -1$) transitions Negro $\rightarrow$ Verde $\rightarrow$ Azul $\rightarrow$ Violeta.
+  - Full integration in `MeshFactory.js` and `Instancer.js` connecting all 3D thread vector points with continuous ribbon lines.
+  - Integration with `ThreadFactory.js` buffer attributes (`intensity`, `color`) and `frustumCulled = false` invariant.
+  - Real-time spatial control sliders (`src/ui/ThreadSliders.js`) updated with specified ranges ($X \in [0.1, 10.0]$, $Z \in [0.1, 5.0]$, Grosor Puntos $\in [0.1, 1.0]$ con valor por defecto $0.3$).
+  - TDD unit test suite (`tests/DivergentShading.test.js`) verifying multi-stop color ramp math.
+
+- **Thread Geometry & Spatial Sliders 3D (`roadmap/archivo/sliders.md`)**:
+  - Synthetic 3D vector thread data factory (`src/visualizer/ThreadFactory.js`) generating buffer geometries for 3D lines and point nodes.
+  - In-situ GPU Float32Array buffer mutator (`updateAllThreadPositions` in `src/visualizer/LayoutEngine.js`) ensuring zero re-creation of geometries and zero memory leaks.
+  - Interactive spatial control UI panel (`src/ui/ThreadSliders.js`) with real-time 60fps sliders for lateral separation ($X$), longitudinal scale ($Z$), and node thickness.
+  - Pure layout math functions (`executeLayoutMath`) with Vitest test coverage (`tests/LayoutEngine.test.js`).
+  - WebGL scene manager (`src/engine/Scene.js`) with perspective camera, lights, and reference grid at $Y=0$.
+
+- **Backend Core (Phase 1)**:
+  - FastAPI server with lifespan lazy-loading of SentenceTransformer (`all-mpnet-base-v2`).
+  - Pre-computed vocabulary embedding matrix in RAM for fast cosine similarity lookup.
+  - Core API endpoints: `/health`, `/embed`, `/tokenize`, and `/arithmetic` ($A - B + C$).
+  - Vocabulary generator script `scripts/generate_vocab.py` with custom word count and URL source support.
+  - Heartbeat test runner `backend/perform_tests.py`.
+  - Full unit test suite with `pytest`.
+
+- **WebGL 3D Engine & Shaders (Phase 2)**:
+  - Fixed WASD camera flight controller (`src/engine/Navigation.js`) with linear velocity interpolation (`lerp`) and input safety (ignoring keys when focused on UI form inputs and clearing inputs on window blur).
+  - Custom GLSL point shader with glowing incandescent halos and anti-aliased radial smoothing (`src/engine/Shaders.js`).
+  - Three.js 3D scene orchestrator with dark background (`#050505`), fog, and reference grid (`src/engine/SceneSetup.js`).
+  - Inertial flight camera controller with WASDQE, mouse drag look, and Shift turbo acceleration (`src/engine/Navigation.js`).
+  - Raycaster mouse picking for 3D vector points (`src/engine/Interaction.js`).
+  - Spatial 3D layout mapper for vector dimension coordinates $X, Y, Z$ (`src/visualizer/LayoutEngine.js`).
+  - GPU instancing and Mesh factory enforcing `frustumCulled = false` invariant (`src/visualizer/MeshFactory.js` & `Instancer.js`).
+  - Corner 3D orientation axis gizmo (`src/visualizer/AxisGizmo.js`).
+  - Vitest test suite (`npm test`).
+
+- **Control Panel & Hugging Face Deployment (Phase 4)**:
+  - Interactive CLI control panel (`setup.sh`) supporting dev mode, bare-metal server, heartbeat, vitest, pytest, vocabulary management, and HF Spaces deployment.
+  - Custom vocabulary management allowing custom file loads or generation of N words.
+  - Monolithic production Dockerfile for Hugging Face Spaces serving FastAPI on port `7860`.
+  - Static files serving integration in `backend/server.py` for bundled `dist/` production assets.

CONTEXT.md

@@ -0,0 +1,106 @@
+# Context & Domain Model Glossary - VHectorLab 3D
+
+## Ubiquitous Language
+
+### Vector Arithmetic
+Operation calculating a composite semantic vector $V_{res} = V_A - V_B + V_C$ in high-dimensional embedding space.
+
+### Vocabulary Matrix
+Pre-computed L2-normalized array of word embeddings in RAM enabling sub-millisecond similarity search via matrix multiplication.
+
+### Lazy Loading
+Initialization pattern deferring heavy model loading (PyTorch / SentenceTransformer) to the application lifespan startup event, preserving module import speed and clean testability.
+
+### Halo Shader
+WebGL fragment shader rendering glowing incandescence for 3D activation points mapped to vector magnitudes.
+
+### Thread Geometry
+3D vector representations constructed using continuous Three.js `Line` and `Points` buffer geometries to display multi-point activation series over space.
+
+### In-situ Buffer Mutation
+Updating existing GPU `Float32Array` attributes directly and setting `needsUpdate = true`, avoiding geometry re-creation and memory leaks during real-time UI interactions.
+
+### Compare Sequence
+Ordered list of 1–1024 token/text items visualized as parallel 3D threads; list order equals layout `sequenceIndex`.
+
+### Compare Group
+Named block in Compare input (`name = tokens…`) that concatenates members into the sequence and renders a floating group badge at the member-origin centroid (screen-offset left of token labels). Default bootstrap: `it_core` / `vehicles` / `women`. Global cosine sort may interleave groups.
+
+### Anchor Token
+The token currently at position #1 in a Compare Sequence. Cosine similarity for every row is computed against this embedding (`cosine_vs_first`).
+
+### Cosine-vs-First Score
+Dot product between an item’s L2-normalized embedding and the Anchor Token embedding; the anchor row is always `1.0000` (REF).
+
+### Collapsible Dock
+Edge-hosted UI host that slides off-screen via CSS `transform` while keeping children mounted; left dock hosts Arithmetic or Compare, right dock hosts spatial sliders and AxisGizmo. The bottom telemetry HUD is not a dock.
+
+_Avoid_: treating Sidebar/ComparePanel as independent minimize targets; unmounting panel DOM to “hide” it.
+
+### Landscape Gate
+_Retired._ Former soft portrait overlay that suggested landscape; product prefers phone portrait. Do not reintroduce without an explicit ask.
+
+### Field Info Tip
+Compact tap “i” control next to an editable field; shows a short English popover (mobile-safe, not hover-only `title`). Catalog lives in `fieldInfo.js`.
+
+### Wide Ribbon
+Quad-strip mesh with real lateral width following a thread centerline, colored by activation; used by `RENDER: RIBBONS`. Distinct from 1px WebGL lines.
+
+### Visualization Controls
+Bottom-HUD glass panel for global sign filter, divergent color anchors, Zero Coverage, Shared noise (Compare ≥2 tokens), and Group contrast (Compare ≥2 groups).
+
+### Sign Filter
+Global show mode `all | positive | negative` over **normalized** activations (post z-score/tanh); near-zero `|t| < 0.01` is treated as neutral and hidden by +/− only.
+
+### Color Anchor
+User-editable hex for normalized activations at +1, 0, and −1; replaces the former fixed dual mid-stop ramp via linear RGB lerp.
+
+### Zero Coverage
+Percent of the |t| range held at the zero color (default black) before blending toward ±1 anchors; range 30%…100%, edited via A/mA knobs + readout.
+
+### Shared Noise
+Compare paint that blackens dims where **all tokens in view** agree in sign and magnitude (min/max over embeddings; `groupId` ignored). Sits with Zero coverage; Similarity uses the same A/mA coverage chrome. Default OFF.
+
+### Group Contrast
+Visualization paint for Compare with ≥2 groups: **Sign conflict** highlights opposite-sign dims (G1↔G2 means, custom color × |Δ|) and can blacken them by difference; **Group hue** optional. Geometry Y unchanged.
+
+### Workbench Theme
+Default product chrome at `/`: Magic Workbench–inspired palette, Topaz typography, and bevelled panels on the fullscreen + floating-dock layout. Tunable via `VITE_AMIGA_*` in `.env`. Product name remains **VHectorLab 3D**. Value fields use dark fills (not white).
+
+### Galaxy feel
+Galaxy VIEW uses a larger UMAP world scale and a slower flight profile (WASD/QE + mouse look) than ANALYSIS/NAVIGATION; leaving Galaxy restores default speeds. Galaxy POINTS render as soft circular stars.
+
+### Group hue
+Optional Visualization → Group contrast mode: each `GROUP_*` paints black (−1) → a picked color (+1), coexisting with Shared noise / Sign conflict. Default OFF.
+
+_Avoid_: parallel MPA skins (`/v25/`, `/amiga/` — retired in 2.4.1); multi-zone lab grids as the primary layout.
+
+### Shared Noise Similarity
+`1 − |mean_G1 − mean_G2| / (|mean_G1| + |mean_G2|)` per dimension — high values mean shared-sign “noise” between groups.
+
+### Top‑K SAE
+Trained sparse autoencoder with exactly K active latents per input (ReLU + Top‑K, no L1 shrinkage). Trained on the **current workspace scope** (Compare/Arithmetic batch); ephemeral in-RAM session model. Default caps 768 → 8192 with K=32 (auto-scaled for small N).
+
+### Embedding Catalog
+Backend single source of truth (`model_catalog`) listing allowed SentenceTransformer Hub IDs plus flags (E5 mode, trust_remote_code, gated, default truncate).
+
+### Model Profile
+Named local preset (`local-comfort`, `local-full`, `hf-demo`) that resolves to a catalog Hub ID and optional `TRUNCATE_DIM`. Selected only from `setup.sh` option 11 — not from the web UI.
+
+### Active Model
+The one SentenceTransformer loaded in the backend process; exposed on `/health` as `model` / `short_label` / `embedding_dim` / `device` (and `model_profile` when set).
+
+### Truncate Dim
+Optional Matryoshka width (`TRUNCATE_DIM`) applied after encode; effective `embedding_dim` is the truncated width when set.
+
+_Avoid_: generative LLM “embeddings”; multi-model residency; in-app model switcher. HF Space model is pinned in the Dockerfile (currently `local-full` / Arctic @256); changing it needs an explicit approval + republish (option 8).
+
+### Clean/Denoise (SAE)
+Compare-only toggle that replaces raw 768D embeddings with SAE sparse activations for 3D threads and cosine while ON. Requires Train SAE on current Visualize data; scope changes clear the session model. Not available in Arithmetic.
+
+### SAE Feature Space
+Expanded latent dimension (default cap 8192, auto-scaled for small N) used for visualization and metrics while Clean/Denoise is enabled.
+
+### Dead Features
+Latents that never activated on the training set; reported in SAE train metrics.
+

Dockerfile

@@ -0,0 +1,66 @@
+# Monolithic Dockerfile for VHectorLab 3D on Hugging Face Spaces (Port 7860)
+# Target hardware: cpu-basic (2 vCPU / 16 GB / 50 GB) — Arctic-m ~1.2 GB fits.
+# Space profile matches local-full so Shared noise / Compare match the Mac lab.
+FROM python:3.10-slim
+
+# Install system dependencies & Node.js
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    git \
+    build-essential \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install uv for Python package management
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Copy configuration and package files
+COPY package.json package-lock.json ./
+COPY backend/pyproject.toml backend/uv.lock backend/README.md ./backend/
+
+# CPU-only torch on Linux via [tool.uv.sources] → pytorch-cpu (not UV_TORCH_BACKEND / uv sync).
+RUN npm ci
+RUN cd backend && uv sync --frozen
+
+# Copy source code and vocabulary
+COPY . .
+
+# Production frontend bundle (same-origin /api)
+ENV VITE_API_BASE_URL=/api
+RUN npm run build
+
+# Match local-full: Arctic-m-v2 Matryoshka @ 256 + EN∪ES vocab (precompute at image build).
+ENV MODEL_PROFILE=local-full
+ENV MODEL_NAME=Snowflake/snowflake-arctic-embed-m-v2.0
+ENV TRUNCATE_DIM=256
+ENV VOCAB_PATH=public/vocab_en_es.txt
+ENV VOCAB_EMBEDDINGS_PATH=public/vocab_embeddings.npz
+ENV SAE_DEVICE=CPU
+RUN uv run --directory backend --frozen python /app/scripts/precompute_vocab_embeddings.py \
+    --device CPU \
+    --profile local-full \
+    --truncate-dim 256 \
+    --vocab /app/public/vocab_en_es.txt \
+    --out /app/public/vocab_embeddings.npz \
+    --model Snowflake/snowflake-arctic-embed-m-v2.0
+
+# Expose Hugging Face Space default port 7860
+EXPOSE 7860
+
+# Environment variables for Docker / HF Space mode
+ENV HOST=0.0.0.0
+ENV PORT=7860
+ENV UVICORN_RELOAD=0
+ENV MODEL_PROFILE=local-full
+ENV MODEL_NAME=Snowflake/snowflake-arctic-embed-m-v2.0
+ENV TRUNCATE_DIM=256
+ENV VOCAB_PATH=public/vocab_en_es.txt
+ENV VOCAB_EMBEDDINGS_PATH=public/vocab_embeddings.npz
+ENV SAE_DEVICE=CPU
+
+# Entrypoint: FastAPI serving API + static frontend
+CMD ["uv", "run", "--directory", "backend", "--frozen", "python", "-m", "server"]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Hector Bauzan
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -0,0 +1,4 @@
+VHectorLab 3D
+Copyright 2026 Hector Bauzan
+
+This product includes software developed for the VHectorLab 3D study / laboratory tool.

README.md

@@ -0,0 +1,206 @@
+---
+title: VHectorLab 3D
+emoji: 🧭
+colorFrom: gray
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+short_description: VHectorLab 3D - Semantic embeddings study tool in WebGL
+---
+
+# VHectorLab 3D
+
+**A local study / laboratory tool for exploring semantic embeddings in 3D (WebGL). Not a production SaaS.**
+
+
+3D visualization (WebGL/Three.js) and semantic embedding vector arithmetic (`A − B + C`), plus compare sequences and related lab experiments.
+
+| | |
+| :--- | :--- |
+| **License** | [Apache-2.0](./LICENSE) © 2026 Hector Bauzan |
+| **Public demo** | [Hugging Face Space](https://huggingface.co/spaces/hbauzan/llm-semantic-visualizer) |
+| **Local (macOS)** | `./setup.sh` → option `1` → http://127.0.0.1:5173 |
+
+---
+
+## Public demo (no install)
+
+Try the hosted **cpu-basic** demo (same profile as `local-full`: Arctic-m-v2 @ 256-D, EN∪ES vocab):
+
+👉 **https://huggingface.co/spaces/hbauzan/llm-semantic-visualizer**
+
+That Space is a shared study sandbox (Docker, CPU). Expect cold starts, variable latency, and soft resource limits. There is **no SLA**, no multi-tenant isolation, and no auth — please be gentle (avoid automated flooding of `/embed`, `/compare`, `/arithmetic`).
+
+For serious work or heavier SAE/training experiments, run **locally** on macOS (below).
+
+---
+
+## Platform support
+
+**Created and tested on macOS 26.5.1 (Darwin 25.5.0, Apple Silicon).**
+
+This project was **not** prepared or validated for Windows or Linux. It may work there with a few adjustments (package managers, paths, process control), but that is unsupported. Prefer a Mac matching the versions above.
+
+The Hugging Face Space image runs on Linux CPU inside HF’s Docker runtime — that path is supported for the **demo**, not as a general Linux desktop install guide.
+
+---
+
+## Quick start (recommended)
+
+Everything goes through `./setup.sh`. On macOS, **option 1 installs missing tools for you** when needed.
+
+```bash
+# 1. Clone the repo (folder name matches the GitHub repo)
+git clone https://github.com/hbauzan/vhectorlab.git
+cd vhectorlab
+
+# 2. Open the control panel
+chmod +x setup.sh   # first time only, if needed
+./setup.sh
+```
+
+Choose **option `1`** (`Deploy / Start Tool`).
+
+That option will:
+
+1. Probe backend (`:8000`) and frontend (`:5173`): matching process **and** health check
+2. **If both healthy**: skip install/sync, tests, and start; open the browser
+3. **If either is sick** (port/process/health mismatch, e.g. frozen Vite): recycle both (stop + start after tests)
+4. **If only one is healthy**: restart **both** services after prereqs + tests
+5. **If both down**: check/install prerequisites on macOS (`uv`, Homebrew+Node if needed, `.env`, `uv sync`, `npm install` if needed), ensure vocab, run tests, start both, open browser
+6. After a fresh start: stream live backend logs (`Ctrl+C` pauses the tail — services stay up)
+
+App URL when ready:
+
+👉 **http://127.0.0.1:5173** (VHectorLab 3D — Magic Workbench chrome)
+
+- Pause live logs: `Ctrl+C` → **Enter** returns to the menu; **Ctrl+C** again exits the panel (services keep running)
+- Stop services: option **`10`** only (Ctrl+C never stops the stack)
+
+> First run can take a while: it may download Homebrew/Node/`uv`, Python packages, and the embedding model.
+> Re-running option **1** while the stack is already healthy will **not** bounce the servers or re-run tests.
+
+---
+
+## What `setup.sh` expects (and installs on Mac)
+
+| Tool | Role | If missing on macOS |
+| :--- | :--- | :--- |
+| **uv** | Python deps / run backend | Installed via [official uv installer](https://docs.astral.sh/uv/) |
+| **Node.js + npm** | Frontend (Vite / Vitest) | Installed via Homebrew (`brew install node`) |
+| **Homebrew** | Used only to install Node if needed | Installed from [brew.sh](https://brew.sh) |
+| **`.env`** | Runtime config | Copied from `.env.example` |
+| **Backend deps** | FastAPI / PyTorch stack | `uv sync --extra dev` in `backend/` |
+| **Frontend deps** | Three.js / Vite | `npm install` when `node_modules` is absent |
+| **Docker Desktop** | **Optional** — only for option **7** (HF Spaces image build) | Not installed by option 1. Option 7 checks Docker; on macOS it can install the Docker Desktop cask via Homebrew and asks you to start the app |
+
+**Daily local use (option 1) does not need Docker Desktop** — only `uv` + Node/`npm` (+ network).
+
+You do **not** need to install `uv` or Node by hand on a typical Mac — option 1 handles that. You *do* need network access and (for Homebrew) permission to install software.
+
+### Optional: Docker Desktop (option 7)
+
+Install [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop/) if you want to build the Hugging Face Spaces image locally. After install, open Docker Desktop and wait until the engine is running (whale icon steady), then use option **7**.
+
+Option **8** publishes a **Docker** Space on **cpu-basic** via the `hf` CLI. It injects `deploy/hf/space-frontmatter.yml` into the Space README at push time (GitHub `README.md` stays clean) and does **not** require Docker Desktop locally.
+
+---
+
+## `setup.sh` menu
+
+| Option | What it does |
+| :--- | :--- |
+| **1** | Deploy/start: **idempotent** — if both healthy, only open browser; else prereqs→tests→start (**no Docker**) |
+| **2** | Backend only (`:8000`) — **skip if already healthy**; refuse if sick |
+| **3** | System heartbeat / health check |
+| **4** | Frontend unit tests (Vitest) |
+| **5** | Backend unit tests (pytest) |
+| **6** | Vocabulary: load a custom file or generate N words |
+| **7** | Build HF Spaces Docker image locally (torch CPU · optional :7860 smoke) |
+| **8** | Publish HF Space: inject `deploy/hf/space-frontmatter.yml` into README at push (GitHub README stays clean) |
+| **9** | View backend logs |
+| **10** | **Stop** / clean services (always kills; not idempotent) |
+| **0** | Exit |
+
+---
+
+## Environment variables
+
+Copy `.env.example` → `.env` (option 1 does this if `.env` is missing). Common keys:
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `HOST` / `PORT` | `127.0.0.1` / `8000` | Backend listen address |
+| `MODEL_NAME` | `all-mpnet-base-v2` | Embedding model |
+| `VOCAB_PATH` | `public/vocab.txt` | App vocabulary file (use `public/vocab_en_es.txt` for EN∪ES) |
+| `VITE_API_BASE_URL` | `/api` | Browser API base URL |
+| `VITE_SHOW_CAM_POSE` | `false` | Live camera POS/ROT overlay (debug) |
+| `VITE_AMIGA_PEN_0`…`_7` | MagicWB pens | Workbench theme palette pens (`#RRGGBB`) |
+| `VITE_AMIGA_BG` / `_FG` / `_ACCENT` | `#222222` / `#F0F0F0` / `#3B67A2` | Page/panel bg, text, titlebar accent |
+
+### EN + ES vocabulary
+
+Default `public/vocab.txt` is English-only. For multilingual Arithmetic/Compare neighbors:
+
+```bash
+uv run python scripts/merge_vocab_en_es.py
+# → public/vocab_en_es.txt (~10k EN ∪ ES seed; includes king/rey … cat/gato)
+```
+
+Set `VOCAB_PATH=public/vocab_en_es.txt`, then regenerate embeddings (`scripts/precompute_vocab_embeddings.py` or **setup.sh option 11**). Languages beyond EN+ES are out of scope for now.
+
+### Embedding model / profile (setup option 11)
+
+From `./setup.sh` → **11. Select Embedding Model / Profile**: pick `P#` / `M#`, stage `.env`, rebuild `vocab_embeddings.npz` (EN∪ES), restart backend, print `/health`. On failure the previous `.env` is restored. HF Space options 7/8 are unchanged.
+
+Default `.env.example` keeps **`all-mpnet-base-v2`** (EN baseline). Switch to `local-comfort` / `local-full` via option 11 when you want multilingual.
+
+Cross-lingual smoke (after option 11, non-blocking):
+
+```bash
+uv run --directory backend python ../scripts/smoke_crosslingual_cosine.py
+uv run --directory backend python ../scripts/smoke_crosslingual_cosine.py --profile local-comfort --include-fr
+# Fail only if mean EN↔ES cosine is soft-low:
+uv run --directory backend python ../scripts/smoke_crosslingual_cosine.py --strict --threshold 0.35
+```
+
+---
+
+## Manual start (without the panel)
+
+Only if you prefer not to use `setup.sh` (still assumes macOS + tools already available):
+
+```bash
+# Backend
+cd backend
+uv sync --extra dev
+uv run python -m server
+
+# Frontend (another terminal, repo root)
+npm install
+npx vite --port 5173 --host 127.0.0.1
+```
+
+---
+
+## Troubleshooting
+
+| Symptom | What to check |
+| :--- | :--- |
+| Unsupported platform warning | You are not on Darwin/macOS — unsupported; adapt paths/package managers yourself |
+| Homebrew install asks for a password | Normal on first install; approve locally |
+| `uv` / `npm` still missing after option 1 | Open a **new** terminal (PATH refresh), then re-run `./setup.sh` |
+| Backend tests slow / fail on first run | Model download needs network; wait and retry |
+| Browser does not open | Open http://127.0.0.1:5173 manually |
+| Port already in use / option 1 says **sick** | Option 1 now recycles automatically. Or use option `10`, then start again |
+| Option 1 restarts everything every time | It should not when both are healthy — report a bug if it still kills/relaunches a healthy stack |
+| Option 7 fails / “Docker daemon not running” | Install/open **Docker Desktop**, wait until it is running, retry option 7 |
+| `Failed to spawn: pytest` / No such file | Stale `backend/.venv` after renaming the folder. Option 1 now recreates it; or run `rm -rf backend/.venv && cd backend && uv sync --extra dev` |
+
+---
+
+## License
+
+Apache License 2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

architecture_spec.md

@@ -0,0 +1,113 @@
+# Architecture Specification - VHectorLab 3D
+
+## System Architecture
+
+VHectorLab 3D is a 3D semantic vector visualizer and vector arithmetic explorer.
+
+### Backend Tier (`backend/`)
+- **Framework**: FastAPI with Uvicorn.
+- **Model Interface**: Lazy-loaded `SentenceTransformer` via catalog selection (`MODEL_PROFILE` / `MODEL_NAME` / `TRUNCATE_DIM`) in FastAPI `lifespan`. Catalog module: `backend/model_catalog.py` (`resolve_selection_from_env`, `build_model`, `encode_texts`).
+- **Encode adapter**: All query/vocab encoding goes through `encode_texts` (E5 `query:` prefixes when `e5_mode`, optional Matryoshka `truncate_dim`, L2 normalize). Frontend never applies model-specific quirks.
+- **Vocabulary Acceleration**: Pre-computed L2-normalized embedding matrix $(N \times D)$ kept in RAM for instant matrix-vector dot product cosine similarity calculation:
+  $$\text{Sim}(V_{res}, V_{vocab}) = V_{vocab} \cdot V_{res}^T$$
+- **SAE dim safety**: On load, if session SAE `input_dim` ≠ active `embedding_dim`, SAE RAM + checkpoint are cleared automatically.
+- **Vocab NPZ**: Prefer `VOCAB_EMBEDDINGS_PATH` when present. Keys: `words`, `embeddings`, `model_name`, `embedding_dim`, optional `truncate_dim`. **Mismatch strategy**: if `model_name` or effective width disagrees with the active catalog selection, log a loud warning, re-encode from `VOCAB_PATH` via `encode_texts`, and overwrite the NPZ (local DX auto-rebuild — not a hard fail).
+- **CORS Policy**: `allow_origins=["*"]` with `allow_credentials=False` for cross-origin WebGL clients.
+
+### API Surface
+- `GET /health`: Server status, model Hub id, optional `model_profile`, `embedding_dim`, `truncate_dim`, vocabulary size, and runtime `device` (`cpu`|`cuda`|`mps`).
+- `POST /embed`: Computes embedding vector for input text.
+- `POST /tokenize`: Returns tokenization details.
+- `POST /arithmetic`: Computes $V_{res} = V_A - V_B + V_C$ and returns top-$K$ nearest vocabulary words and component vectors.
+- `POST /compare`: Batch-encodes 1–1024 texts, L2-normalizes embeddings, and returns per-item cosine vs the first token (anchor).
+- `POST /project`: Projects precomputed embedding vectors to 2D/3D (does **not** re-encode text). v1 method = **`umap` only**; `pca` / `tsne` → **501**; other methods → **400**. Default seed `42`. When `dim > 50`, internal PCA→50 before UMAP. Positions are zero-mean and RMS-scaled server-side.
+
+### Data Contracts
+
+#### Health
+```json
+{
+  "status": "ok",
+  "model": "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
+  "model_profile": "local-comfort",
+  "short_label": "MiniLM-multi",
+  "embedding_dim": 384,
+  "truncate_dim": null,
+  "device": "mps",
+  "is_loaded": true,
+  "vocab_size": 12345
+}
+```
+`model_profile` / `truncate_dim` / `short_label` may be `null` when unset. `embedding_dim` is the effective width after truncate. Navbar ONLINE chip uses profile (if any) · short_label · `{D}D` · device.
+
+#### Arithmetic
+```json
+{
+  "word_a": "king",
+  "word_b": "man",
+  "word_c": "woman",
+  "top_k": 10
+}
+```
+Returns:
+```json
+{
+  "inputs": {"word_a": "king", "word_b": "man", "word_c": "woman"},
+  "vector_res": [0.01, ..., 0.05],
+  "components": {"vec_a": [...], "vec_b": [...], "vec_c": [...]},
+  "results": [
+    {"word": "queen", "score": 0.892, "token_id": 42}
+  ]
+}
+```
+
+#### Compare
+```json
+{ "texts": ["king", "queen", "man"] }
+```
+Returns:
+```json
+{
+  "count": 3,
+  "anchor": { "index": 0, "text": "king" },
+  "items": [
+    {
+      "id": "tok_0",
+      "index": 0,
+      "text": "king",
+      "embedding": [0.01, "..."],
+      "cosine_vs_first": 1.0
+    }
+  ]
+}
+```
+`cosine_vs_first` is $\text{dot}(\hat{e}_i, \hat{e}_0)$ on L2-normalized embeddings. Frontend reorders may recompute scores in memory without re-calling `/compare`.
+
+#### Project (Galaxy / UMAP)
+```json
+{
+  "vectors": [[0.01, "..."], ["..."]],
+  "method": "umap",
+  "n_components": 3,
+  "seed": 42,
+  "params": { "n_neighbors": 15, "min_dist": 0.1, "metric": "cosine" }
+}
+```
+Constraints: `len(vectors)` ∈ 1..1024; uniform row dim; `n_components` ∈ {2, 3}; `method` = `umap` (green path).
+
+Returns:
+```json
+{
+  "method": "umap",
+  "n_components": 3,
+  "positions": [[x, y, z], "..."],
+  "meta": {
+    "seed": 42,
+    "n_neighbors": 15,
+    "min_dist": 0.1,
+    "metric": "cosine",
+    "pre_pca_dims": 50
+  }
+}
+```
+`meta.pre_pca_dims` is present only when the internal PCA pre-step ran. Encoding stays on `/compare` (or SAE encode); `/project` is additive.

backend/README.md

@@ -0,0 +1,21 @@
+# VHectorLab 3D — Backend
+
+FastAPI service for this **study / laboratory** tool: semantic embeddings, vector arithmetic (`A − B + C`), tokenize, and compare APIs that drive the WebGL UI.
+
+This is **not** a production multi-tenant API. Prefer the [public Hugging Face demo](https://huggingface.co/spaces/hbauzan/llm-semantic-visualizer) for a quick look, or run the full stack locally via the root [`../README.md`](../README.md) (`./setup.sh`).
+
+## Requirements & setup
+
+From this directory (macOS + [`uv`](https://docs.astral.sh/uv/)):
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run python -m server
+```
+
+Default listen address comes from the repo `.env` / `.env.example` (`HOST` / `PORT`, typically `127.0.0.1:8000`).
+
+## License
+
+Apache License 2.0 — see [`../LICENSE`](../LICENSE) and [`../NOTICE`](../NOTICE).

backend/artifacts/.gitignore

@@ -0,0 +1,3 @@
+# SAE checkpoints (large binaries) — train locally; do not commit weights.
+*.pt
+!.gitkeep

backend/artifacts/README.md

@@ -0,0 +1,6 @@
+# SAE artifacts
+
+Compare-scope Top-K SAE checkpoint: `sae_weights.pt` (gitignored).
+
+Created by `POST /api/sae/train`. Deleted by `POST /api/sae/clear` (Retrain confirm in UI).
+Loaded automatically on `/api/sae/status` and `/api/sae/encode`.

backend/crosslingual_smoke.py

@@ -0,0 +1,66 @@
+"""
+Cross-lingual cosine helpers for smoke harness (multillm Slice 7).
+
+Pure math + pair tables — encode happens in the CLI script.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from backend.vocab_merge import DEMO_PAIRS
+
+# Encode-only FR triads (FR need not be in vocab file).
+FR_TRIADS: tuple[tuple[str, str, str], ...] = (
+    ("brother", "hermano", "frère"),
+    ("city", "ciudad", "ville"),
+    ("sun", "sol", "soleil"),
+    ("book", "libro", "livre"),
+    ("truth", "verdad", "vérité"),
+)
+
+DEFAULT_SOFT_THRESHOLD = 0.35
+
+
+@dataclass(frozen=True, slots=True)
+class PairScore:
+    left: str
+    right: str
+    cosine: float
+
+
+def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
+    va = np.asarray(a, dtype=np.float64).reshape(-1)
+    vb = np.asarray(b, dtype=np.float64).reshape(-1)
+    if va.shape != vb.shape:
+        raise ValueError(f"dim mismatch: {va.shape} vs {vb.shape}")
+    na = float(np.linalg.norm(va))
+    nb = float(np.linalg.norm(vb))
+    if na == 0.0 or nb == 0.0:
+        return 0.0
+    return float(np.dot(va, vb) / (na * nb))
+
+
+def score_pairs(
+    embeddings: dict[str, np.ndarray],
+    pairs: tuple[tuple[str, str], ...] = DEMO_PAIRS,
+) -> list[PairScore]:
+    scores: list[PairScore] = []
+    for left, right in pairs:
+        if left not in embeddings or right not in embeddings:
+            raise KeyError(f"missing embedding for pair {left!r}/{right!r}")
+        scores.append(
+            PairScore(
+                left=left,
+                right=right,
+                cosine=cosine_similarity(embeddings[left], embeddings[right]),
+            )
+        )
+    return scores
+
+
+def mean_cosine(scores: list[PairScore]) -> float:
+    if not scores:
+        return 0.0
+    return float(sum(s.cosine for s in scores) / len(scores))

backend/device.py

@@ -0,0 +1,26 @@
+"""Resolve torch runtime device from env (lazy torch import — safe for AppState top-level)."""
+
+from __future__ import annotations
+
+
+def get_optimal_device(env_device: str = "AUTO") -> str:
+    """Resolve device string: AUTO|CPU|CUDA|MPS|GPU → cuda|mps|cpu."""
+    env_device = (env_device or "AUTO").upper().strip()
+    if env_device == "CPU":
+        return "cpu"
+
+    import torch
+
+    if env_device == "CUDA":
+        return "cuda" if torch.cuda.is_available() else "cpu"
+    if env_device == "MPS":
+        if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            return "mps"
+        return "cpu"
+    if env_device in ("GPU", "AUTO"):
+        if torch.cuda.is_available():
+            return "cuda"
+        if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            return "mps"
+        return "cpu"
+    return "cpu"

backend/model_catalog.py

@@ -0,0 +1,442 @@
+"""
+Embedding model catalog — single source of truth for profiles and Hub IDs.
+
+Resolves selection from env, builds SentenceTransformer, and encodes texts
+with E5 prefixes / Matryoshka truncate / L2 norm in one adapter.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass, replace
+from typing import Any
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# Explicit no-go list from roadmap §2.3 (must never appear in list_models).
+NO_GO_HUB_IDS: frozenset[str] = frozenset(
+    {
+        "BAAI/bge-m3",
+        "jinaai/jina-embeddings-v3",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ModelSelection:
+    """Resolved embedding selection for env / setup / AppState (Slice 2+)."""
+
+    hub_id: str
+    profile: str | None
+    trust_remote_code: bool
+    e5_mode: bool
+    truncate_dim: int | None
+    gated: bool
+    short_label: str
+
+
+@dataclass(frozen=True, slots=True)
+class _ModelEntry:
+    hub_id: str
+    short_label: str
+    trust_remote_code: bool = False
+    e5_mode: bool = False
+    default_truncate_dim: int | None = None
+    gated: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ProfileInfo:
+    id: str
+    hub_id: str
+    default_truncate_dim: int | None
+
+
+# §2.1 required + §2.2 inferred extras (order = menu order later).
+_MODELS: tuple[_ModelEntry, ...] = (
+    _ModelEntry(
+        hub_id="sentence-transformers/all-mpnet-base-v2",
+        short_label="EN baseline (mpnet)",
+    ),
+    _ModelEntry(
+        hub_id="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
+        short_label="MiniLM-multi",
+    ),
+    _ModelEntry(
+        hub_id="Snowflake/snowflake-arctic-embed-m-v2.0",
+        short_label="Arctic-m-v2",
+        trust_remote_code=True,
+        default_truncate_dim=256,
+    ),
+    _ModelEntry(
+        hub_id="Alibaba-NLP/gte-multilingual-base",
+        short_label="GTE-multi",
+        trust_remote_code=True,
+    ),
+    _ModelEntry(
+        hub_id="intfloat/multilingual-e5-small",
+        short_label="E5-small-multi",
+        e5_mode=True,
+    ),
+    _ModelEntry(
+        hub_id="google/embeddinggemma-300m",
+        short_label="EmbeddingGemma-300m",
+        gated=True,
+    ),
+    _ModelEntry(
+        hub_id="sentence-transformers/paraphrase-multilingual-mpnet-base-v2",
+        short_label="mpnet-multi",
+    ),
+    _ModelEntry(
+        hub_id="intfloat/multilingual-e5-base",
+        short_label="E5-base-multi",
+        e5_mode=True,
+    ),
+    _ModelEntry(
+        hub_id="sentence-transformers/distiluse-base-multilingual-cased-v2",
+        short_label="distiluse-multi",
+    ),
+)
+
+_MODEL_BY_HUB: dict[str, _ModelEntry] = {m.hub_id: m for m in _MODELS}
+
+# Named profiles (§2.4). Space Docker pins `local-full` (see Dockerfile).
+# `hf-demo` remains a local MiniLM preset (comfort twin), not the live Space model.
+_PROFILES: dict[str, ProfileInfo] = {
+    "local-comfort": ProfileInfo(
+        id="local-comfort",
+        hub_id="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
+        default_truncate_dim=None,
+    ),
+    "local-full": ProfileInfo(
+        id="local-full",
+        hub_id="Snowflake/snowflake-arctic-embed-m-v2.0",
+        default_truncate_dim=256,
+    ),
+    "hf-demo": ProfileInfo(
+        id="hf-demo",
+        hub_id="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
+        default_truncate_dim=None,
+    ),
+}
+
+
+def _selection_from_entry(
+    entry: _ModelEntry,
+    *,
+    profile: str | None,
+    truncate_dim: int | None,
+) -> ModelSelection:
+    return ModelSelection(
+        hub_id=entry.hub_id,
+        profile=profile,
+        trust_remote_code=entry.trust_remote_code,
+        e5_mode=entry.e5_mode,
+        truncate_dim=truncate_dim,
+        gated=entry.gated,
+        short_label=entry.short_label,
+    )
+
+
+def list_models() -> Sequence[ModelSelection]:
+    """Catalog models as ModelSelection with profile=None and entry default truncate."""
+    return tuple(
+        _selection_from_entry(
+            entry,
+            profile=None,
+            truncate_dim=entry.default_truncate_dim,
+        )
+        for entry in _MODELS
+    )
+
+
+def list_profiles() -> Sequence[ProfileInfo]:
+    """Named profiles in stable order: comfort, full, hf-demo."""
+    order = ("local-comfort", "local-full", "hf-demo")
+    return tuple(_PROFILES[pid] for pid in order)
+
+
+def resolve_profile(profile_id: str) -> ModelSelection:
+    """Map a profile id to a full ModelSelection (including default truncate_dim)."""
+    info = _PROFILES.get(profile_id)
+    if info is None:
+        raise ValueError(f"unknown profile: {profile_id!r}")
+    entry = _MODEL_BY_HUB.get(info.hub_id)
+    if entry is None:
+        raise ValueError(
+            f"profile {profile_id!r} maps to missing catalog hub_id {info.hub_id!r}"
+        )
+    return _selection_from_entry(
+        entry,
+        profile=info.id,
+        truncate_dim=info.default_truncate_dim,
+    )
+
+
+def _lookup_entry(hub_id: str) -> _ModelEntry | None:
+    """Exact Hub ID or bare name matching a catalog suffix."""
+    entry = _MODEL_BY_HUB.get(hub_id)
+    if entry is not None:
+        return entry
+    bare = hub_id.split("/")[-1]
+    matches = [m for m in _MODELS if m.hub_id == bare or m.hub_id.endswith("/" + bare)]
+    if len(matches) == 1:
+        return matches[0]
+    return None
+
+
+def get_model(hub_id: str) -> ModelSelection:
+    """Look up a catalog model by Hub ID or bare name (no profile)."""
+    entry = _lookup_entry(hub_id)
+    if entry is None:
+        raise ValueError(f"unknown model: {hub_id!r}")
+    return _selection_from_entry(
+        entry,
+        profile=None,
+        truncate_dim=entry.default_truncate_dim,
+    )
+
+
+def _parse_truncate_dim(raw: str | int | None) -> int | None:
+    if raw is None:
+        return None
+    if isinstance(raw, int):
+        return raw if raw > 0 else None
+    text = str(raw).strip()
+    if not text:
+        return None
+    value = int(text)
+    if value <= 0:
+        raise ValueError(f"TRUNCATE_DIM must be positive, got {value}")
+    return value
+
+
+def _passthrough_selection(hub_id: str, truncate_dim: int | None) -> ModelSelection:
+    """Legacy / unlisted Hub ID — minimal flags inferred from the id string."""
+    lower = hub_id.lower()
+    return ModelSelection(
+        hub_id=hub_id,
+        profile=None,
+        trust_remote_code=False,
+        e5_mode="e5" in lower,
+        truncate_dim=truncate_dim,
+        gated=False,
+        short_label=hub_id.split("/")[-1],
+    )
+
+
+def resolve_selection(
+    *,
+    profile: str | None = None,
+    model_name: str | None = None,
+    truncate_dim: int | None = None,
+) -> ModelSelection:
+    """
+    Resolve ModelSelection from explicit knobs.
+
+    Profile wins over model_name for hub_id. truncate_dim overrides profile/model defaults
+    when provided (including overriding local-full's 256).
+    """
+    if profile and profile.strip():
+        sel = resolve_profile(profile.strip())
+        if truncate_dim is not None:
+            return replace(sel, truncate_dim=truncate_dim)
+        return sel
+
+    name = (model_name or "").strip() or "sentence-transformers/all-mpnet-base-v2"
+    entry = _lookup_entry(name)
+    if entry is None:
+        return _passthrough_selection(name, truncate_dim)
+    sel = _selection_from_entry(
+        entry,
+        profile=None,
+        truncate_dim=entry.default_truncate_dim,
+    )
+    if truncate_dim is not None:
+        return replace(sel, truncate_dim=truncate_dim)
+    return sel
+
+
+def resolve_selection_from_env(
+    *,
+    profile: str | None = None,
+    model_name: str | None = None,
+    truncate_dim: str | int | None = None,
+) -> ModelSelection:
+    """Read MODEL_PROFILE / MODEL_NAME / TRUNCATE_DIM (args override env)."""
+    env_profile = profile if profile is not None else os.getenv("MODEL_PROFILE")
+    env_model = model_name if model_name is not None else os.getenv("MODEL_NAME")
+    if truncate_dim is not None:
+        dim = _parse_truncate_dim(truncate_dim)
+    else:
+        dim = _parse_truncate_dim(os.getenv("TRUNCATE_DIM"))
+    return resolve_selection(
+        profile=env_profile,
+        model_name=env_model,
+        truncate_dim=dim,
+    )
+
+
+def _gte_auto_model(st_model: Any) -> Any | None:
+    """Return the underlying HF auto model for a SentenceTransformer, if present."""
+    try:
+        first = st_model[0]
+    except (TypeError, IndexError, KeyError):
+        return None
+    return getattr(first, "auto_model", None)
+
+
+def _repair_gte_nonpersistent_buffers(st_model: Any) -> None:
+    """
+    Re-init GTE/Arctic non-persistent buffers after transformers 5.x meta load.
+
+    Remote GTE code registers position_ids / RoPE caches with persistent=False but
+    does not restore them in _init_weights. transformers≥5 materializes on meta and
+    leaves those buffers as uninitialized / zero storage → RoPE NaNs or IndexError.
+    See HF transformers#43644 / #43950.
+    """
+    import torch
+
+    auto = _gte_auto_model(st_model)
+    if auto is None:
+        return
+    embeddings = getattr(auto, "embeddings", None)
+    if embeddings is None:
+        return
+
+    position_ids = getattr(embeddings, "position_ids", None)
+    if isinstance(position_ids, torch.Tensor) and position_ids.numel() > 0:
+        expected = torch.arange(
+            position_ids.numel(),
+            device=position_ids.device,
+            dtype=position_ids.dtype,
+        )
+        if not torch.equal(position_ids, expected):
+            embeddings.register_buffer(
+                "position_ids", expected, persistent=False
+            )
+            logger.info("Repaired GTE embeddings.position_ids after meta load")
+
+    rotary = getattr(embeddings, "rotary_emb", None)
+    if rotary is None:
+        return
+    dim = int(getattr(rotary, "dim", 0) or 0)
+    base = float(getattr(rotary, "base", 10000.0) or 10000.0)
+    max_pos = int(
+        getattr(rotary, "max_position_embeddings", 0)
+        or getattr(auto.config, "max_position_embeddings", 0)
+        or 0
+    )
+    if dim <= 0 or max_pos <= 0:
+        return
+    device = next(auto.parameters()).device
+    inv_freq = 1.0 / (
+        base ** (torch.arange(0, dim, 2, device=device, dtype=torch.float32) / dim)
+    )
+    rotary.register_buffer("inv_freq", inv_freq, persistent=False)
+    # Prefer the module's own cache builder (covers NTKScalingRotaryEmbedding).
+    if hasattr(rotary, "_set_cos_sin_cache"):
+        rotary._set_cos_sin_cache(
+            seq_len=max_pos,
+            device=device,
+            dtype=torch.get_default_dtype(),
+        )
+    logger.info("Repaired GTE rotary_emb buffers after meta load")
+
+
+def build_model(selection: ModelSelection, device: str) -> Any:
+    """Construct SentenceTransformer for the selection (trust_remote_code when declared).
+
+    Arctic (GTE remote code) ships with use_memory_efficient_attention=true and
+    unpad_inputs=true, which hard-require xformers. That package is often
+    unavailable on macOS/MPS and unnecessary for lab encode workloads, so we
+    force both flags off via config_kwargs. Also repairs non-persistent RoPE /
+    position buffers corrupted by transformers≥5 meta-device loading.
+    """
+    from sentence_transformers import SentenceTransformer
+
+    kwargs: dict[str, Any] = {"device": device}
+    if selection.trust_remote_code:
+        kwargs["trust_remote_code"] = True
+        # Arctic Hub config: use_memory_efficient_attention=true (+ unpad_inputs)
+        # hard-requires xformers; without MEA, unpad+RoPE blows up on encode.
+        # Force both off for CPU/MPS/lab loads (HF discussion #15).
+        kwargs["config_kwargs"] = {
+            "use_memory_efficient_attention": False,
+            "unpad_inputs": False,
+        }
+    logger.info(
+        "Building SentenceTransformer hub_id=%s trust_remote_code=%s device=%s",
+        selection.hub_id,
+        selection.trust_remote_code,
+        device,
+    )
+    model = SentenceTransformer(selection.hub_id, **kwargs)
+    if selection.trust_remote_code:
+        _repair_gte_nonpersistent_buffers(model)
+    return model
+
+
+def _apply_e5_prefixes(texts: Sequence[str]) -> list[str]:
+    """Symmetric lab tasks use query: for all strings (E5 STS guidance)."""
+    out: list[str] = []
+    for text in texts:
+        t = text.strip()
+        if t.startswith(("query:", "passage:")):
+            out.append(t)
+        else:
+            out.append(f"query: {t}")
+    return out
+
+
+def _l2_normalize(matrix: np.ndarray) -> np.ndarray:
+    if matrix.ndim == 1:
+        norm = float(np.linalg.norm(matrix))
+        if norm == 0:
+            norm = 1e-9
+        return (matrix / norm).astype(np.float32, copy=False)
+    norms = np.linalg.norm(matrix, axis=1, keepdims=True)
+    norms[norms == 0] = 1e-9
+    return (matrix / norms).astype(np.float32, copy=False)
+
+
+def encode_texts(
+    model: Any,
+    texts: str | Sequence[str],
+    selection: ModelSelection,
+    *,
+    show_progress_bar: bool = False,
+) -> np.ndarray:
+    """
+    Encode via the catalog adapter: optional E5 prefixes, truncate_dim, L2 normalize.
+
+    Single string → 1-D float32 vector; sequence → 2-D (N, D).
+    """
+    single = isinstance(texts, str)
+    batch: list[str] = [texts] if single else [str(t) for t in texts]
+    if selection.e5_mode:
+        batch = _apply_e5_prefixes(batch)
+
+    raw = model.encode(
+        batch, show_progress_bar=show_progress_bar, convert_to_numpy=True
+    )
+    arr = np.asarray(raw, dtype=np.float32)
+    if arr.ndim == 1:
+        arr = arr.reshape(1, -1)
+
+    if selection.truncate_dim is not None:
+        dim = selection.truncate_dim
+        if dim > arr.shape[1]:
+            raise ValueError(
+                f"truncate_dim={dim} exceeds model embedding width {arr.shape[1]}"
+            )
+        arr = arr[:, :dim]
+
+    arr = _l2_normalize(arr)
+    if single:
+        return arr[0]
+    return arr

backend/model_swap.py

@@ -0,0 +1,552 @@
+"""
+Embedding model swap helpers for setup.sh option 11.
+
+Stage .env → precompute vocab NPZ → commit on success; restore backup on failure.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from backend.model_catalog import (
+    ModelSelection,
+    get_model,
+    list_models,
+    list_profiles,
+    resolve_profile,
+    resolve_selection,
+)
+from backend.progress_cli import print_fail, print_ok, print_phase
+from backend.vocab_merge import merge_en_es_files
+
+_ENV_KEY_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
+
+# ANSI (safe for most terminals used with setup.sh)
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+_CYAN = "\033[36m"
+_MAGENTA = "\033[35m"
+_GREEN = "\033[32m"
+_YELLOW = "\033[33m"
+_RESET = "\033[0m"
+
+
+@dataclass(frozen=True, slots=True)
+class EnvSnapshot:
+    path: Path
+    backup_path: Path | None
+
+
+@dataclass(frozen=True, slots=True)
+class MenuEntry:
+    """One selectable row in option 11."""
+
+    index: int
+    token: str  # P1 / M3 / etc.
+    kind: str  # profile | model
+    selection: ModelSelection
+    title: str
+    subtitle: str
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def read_dotenv(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    if not path.is_file():
+        return values
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        match = _ENV_KEY_RE.match(stripped)
+        if not match:
+            continue
+        key, raw = match.group(1), match.group(2)
+        if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in ("'", '"'):
+            raw = raw[1:-1]
+        values[key] = raw
+    return values
+
+
+def apply_dotenv(path: Path, *, override: bool = False) -> dict[str, str]:
+    """
+    Load KEY=VAL from a .env file into os.environ.
+
+    By default does not override variables already set in the process environment
+    (explicit exports / systemd / CI win). Used by the backend so option 1 and
+    option 11 honor the repo-root `.env` even when `uv run` cwd is `backend/`.
+    """
+    values = read_dotenv(path)
+    for key, value in values.items():
+        if override or key not in os.environ:
+            os.environ[key] = value
+    return values
+
+
+def upsert_dotenv(path: Path, updates: dict[str, str | None]) -> None:
+    """
+    Upsert keys in a .env file. Value None removes the key line.
+    Preserves unrelated lines/comments; appends missing keys at end.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines: list[str] = []
+    if path.is_file():
+        lines = path.read_text(encoding="utf-8").splitlines()
+
+    seen: set[str] = set()
+    out: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        match = (
+            _ENV_KEY_RE.match(stripped)
+            if stripped and not stripped.startswith("#")
+            else None
+        )
+        if match is None:
+            out.append(line)
+            continue
+        key = match.group(1)
+        if key not in updates:
+            out.append(line)
+            continue
+        seen.add(key)
+        value = updates[key]
+        if value is None:
+            continue
+        out.append(f"{key}={value}")
+
+    for key, value in updates.items():
+        if key in seen or value is None:
+            continue
+        out.append(f"{key}={value}")
+
+    text = "\n".join(out)
+    if text and not text.endswith("\n"):
+        text += "\n"
+    path.write_text(text, encoding="utf-8")
+
+
+def stage_env(path: Path, updates: dict[str, str | None]) -> EnvSnapshot:
+    backup = path.with_suffix(path.suffix + ".multillm.bak")
+    if path.is_file():
+        shutil.copy2(path, backup)
+    else:
+        backup.write_text("", encoding="utf-8")
+        path.write_text("", encoding="utf-8")
+    upsert_dotenv(path, updates)
+    return EnvSnapshot(path=path, backup_path=backup)
+
+
+def commit_env(snapshot: EnvSnapshot) -> None:
+    if snapshot.backup_path and snapshot.backup_path.is_file():
+        snapshot.backup_path.unlink()
+
+
+def rollback_env(snapshot: EnvSnapshot) -> None:
+    if snapshot.backup_path is None:
+        return
+    if snapshot.backup_path.is_file():
+        shutil.copy2(snapshot.backup_path, snapshot.path)
+        snapshot.backup_path.unlink()
+
+
+def resolve_choice(
+    *, profile: str | None = None, model: str | None = None
+) -> ModelSelection:
+    if profile:
+        return resolve_profile(profile)
+    if model:
+        try:
+            return get_model(model)
+        except ValueError:
+            return resolve_selection(model_name=model)
+    raise ValueError("Provide --profile or --model")
+
+
+def ensure_en_es_vocab(root: Path | None = None) -> Path:
+    root = root or repo_root()
+    out = root / "public" / "vocab_en_es.txt"
+    en = root / "public" / "vocab.txt"
+    es = root / "public" / "vocab_es.txt"
+    if not out.is_file():
+        merge_en_es_files(en, es, out)
+    return out
+
+
+def selection_env_updates(
+    selection: ModelSelection, *, vocab_path: str
+) -> dict[str, str | None]:
+    truncate = str(selection.truncate_dim) if selection.truncate_dim is not None else ""
+    return {
+        "MODEL_PROFILE": selection.profile or "",
+        "MODEL_NAME": selection.hub_id,
+        "TRUNCATE_DIM": truncate,
+        "VOCAB_PATH": vocab_path,
+    }
+
+
+def run_precompute(
+    selection: ModelSelection,
+    *,
+    root: Path | None = None,
+    vocab_path: Path,
+    out_path: Path,
+    device: str = "AUTO",
+) -> None:
+    """Run precompute with live stdout/stderr (tqdm + phase logs visible)."""
+    root = root or repo_root()
+    cmd = [
+        "uv",
+        "run",
+        "python",
+        str(root / "scripts" / "precompute_vocab_embeddings.py"),
+        "--model",
+        selection.hub_id,
+        "--vocab",
+        str(vocab_path),
+        "--out",
+        str(out_path),
+        "--device",
+        device,
+    ]
+    if selection.profile:
+        cmd.extend(["--profile", selection.profile])
+    if selection.truncate_dim is not None:
+        cmd.extend(["--truncate-dim", str(selection.truncate_dim)])
+    env = os.environ.copy()
+    env.setdefault("PYTHONUNBUFFERED", "1")
+    completed = subprocess.run(
+        cmd,
+        cwd=str(root),
+        env=env,
+        check=False,
+    )
+    if completed.returncode != 0:
+        raise RuntimeError(f"precompute failed (exit {completed.returncode})")
+
+
+def apply_model_swap(
+    selection: ModelSelection,
+    *,
+    root: Path | None = None,
+    env_path: Path | None = None,
+    device: str = "AUTO",
+    skip_precompute: bool = False,
+    quiet: bool = False,
+) -> ModelSelection:
+    """
+    Stage .env, ensure EN∪ES vocab, precompute NPZ, commit env.
+    Rolls back .env on any failure after staging.
+    """
+    root = root or repo_root()
+    env_path = env_path or (root / ".env")
+    total = 4 if not skip_precompute else 3
+    step = 0
+
+    def _phase(title: str, detail: str = "") -> None:
+        nonlocal step
+        step += 1
+        if not quiet:
+            print_phase(step, total, title, detail=detail)
+
+    _phase(
+        "Ensure EN∪ES vocabulary",
+        detail="public/vocab_en_es.txt (merge if missing)",
+    )
+    vocab_en_es = ensure_en_es_vocab(root)
+    if not quiet:
+        n_words = sum(1 for line in vocab_en_es.open(encoding="utf-8") if line.strip())
+        print_ok(f"Vocab ready — {n_words} words at {vocab_en_es.name}")
+
+    vocab_rel = "public/vocab_en_es.txt"
+    npz_rel = read_dotenv(env_path).get(
+        "VOCAB_EMBEDDINGS_PATH", "public/vocab_embeddings.npz"
+    )
+    updates = selection_env_updates(selection, vocab_path=vocab_rel)
+
+    _phase(
+        "Stage .env (backup → write)",
+        detail=f"MODEL_NAME={selection.hub_id}",
+    )
+    snapshot = stage_env(env_path, updates)
+    if not quiet:
+        print_ok(f"Staged {env_path.name} (rollback available on failure)")
+
+    try:
+        if not skip_precompute:
+            _phase(
+                "Precompute vocab embeddings NPZ",
+                detail="download/load model + encode (progress bar below)",
+            )
+            run_precompute(
+                selection,
+                root=root,
+                vocab_path=vocab_en_es,
+                out_path=root / npz_rel,
+                device=device,
+            )
+            if not quiet:
+                print_ok(f"NPZ written → {npz_rel}")
+
+        _phase("Commit .env (drop backup)")
+        commit_env(snapshot)
+        if not quiet:
+            print_ok("Environment committed")
+            print()
+            trunc = (
+                selection.truncate_dim
+                if selection.truncate_dim is not None
+                else "—"
+            )
+            print(
+                f"  {_GREEN}{_BOLD}Swap prepare OK{_RESET}  "
+                f"model={selection.short_label}  "
+                f"profile={selection.profile or '—'}  "
+                f"truncate={trunc}"
+            )
+    except Exception:
+        if not quiet:
+            print_fail("Failure — restoring previous .env")
+        rollback_env(snapshot)
+        raise
+    return selection
+
+
+def _entry_subtitle(sel: ModelSelection, *, kind: str) -> str:
+    bits: list[str] = []
+    if kind == "profile" and sel.profile:
+        bits.append(sel.profile)
+    hub_short = sel.hub_id.split("/")[-1]
+    bits.append(hub_short)
+    if sel.truncate_dim is not None:
+        bits.append(f"MRL→{sel.truncate_dim}D")
+    if sel.e5_mode:
+        bits.append("E5")
+    if sel.gated:
+        bits.append("gated")
+    if sel.trust_remote_code:
+        bits.append("trust_remote")
+    return " · ".join(bits)
+
+
+def build_menu_entries() -> list[MenuEntry]:
+    entries: list[MenuEntry] = []
+    idx = 1
+    for i, p in enumerate(list_profiles(), start=1):
+        sel = resolve_profile(p.id)
+        entries.append(
+            MenuEntry(
+                index=idx,
+                token=f"P{i}",
+                kind="profile",
+                selection=sel,
+                title=sel.short_label,
+                subtitle=_entry_subtitle(sel, kind="profile"),
+            )
+        )
+        idx += 1
+    for i, m in enumerate(list_models(), start=1):
+        entries.append(
+            MenuEntry(
+                index=idx,
+                token=f"M{i}",
+                kind="model",
+                selection=m,
+                title=m.short_label,
+                subtitle=_entry_subtitle(m, kind="model"),
+            )
+        )
+        idx += 1
+    return entries
+
+
+def format_menu_lines(*, color: bool = True) -> list[str]:
+    """Pretty catalog listing for option 11 (profiles then models)."""
+    b = _BOLD if color else ""
+    d = _DIM if color else ""
+    c = _CYAN if color else ""
+    m = _MAGENTA if color else ""
+    g = _GREEN if color else ""
+    y = _YELLOW if color else ""
+    r = _RESET if color else ""
+
+    entries = build_menu_entries()
+    lines: list[str] = []
+    lines.append(f"{c}{b}╭────────────────────────────────────────────────────────────╮{r}")
+    lines.append(f"{c}{b}│{r}  {b}Embedding profiles{r}  {d}(recommended presets){r}")
+    lines.append(f"{c}{b}╰────────────────────────────────────────────────────────────╯{r}")
+
+    for e in entries:
+        if e.kind != "profile":
+            continue
+        mark = f"{g}★{r}" if color else "*"
+        lines.append(
+            f"  {b}{e.index:>2}){r} {mark} {m}{e.token:<4}{r}  "
+            f"{b}{e.title:<22}{r}  {d}{e.subtitle}{r}"
+        )
+
+    lines.append("")
+    lines.append(f"{c}{b}╭────────────────────────────────────────────────────────────╮{r}")
+    lines.append(f"{c}{b}│{r}  {b}Catalog models{r}  {d}(pick any one){r}")
+    lines.append(f"{c}{b}╰────────────────────────────────────────────────────────────╯{r}")
+
+    for e in entries:
+        if e.kind != "model":
+            continue
+        lines.append(
+            f"  {b}{e.index:>2}){r}   {y}{e.token:<4}{r}  "
+            f"{b}{e.title:<22}{r}  {d}{e.subtitle}{r}"
+        )
+
+    lines.append("")
+    lines.append(f"  {b} 0){r}  {d}Cancel{r}")
+    lines.append(
+        f"  {d}Enter a number (1–{entries[-1].index}), or P# / M# token.{r}"
+    )
+    return lines
+
+
+def selection_from_menu_token(token: str) -> ModelSelection:
+    raw = token.strip()
+    if not raw:
+        raise ValueError("empty choice")
+
+    if raw.isdigit():
+        n = int(raw)
+        for e in build_menu_entries():
+            if e.index == n:
+                return e.selection
+        raise ValueError(f"unknown menu index: {n}")
+
+    t = raw.upper()
+    profiles = list(list_profiles())
+    models = list(list_models())
+    if t.startswith("P") and t[1:].isdigit():
+        idx = int(t[1:]) - 1
+        if 0 <= idx < len(profiles):
+            return resolve_profile(profiles[idx].id)
+    if t.startswith("M") and t[1:].isdigit():
+        idx = int(t[1:]) - 1
+        if 0 <= idx < len(models):
+            return models[idx]
+    lower = raw
+    try:
+        return resolve_profile(lower)
+    except ValueError:
+        pass
+    return resolve_choice(model=lower)
+
+
+def describe_selection(selection: ModelSelection) -> str:
+    trunc = (
+        str(selection.truncate_dim) if selection.truncate_dim is not None else "—"
+    )
+    return (
+        f"{selection.short_label}  ·  profile={selection.profile or '—'}  "
+        f"·  truncate={trunc}  ·  {selection.hub_id}"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    list_p = sub.add_parser("list", help="Print profiles + catalog short labels")
+    list_p.add_argument(
+        "--plain",
+        action="store_true",
+        help="Disable ANSI colors",
+    )
+
+    apply_p = sub.add_parser(
+        "apply", help="Stage env, precompute, commit (or rollback)"
+    )
+    apply_p.add_argument("--profile", default=None)
+    apply_p.add_argument("--model", default=None)
+    apply_p.add_argument("--choice", default=None, help="Menu token e.g. P1 / M3 / 2")
+    apply_p.add_argument("--device", default=os.getenv("SAE_DEVICE", "AUTO"))
+    apply_p.add_argument(
+        "--skip-precompute",
+        action="store_true",
+        help="Only upsert .env (tests / dry wiring)",
+    )
+    apply_p.add_argument("--env", type=Path, default=None)
+    apply_p.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress phase progress (tests)",
+    )
+
+    describe_p = sub.add_parser(
+        "describe", help="Resolve a choice and print a one-line summary"
+    )
+    describe_p.add_argument("--choice", required=True)
+
+    args = parser.parse_args(argv)
+    root = repo_root()
+
+    if args.cmd == "list":
+        print("\n".join(format_menu_lines(color=not args.plain)))
+        return 0
+
+    if args.cmd == "describe":
+        try:
+            selection = selection_from_menu_token(args.choice)
+        except Exception as exc:  # noqa: BLE001
+            print(f"ERROR: {exc}", file=sys.stderr)
+            return 1
+        print(describe_selection(selection))
+        return 0
+
+    if args.cmd == "apply":
+        if args.choice:
+            selection = selection_from_menu_token(args.choice)
+        else:
+            selection = resolve_choice(profile=args.profile, model=args.model)
+        env_path = args.env or (root / ".env")
+        if not args.quiet:
+            print()
+            print(f"  {_BOLD}Target{_RESET}: {describe_selection(selection)}")
+            print(
+                f"  {_DIM}Pipeline: vocab → stage .env → encode NPZ → commit{_RESET}"
+            )
+            print()
+        try:
+            apply_model_swap(
+                selection,
+                root=root,
+                env_path=env_path,
+                device=args.device,
+                skip_precompute=args.skip_precompute,
+                quiet=args.quiet,
+            )
+        except Exception as exc:  # noqa: BLE001
+            print(f"ERROR: {exc}", file=sys.stderr)
+            if "gated" in selection.hub_id.lower() or selection.gated:
+                print(
+                    "Gated model tip: run `hf auth login` and accept the model license on Hugging Face.",
+                    file=sys.stderr,
+                )
+            return 1
+        print(
+            f"OK model={selection.hub_id} profile={selection.profile!r} "
+            f"truncate_dim={selection.truncate_dim!r}"
+        )
+        return 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

backend/perform_tests.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""
+System Heartbeat and Diagnostic Runner for VHectorLab 3D.
+Tests /health and /arithmetic endpoints locally using httpx or direct state.
+"""
+
+import logging
+import sys
+
+import httpx
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("heartbeat")
+
+
+def run_heartbeat(base_url: str = "http://127.0.0.1:8000") -> bool:
+    logger.info(f"Running System Heartbeat against {base_url}...")
+
+    try:
+        # 1. Health check
+        health_resp = httpx.get(f"{base_url}/health", timeout=5.0)
+        if health_resp.status_code != 200:
+            logger.error(
+                f"Health check failed with status {health_resp.status_code}: {health_resp.text}"
+            )
+            return False
+
+        health_data = health_resp.json()
+        logger.info(f"Health check OK: {health_data}")
+
+        # 2. Arithmetic check (king - man + woman)
+        payload = {"word_a": "king", "word_b": "man", "word_c": "woman", "top_k": 5}
+        arith_resp = httpx.post(f"{base_url}/arithmetic", json=payload, timeout=15.0)
+        if arith_resp.status_code != 200:
+            logger.error(
+                f"Arithmetic test failed with status {arith_resp.status_code}: {arith_resp.text}"
+            )
+            return False
+
+        arith_data = arith_resp.json()
+        results = arith_data.get("results", [])
+        logger.info("Arithmetic test OK! Top results for 'king - man + woman':")
+        for res in results:
+            logger.info(f"  - {res['word']} (score: {res['score']:.4f})")
+
+        return True
+    except Exception as e:  # noqa: BLE001
+        logger.error(f"Heartbeat connection error: {e}")
+        return False
+
+
+if __name__ == "__main__":
+    url = sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:8000"
+    success = run_heartbeat(url)
+    sys.exit(0 if success else 1)

backend/progress_cli.py

@@ -0,0 +1,36 @@
+"""Terminal progress helpers for operator-facing CLIs (option 11, precompute)."""
+
+from __future__ import annotations
+
+import sys
+
+
+def progress_bar(current: int, total: int, *, width: int = 28) -> str:
+    total = max(int(total), 1)
+    current = max(0, min(int(current), total))
+    filled = round(width * current / total)
+    filled = max(0, min(filled, width))
+    return "█" * filled + "░" * (width - filled)
+
+
+def print_phase(
+    current: int,
+    total: int,
+    title: str,
+    *,
+    detail: str = "",
+    file=sys.stdout,
+) -> None:
+    bar = progress_bar(current, total)
+    line = f"  [{bar}]  {current}/{total}  {title}"
+    print(line, file=file, flush=True)
+    if detail:
+        print(f"           {detail}", file=file, flush=True)
+
+
+def print_ok(message: str, *, file=sys.stdout) -> None:
+    print(f"  ✓  {message}", file=file, flush=True)
+
+
+def print_fail(message: str, *, file=sys.stderr) -> None:
+    print(f"  ✗  {message}", file=file, flush=True)

backend/projection.py

@@ -0,0 +1,203 @@
+"""
+Dimensionality reduction for Galaxy VIEW.
+
+Deep seam: project_embeddings(vectors, ...) → positions + meta.
+UMAP only in v1; PCA/t-SNE raise ProjectError(501).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+PRE_PCA_DIMS = 50
+MAX_VECTORS = 1024
+DEFAULT_N_NEIGHBORS = 15
+DEFAULT_MIN_DIST = 0.1
+DEFAULT_METRIC = "cosine"
+
+
+class ProjectError(Exception):
+    """Validation / capability error with HTTP-ish status code."""
+
+    def __init__(self, message: str, status_code: int = 400) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+
+def _as_matrix(vectors: list[list[float]] | np.ndarray) -> np.ndarray:
+    if isinstance(vectors, np.ndarray):
+        mat = np.asarray(vectors, dtype=np.float64)
+    else:
+        if not vectors:
+            raise ProjectError("vectors list cannot be empty (need 1..1024)")
+        lengths = {len(row) for row in vectors}
+        if len(lengths) != 1:
+            raise ProjectError("all vectors must have the same dimension")
+        if next(iter(lengths)) < 1:
+            raise ProjectError("vector dimension must be >= 1")
+        mat = np.asarray(vectors, dtype=np.float64)
+
+    if mat.ndim != 2:
+        raise ProjectError("vectors must be a 2D matrix [n, dim]")
+    n, dim = mat.shape
+    if n < 1 or n > MAX_VECTORS:
+        raise ProjectError(f"len(vectors) must be in 1..{MAX_VECTORS}, got {n}")
+    if dim < 1:
+        raise ProjectError("vector dimension must be >= 1")
+    if not np.isfinite(mat).all():
+        raise ProjectError("vectors must contain only finite values")
+    return mat
+
+
+def _normalize_positions(pos: np.ndarray) -> np.ndarray:
+    """Zero-mean; scale so RMS distance from origin is 1 (stable camera defaults)."""
+    centered = pos - pos.mean(axis=0, keepdims=True)
+    rms = float(np.sqrt(np.mean(np.sum(centered**2, axis=1))))
+    if rms < 1e-12:
+        return centered
+    return centered / rms
+
+
+def _project_small_n(
+    mat: np.ndarray, *, n_components: int, seed: int
+) -> tuple[np.ndarray, dict[str, Any]]:
+    """
+    Deterministic layout when UMAP cannot run (n < 3).
+
+    n=1 → origin; n=2 → PCA to 1D padded to n_components (pair on an axis).
+    """
+    n_samples, dim = mat.shape
+    if n_samples == 1:
+        pos = np.zeros((1, n_components), dtype=np.float64)
+        return pos, {"fallback": "origin"}
+
+    from sklearn.decomposition import PCA
+
+    k = min(n_samples - 1, n_components, dim)
+    if k < 1:
+        pos = np.zeros((n_samples, n_components), dtype=np.float64)
+        return pos, {"fallback": "origin"}
+
+    reduced = PCA(n_components=k, random_state=seed).fit_transform(mat)
+    pos = np.zeros((n_samples, n_components), dtype=np.float64)
+    pos[:, :k] = reduced
+    return pos, {"fallback": "pca_micro", "pca_components": int(k)}
+
+
+def _resolve_umap_params(
+    n_samples: int, params: dict[str, Any] | None
+) -> dict[str, Any]:
+    raw = params or {}
+    n_neighbors = int(raw.get("n_neighbors", DEFAULT_N_NEIGHBORS))
+    min_dist = float(raw.get("min_dist", DEFAULT_MIN_DIST))
+    metric = str(raw.get("metric", DEFAULT_METRIC))
+
+    # UMAP requires n_neighbors < n_samples
+    max_nn = max(2, n_samples - 1)
+    n_neighbors = max(n_neighbors, 2)
+    n_neighbors = min(n_neighbors, max_nn)
+
+    if min_dist < 0.0:
+        raise ProjectError("params.min_dist must be >= 0")
+
+    return {
+        "n_neighbors": n_neighbors,
+        "min_dist": min_dist,
+        "metric": metric,
+    }
+
+
+def project_embeddings(
+    vectors: list[list[float]] | np.ndarray,
+    *,
+    method: str = "umap",
+    n_components: int = 3,
+    seed: int = 42,
+    params: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    Project embedding rows to 2D/3D.
+
+    Returns:
+        { method, n_components, positions, meta }
+    """
+    method_l = (method or "").strip().lower()
+    if method_l in ("pca", "tsne"):
+        raise ProjectError(
+            f"method '{method_l}' is not implemented yet; use 'umap'",
+            status_code=501,
+        )
+    if method_l != "umap":
+        raise ProjectError(
+            f"unsupported method '{method}'; v1 accepts 'umap' only "
+            "(pca/tsne coming later)",
+            status_code=400,
+        )
+
+    if n_components not in (2, 3):
+        raise ProjectError("n_components must be 2 or 3")
+
+    mat = _as_matrix(vectors)
+    n_samples, dim = mat.shape
+
+    # UMAP needs ≥3 samples; 1–2 tokens still valid in Token Comparison / Galaxy.
+    if n_samples < 3:
+        embedded, fallback_meta = _project_small_n(
+            mat, n_components=n_components, seed=seed
+        )
+        positions = _normalize_positions(np.asarray(embedded, dtype=np.float64))
+        return {
+            "method": "umap",
+            "n_components": n_components,
+            "positions": positions.tolist(),
+            "meta": {"seed": seed, **fallback_meta},
+        }
+
+    umap_params = _resolve_umap_params(n_samples, params)
+    pre_pca_dims: int | None = None
+    work = mat
+
+    if dim > PRE_PCA_DIMS:
+        from sklearn.decomposition import PCA
+
+        pca_dims = min(PRE_PCA_DIMS, n_samples - 1, dim)
+        if pca_dims < n_components:
+            raise ProjectError(
+                f"cannot pre-reduce: need at least {n_components} PCA dims "
+                f"(n={n_samples}, dim={dim})"
+            )
+        pca = PCA(n_components=pca_dims, random_state=seed)
+        work = pca.fit_transform(mat)
+        pre_pca_dims = pca_dims
+
+    import umap
+
+    reducer = umap.UMAP(
+        n_components=n_components,
+        n_neighbors=umap_params["n_neighbors"],
+        min_dist=umap_params["min_dist"],
+        metric=umap_params["metric"],
+        random_state=seed,
+        n_jobs=1,
+    )
+    embedded = reducer.fit_transform(work)
+    positions = _normalize_positions(np.asarray(embedded, dtype=np.float64))
+
+    meta: dict[str, Any] = {
+        "seed": seed,
+        "n_neighbors": umap_params["n_neighbors"],
+        "min_dist": umap_params["min_dist"],
+        "metric": umap_params["metric"],
+    }
+    if pre_pca_dims is not None:
+        meta["pre_pca_dims"] = pre_pca_dims
+
+    return {
+        "method": "umap",
+        "n_components": n_components,
+        "positions": positions.tolist(),
+        "meta": meta,
+    }

backend/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "vhectorlab-backend"
+version = "2.3.0"
+description = "VHectorLab 3D FastAPI Backend for Vector Arithmetic and Semantic Embeddings"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.110.0",
+    "uvicorn>=0.28.0",
+    "sentence-transformers>=2.5.0",
+    "torch>=2.2.0",
+    "numpy>=1.26.0",
+    "httpx>=0.27.0",
+    "huggingface-hub>=0.21.0",
+    "orjson>=3.11.9",
+    "umap-learn==0.5.12",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "httpx>=0.27.0",
+    "ruff>=0.3.0",
+]
+
+# HF Space / Docker (Linux): CPU wheels only — PyPI Linux torch pulls multi-GB nvidia-*.
+# macOS keeps default PyPI (MPS-capable). UV_TORCH_BACKEND alone does NOT affect `uv sync`.
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[tool.uv.sources]
+torch = [
+    { index = "pytorch-cpu", marker = "sys_platform == 'linux'" },
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+pythonpath = ["..", "."]

backend/routers/core.py

@@ -0,0 +1,170 @@
+"""
+Core API Router for VHectorLab 3D.
+Provides /health, /embed, /tokenize, /arithmetic, /compare, and /project endpoints.
+"""
+
+from typing import Any, Literal
+
+from backend.projection import ProjectError, project_embeddings
+from backend.state import state
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+router = APIRouter()
+
+
+class EmbedRequest(BaseModel):
+    text: str = Field(..., description="Text to compute embedding for")
+
+
+class TokenizeRequest(BaseModel):
+    text: str = Field(..., description="Text to tokenize")
+
+
+class ArithmeticRequest(BaseModel):
+    word_a: str = Field(
+        ..., json_schema_extra={"example": "king"}, description="Positive base word (A)"
+    )
+    word_b: str = Field(
+        ..., json_schema_extra={"example": "man"}, description="Subtracted word (B)"
+    )
+    word_c: str = Field(
+        ..., json_schema_extra={"example": "woman"}, description="Added word (C)"
+    )
+    top_k: int = Field(
+        default=10, ge=1, le=100, description="Number of nearest neighbors to return"
+    )
+
+
+class CompareRequest(BaseModel):
+    texts: list[str] = Field(
+        ...,
+        description="List of texts/tokens to compute batch embeddings for (1 to 1024 items)",
+    )
+
+
+class ProjectParams(BaseModel):
+    n_neighbors: int = Field(default=15, ge=2, le=200)
+    min_dist: float = Field(default=0.1, ge=0.0)
+    metric: str = Field(default="cosine")
+
+
+class ProjectRequest(BaseModel):
+    vectors: list[list[float]] = Field(
+        ...,
+        description="Precomputed embedding rows (1..1024); does not re-encode text",
+    )
+    method: str = Field(
+        default="umap",
+        description="Projection method; v1 accepts 'umap' only",
+    )
+    n_components: Literal[2, 3] = Field(
+        default=3,
+        description="Output dimensionality (Galaxy uses 3; 2 reserved for future 2D VIEW)",
+    )
+    seed: int = Field(default=42, description="RNG seed for reproducibility")
+    params: ProjectParams | None = Field(
+        default=None,
+        description="UMAP hyperparameters (n_neighbors, min_dist, metric)",
+    )
+
+
+@router.get("/health")
+def health_check() -> dict[str, Any]:
+    selection = getattr(state, "selection", None)
+    short_label = getattr(selection, "short_label", None) if selection else None
+    return {
+        "status": "ok" if state.is_loaded else "uninitialized",
+        "model": state.model_name,
+        "model_profile": getattr(state, "model_profile", None),
+        "short_label": short_label,
+        "embedding_dim": getattr(state, "embedding_dim", None),
+        "truncate_dim": getattr(state, "truncate_dim", None),
+        "vocab_size": len(state.vocab_words),
+        "is_loaded": state.is_loaded,
+        "device": getattr(state, "device", "cpu"),
+    }
+
+
+@router.post("/embed")
+def embed_text(req: EmbedRequest) -> dict[str, Any]:
+    if not state.is_loaded or state.model is None:
+        raise HTTPException(status_code=503, detail="Backend model is not loaded yet")
+    if not req.text.strip():
+        raise HTTPException(status_code=400, detail="Text cannot be empty")
+
+    vec = state.compute_embedding(req.text)
+    return {"text": req.text, "embedding": vec.tolist(), "dimension": len(vec)}
+
+
+@router.post("/tokenize")
+def tokenize_text(req: TokenizeRequest) -> dict[str, Any]:
+    if not state.is_loaded or state.model is None:
+        raise HTTPException(status_code=503, detail="Backend model is not loaded yet")
+
+    # SentenceTransformer uses underlying Hugging Face tokenizer
+    tokenizer = getattr(state.model, "tokenizer", None)
+    if tokenizer is not None:
+        tokens = tokenizer.tokenize(req.text)
+        input_ids = tokenizer.encode(req.text)
+    else:
+        # Fallback space tokenization
+        tokens = req.text.split()
+        input_ids = list(range(len(tokens)))
+
+    return {
+        "text": req.text,
+        "tokens": tokens,
+        "input_ids": input_ids,
+        "count": len(tokens),
+    }
+
+
+@router.post("/arithmetic")
+def perform_arithmetic(req: ArithmeticRequest) -> dict[str, Any]:
+    if not state.is_loaded or state.model is None:
+        raise HTTPException(status_code=503, detail="Backend model is not loaded yet")
+
+    if not (req.word_a.strip() and req.word_b.strip() and req.word_c.strip()):
+        raise HTTPException(
+            status_code=400, detail="Words A, B, and C must not be empty"
+        )
+
+    try:
+        res = state.perform_arithmetic(req.word_a, req.word_b, req.word_c, req.top_k)
+        return res
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/compare")
+def perform_compare(req: CompareRequest) -> dict[str, Any]:
+    if not state.is_loaded or state.model is None:
+        raise HTTPException(status_code=503, detail="Backend model is not loaded yet")
+
+    if not req.texts:
+        raise HTTPException(status_code=400, detail="Texts list cannot be empty")
+
+    try:
+        return state.perform_compare(req.texts)
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/project")
+def perform_project(req: ProjectRequest) -> dict[str, Any]:
+    """Project embedding vectors to 2D/3D (UMAP). Does not encode text."""
+    params = req.params.model_dump() if req.params is not None else None
+    try:
+        return project_embeddings(
+            req.vectors,
+            method=req.method,
+            n_components=req.n_components,
+            seed=req.seed,
+            params=params,
+        )
+    except ProjectError as e:
+        raise HTTPException(status_code=e.status_code, detail=e.message)
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(e))
+

backend/routers/sae.py

@@ -0,0 +1,400 @@
+"""SAE API: status / train / encode / clear — persisted Compare-scope Top-K SAE."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import orjson
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+from starlette.responses import JSONResponse
+
+from backend.sae.sae_model import SAEManager
+from backend.sae.suggest_dims import suggest_sae_dims, suggest_train_schedule
+from backend.sae.train_sae import get_optimal_device, train_sae
+
+logger = logging.getLogger(__name__)
+
+
+class OrjsonResponse(JSONResponse):
+    """FastJSON via orjson (avoid deprecated fastapi.responses.ORJSONResponse)."""
+
+    media_type = "application/json"
+
+    def render(self, content: Any) -> bytes:
+        return orjson.dumps(content)
+
+
+router = APIRouter(default_response_class=OrjsonResponse)
+
+_ARTIFACTS_DIR = Path(__file__).resolve().parent.parent / "artifacts"
+SAE_WEIGHTS_PATH = str(_ARTIFACTS_DIR / "sae_weights.pt")
+
+
+def _resolve_sae_device() -> str:
+    return get_optimal_device(os.getenv("SAE_DEVICE", "AUTO"))
+
+
+sae_manager = SAEManager(
+    device=_resolve_sae_device(),
+    weights_path=SAE_WEIGHTS_PATH,
+)
+
+
+class SAEEncodeRequest(BaseModel):
+    embeddings: list[list[float]] = Field(
+        ..., description="Batch of raw embedding vectors [N, D]"
+    )
+
+
+class SAETrainRequest(BaseModel):
+    embeddings: list[list[float]] = Field(
+        ...,
+        min_length=2,
+        description="Current workspace scope vectors (Compare items or Arithmetic components)",
+    )
+    hidden_dim: int = Field(default=8192, ge=32, le=32768)
+    k: int = Field(default=32, ge=1, le=4096)
+    epochs: int = Field(default=50, ge=1, le=500)
+    lr: float = Field(default=1e-3, gt=0, le=1.0)
+    batch_size: int = Field(default=64, ge=1, le=2048)
+    auto_scale: bool = Field(
+        default=True,
+        description="Scale hidden_dim/k down for small N (recommended)",
+    )
+
+
+class SAETrainingStatus:
+    def __init__(self) -> None:
+        self.status = "idle"  # idle | preparing | training | success | failed
+        self.phase = "idle"
+        self.phase_key = "idle"  # idle | preparing | training | installing | ready | failed
+        self.current_epoch = 0
+        self.total_epochs = 0
+        self.remaining_epochs = 0
+        self.percent = 0.0
+        self.loss = 0.0
+        self.error_message: str | None = None
+        self.metrics: dict[str, Any] | None = None
+        self.message = ""
+        self.resolved_hidden: int | None = None
+        self.resolved_k: int | None = None
+        self.n_vectors: int | None = None
+
+
+sae_training_status = SAETrainingStatus()
+
+
+async def _train_sae_task(
+    vectors: np.ndarray,
+    hidden_dim: int,
+    k: int,
+    epochs: int,
+    lr: float,
+    batch_size: int,
+) -> None:
+    global sae_training_status
+    try:
+        n = int(vectors.shape[0])
+        sae_training_status.status = "training"
+        sae_training_status.phase_key = "preparing"
+        sae_training_status.phase = "Preparing scope matrix…"
+        sae_training_status.current_epoch = 0
+        sae_training_status.total_epochs = epochs
+        sae_training_status.remaining_epochs = epochs
+        sae_training_status.percent = 0.0
+        sae_training_status.loss = 0.0
+        sae_training_status.error_message = None
+        sae_training_status.metrics = None
+        sae_training_status.message = (
+            f"Preparing scope matrix… (n={n}, hidden={hidden_dim}, k={k}, epochs={epochs})"
+        )
+        sae_training_status.resolved_hidden = hidden_dim
+        sae_training_status.resolved_k = k
+        sae_training_status.n_vectors = n
+
+        # Drop previous in-RAM model (file replaced on install)
+        sae_manager.unload()
+
+        def progress_cb(
+            completed: float,
+            total_epochs: int,
+            loss: float,
+            detail: str = "",
+        ) -> None:
+            completed_f = float(completed)
+            total_epochs = int(total_epochs)
+            completed_i = int(completed_f) if completed_f < total_epochs else total_epochs
+            remaining = max(0, total_epochs - completed_i)
+            # Keep a fractional "still in this epoch" remaining feel
+            if completed_f < total_epochs and completed_f > completed_i:
+                remaining = max(0, total_epochs - completed_i - 1)
+            pct = (
+                round(100.0 * min(completed_f, float(total_epochs)) / total_epochs, 1)
+                if total_epochs
+                else 0.0
+            )
+            sae_training_status.current_epoch = completed_i
+            sae_training_status.total_epochs = total_epochs
+            sae_training_status.remaining_epochs = remaining
+            sae_training_status.percent = min(99.0, pct) if completed_f < total_epochs else pct
+            sae_training_status.loss = float(loss)
+            sae_training_status.phase_key = "training"
+            sae_training_status.status = "training"
+            if detail:
+                sae_training_status.phase = detail
+            elif completed_f < total_epochs:
+                running = min(total_epochs, completed_i + 1)
+                loss_bit = f" · loss={loss:.6f}" if loss else ""
+                sae_training_status.phase = (
+                    f"Training epoch {running}/{total_epochs} — "
+                    f"{remaining} remaining{loss_bit}"
+                )
+            else:
+                sae_training_status.phase = (
+                    f"Epochs done {total_epochs}/{total_epochs} · loss={loss:.6f}"
+                )
+            sae_training_status.message = sae_training_status.phase
+
+        sae_training_status.phase_key = "training"
+        sae_training_status.phase = (
+            f"Training epoch 1/{epochs} — {epochs} remaining"
+        )
+        sae_training_status.message = sae_training_status.phase
+        metrics, checkpoint = await asyncio.to_thread(
+            train_sae,
+            vectors=vectors,
+            hidden_dim=hidden_dim,
+            k=k,
+            epochs=epochs,
+            lr=lr,
+            batch_size=batch_size,
+            device_name=os.getenv("SAE_DEVICE", "AUTO"),
+            output_path=None,
+            progress_cb=progress_cb,
+        )
+
+        sae_training_status.phase_key = "installing"
+        sae_training_status.current_epoch = epochs
+        sae_training_status.remaining_epochs = 0
+        sae_training_status.percent = 99.0
+        sae_training_status.phase = "Saving checkpoint…"
+        sae_training_status.message = (
+            f"Saving checkpoint… ({hidden_dim}D · k={k} · n={n})"
+        )
+        sae_manager.device = _resolve_sae_device()
+        sae_manager.install_checkpoint(checkpoint, persist=True)
+
+        sae_training_status.metrics = metrics
+        sae_training_status.status = "success"
+        sae_training_status.phase_key = "ready"
+        sae_training_status.percent = 100.0
+        sae_training_status.remaining_epochs = 0
+        sae_training_status.phase = "Ready"
+        sae_training_status.message = (
+            f"Ready — saved SAE {hidden_dim}D · k={k} · n={n}"
+        )
+        logger.info("SAE training completed (checkpoint saved).")
+
+    except Exception as e:
+        logger.exception("SAE training failed")
+        sae_manager.clear(delete_file=False)
+        sae_training_status.status = "failed"
+        sae_training_status.phase_key = "failed"
+        sae_training_status.phase = "failed"
+        sae_training_status.error_message = str(e)
+        sae_training_status.message = str(e)
+
+
+@router.get("/sae/status")
+async def sae_status() -> dict[str, Any]:
+    is_trained = sae_manager.is_trained()
+    status_info: dict[str, Any] = {
+        "is_trained": is_trained,
+        "ephemeral": False,
+        "persisted": sae_manager.has_checkpoint_file(),
+        "weights_path": SAE_WEIGHTS_PATH,
+        "config": None,
+        "metrics": None,
+        "training": {
+            "status": sae_training_status.status,
+            "phase": sae_training_status.phase,
+            "phase_key": sae_training_status.phase_key,
+            "message": sae_training_status.message,
+            "current_epoch": sae_training_status.current_epoch,
+            "total_epochs": sae_training_status.total_epochs,
+            "remaining_epochs": sae_training_status.remaining_epochs,
+            "percent": sae_training_status.percent,
+            "loss": sae_training_status.loss,
+            "error_message": sae_training_status.error_message,
+            "metrics": sae_training_status.metrics,
+            "resolved_hidden": sae_training_status.resolved_hidden,
+            "resolved_k": sae_training_status.resolved_k,
+            "n_vectors": sae_training_status.n_vectors,
+        },
+    }
+    if is_trained:
+        if sae_manager.load_model():
+            status_info["config"] = sae_manager.config
+            status_info["metrics"] = sae_manager.metrics
+    return status_info
+
+
+@router.post("/sae/clear")
+async def sae_clear() -> dict[str, Any]:
+    """Delete the saved SAE checkpoint and drop RAM weights (Retrain confirm)."""
+    if sae_training_status.status == "training":
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot clear SAE while a training job is in progress.",
+        )
+    sae_manager.clear(delete_file=True)
+    sae_training_status.status = "idle"
+    sae_training_status.phase = "idle"
+    sae_training_status.phase_key = "idle"
+    sae_training_status.message = ""
+    sae_training_status.metrics = None
+    sae_training_status.error_message = None
+    sae_training_status.resolved_hidden = None
+    sae_training_status.resolved_k = None
+    sae_training_status.n_vectors = None
+    sae_training_status.current_epoch = 0
+    sae_training_status.total_epochs = 0
+    sae_training_status.remaining_epochs = 0
+    sae_training_status.percent = 0.0
+    return {"message": "SAE checkpoint deleted.", "is_trained": False}
+
+
+@router.post("/sae/train")
+async def sae_train(request: SAETrainRequest) -> dict[str, Any]:
+    if sae_training_status.status == "training":
+        raise HTTPException(
+            status_code=400, detail="A training job is already in progress."
+        )
+
+    vectors = np.asarray(request.embeddings, dtype=np.float32)
+    if vectors.ndim != 2:
+        raise HTTPException(
+            status_code=400, detail="embeddings must be a 2D array [N, D]"
+        )
+    if vectors.shape[0] < 2:
+        raise HTTPException(
+            status_code=400, detail="Need at least 2 embedding vectors to train SAE"
+        )
+
+    input_dim = int(vectors.shape[1])
+    n_vectors = int(vectors.shape[0])
+    if request.auto_scale:
+        hidden_dim, k = suggest_sae_dims(
+            n_vectors=n_vectors,
+            input_dim=input_dim,
+            requested_hidden=request.hidden_dim,
+            requested_k=request.k,
+        )
+        epochs, batch_size = suggest_train_schedule(
+            n_vectors=n_vectors,
+            hidden_dim=hidden_dim,
+            requested_epochs=request.epochs,
+            requested_batch_size=request.batch_size,
+        )
+    else:
+        hidden_dim, k = request.hidden_dim, request.k
+        epochs, batch_size = request.epochs, request.batch_size
+
+    if k > hidden_dim:
+        raise HTTPException(status_code=400, detail="k must be <= hidden_dim")
+
+    asyncio.create_task(
+        _train_sae_task(
+            vectors=vectors,
+            hidden_dim=hidden_dim,
+            k=k,
+            epochs=epochs,
+            lr=request.lr,
+            batch_size=batch_size,
+        )
+    )
+    return {
+        "message": "Training started.",
+        "status": "training",
+        "resolved_hidden": hidden_dim,
+        "resolved_k": k,
+        "resolved_epochs": epochs,
+        "resolved_batch_size": batch_size,
+        "n_vectors": n_vectors,
+        "device": _resolve_sae_device(),
+        "auto_scaled": bool(
+            request.auto_scale
+            and (
+                hidden_dim != request.hidden_dim
+                or k != request.k
+                or epochs != request.epochs
+                or batch_size != request.batch_size
+            )
+        ),
+    }
+
+
+@router.post("/sae/encode")
+async def sae_encode(request: SAEEncodeRequest) -> dict[str, Any]:
+    """
+    Encode embeddings → Top-K sparse activations (indices + values).
+
+    Does NOT return a dense [N, hidden_dim] matrix (mostly zeros). Clients densify
+    locally when needed. Model stays resident in RAM after first load_model().
+    """
+    if not sae_manager.is_trained():
+        raise HTTPException(
+            status_code=404,
+            detail="No trained SAE model available. Please train one first.",
+        )
+
+    try:
+        if not request.embeddings:
+            # Ensure config is in RAM if only the checkpoint file exists
+            sae_manager.load_model()
+            hidden = int(sae_manager.config.get("hidden_dim", 8192))
+            k = int(sae_manager.config.get("k", 32))
+            return {
+                "format": "topk_sparse",
+                "indices": [],
+                "values": [],
+                "dimension": hidden,
+                "k": k,
+                "count": 0,
+                "batch_metrics": {
+                    "l0": 0.0,
+                    "sparsity": 0.0,
+                    "active_features": 0,
+                },
+            }
+
+        vectors = np.asarray(request.embeddings, dtype=np.float32)
+        if vectors.ndim != 2:
+            raise HTTPException(
+                status_code=400, detail="embeddings must be a 2D array [N, D]"
+            )
+
+        sparse = await asyncio.to_thread(sae_manager.encode_vectors_sparse, vectors)
+        # ORJSON serializes ndarray; convert only the small [N, K] packs
+        return {
+            "format": sparse["format"],
+            "indices": sparse["indices"].tolist(),
+            "values": sparse["values"].tolist(),
+            "dimension": int(sparse["dimension"]),
+            "k": int(sparse["k"]),
+            "count": int(sparse["count"]),
+            "batch_metrics": sparse["batch_metrics"],
+        }
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    except Exception:
+        logger.exception("Error encoding embeddings through SAE")
+        raise HTTPException(status_code=500, detail="SAE encode failed") from None

backend/sae/__init__.py

@@ -0,0 +1,14 @@
+"""Top-K Sparse Autoencoder (trained) for Clean/Denoise."""
+
+from backend.sae.sae_model import SAEManager, TopKSAE
+from backend.sae.suggest_dims import suggest_sae_dims, suggest_train_schedule
+from backend.sae.train_sae import get_optimal_device, train_sae
+
+__all__ = [
+    "TopKSAE",
+    "SAEManager",
+    "train_sae",
+    "get_optimal_device",
+    "suggest_sae_dims",
+    "suggest_train_schedule",
+]

backend/sae/sae_model.py

@@ -0,0 +1,326 @@
+"""Top-K SAE model and lazy-load manager (ported from predecessor tool)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import numpy as np
+import torch
+from torch import nn
+
+logger = logging.getLogger("sae_model")
+
+
+class TopKSAE(nn.Module):
+    """
+    Sparse Autoencoder with Top-K activation sparsity.
+    Projects D-dimensional embeddings to a higher-dimensional sparse space.
+    """
+
+    def __init__(self, input_dim: int = 768, hidden_dim: int = 8192, k: int = 32):
+        super().__init__()
+        self.input_dim = input_dim
+        self.hidden_dim = hidden_dim
+        self.k = k
+
+        self.b_dec = nn.Parameter(torch.zeros(input_dim))
+        self.W_enc = nn.Parameter(torch.empty(input_dim, hidden_dim))
+        self.b_enc = nn.Parameter(torch.zeros(hidden_dim))
+        self.W_dec = nn.Parameter(torch.empty(hidden_dim, input_dim))
+
+        self.reset_parameters()
+
+    def reset_parameters(self) -> None:
+        nn.init.kaiming_uniform_(self.W_enc, nonlinearity="relu")
+        nn.init.kaiming_uniform_(self.W_dec, nonlinearity="linear")
+        self.make_decoder_weights_unit_norm()
+
+    def make_decoder_weights_unit_norm(self) -> None:
+        """Constrains decoder weight rows (W_dec) to unit L2 norm."""
+        with torch.no_grad():
+            self.W_dec.data.div_(
+                torch.norm(self.W_dec.data, dim=1, keepdim=True) + 1e-8
+            )
+
+    def encode(self, x: torch.Tensor) -> torch.Tensor:
+        x_centered = x - self.b_dec
+        pre_acts = torch.relu(x_centered @ self.W_enc + self.b_enc)
+
+        # Top-K in FP32 for dead-latent / overflow stability
+        if self.k < self.hidden_dim:
+            pre_acts_fp32 = pre_acts.float()
+            topk_vals, topk_indices = torch.topk(pre_acts_fp32, self.k, dim=-1)
+            acts = torch.zeros_like(pre_acts_fp32).scatter_(-1, topk_indices, topk_vals)
+            if acts.dtype != pre_acts.dtype:
+                acts = acts.to(pre_acts.dtype)
+        else:
+            acts = pre_acts
+
+        return acts
+
+    def decode(self, acts: torch.Tensor) -> torch.Tensor:
+        if acts.dtype != self.W_dec.dtype:
+            acts = acts.to(self.W_dec.dtype)
+        return acts @ self.W_dec + self.b_dec
+
+    def forward(self, x: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+        acts = self.encode(x)
+        x_reconstructed = self.decode(acts)
+        return x_reconstructed, acts
+
+
+class SAEManager:
+    """Lazy-load checkpoint from disk + in-memory encode for Clean/Denoise."""
+
+    def __init__(self, device: str = "cpu", weights_path: str | None = None):
+        self.weights_path = weights_path
+        self.device = device
+        self.model: TopKSAE | None = None
+        self.config: dict[str, Any] = {}
+        self.metrics: dict[str, Any] = {}
+        self.static_buckets = [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024]
+
+    def has_checkpoint_file(self) -> bool:
+        return bool(self.weights_path) and os.path.exists(self.weights_path)
+
+    def is_trained(self) -> bool:
+        return self.model is not None or self.has_checkpoint_file()
+
+    def clear(self, *, delete_file: bool = False) -> None:
+        """Drop in-memory model; optionally delete the saved checkpoint."""
+        self.model = None
+        self.config = {}
+        self.metrics = {}
+        if delete_file and self.weights_path and os.path.exists(self.weights_path):
+            try:
+                os.remove(self.weights_path)
+                logger.info("Deleted SAE checkpoint %s", self.weights_path)
+            except OSError as e:
+                logger.warning("Could not delete SAE checkpoint: %s", e)
+
+    def clear_if_dim_mismatch(self, embedding_dim: int) -> bool:
+        """
+        Clear SAE RAM (+ delete checkpoint) when stored input_dim ≠ embedding_dim (M10).
+
+        Returns True if something was cleared. No-op when SAE is empty or dims match.
+        """
+        stored: int | None = None
+        if self.config.get("input_dim") is not None:
+            stored = int(self.config["input_dim"])
+        elif self.model is not None:
+            stored = int(self.model.input_dim)
+        elif self.has_checkpoint_file():
+            try:
+                checkpoint = torch.load(self.weights_path, map_location="cpu")
+                cfg = checkpoint.get("config") or {}
+                if cfg.get("input_dim") is not None:
+                    stored = int(cfg["input_dim"])
+            except Exception as e:  # noqa: BLE001
+                logger.warning(
+                    "Could not read SAE checkpoint dim (%s); clearing to be safe.", e
+                )
+                self.clear(delete_file=True)
+                return True
+
+        if stored is None:
+            return False
+        if stored == int(embedding_dim):
+            return False
+        logger.warning(
+            "SAE input_dim=%s != embedding_dim=%s — clearing session SAE.",
+            stored,
+            embedding_dim,
+        )
+        self.clear(delete_file=True)
+        return True
+
+    def unload(self) -> None:
+        """Drop RAM only (keep file on disk)."""
+        self.model = None
+        self.config = {}
+        self.metrics = {}
+
+    def save_checkpoint(self, checkpoint: dict[str, Any]) -> None:
+        if not self.weights_path:
+            return
+        parent = os.path.dirname(self.weights_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        torch.save(checkpoint, self.weights_path)
+        logger.info("Saved SAE checkpoint to %s", self.weights_path)
+
+    def install_checkpoint(self, checkpoint: dict[str, Any], *, persist: bool = True) -> None:
+        """Install a trained checkpoint into RAM; optionally persist to disk."""
+        self.config = dict(
+            checkpoint.get("config", {"input_dim": 768, "hidden_dim": 8192, "k": 32})
+        )
+        self.metrics = dict(checkpoint.get("metrics", {}))
+        self.model = TopKSAE(
+            input_dim=int(self.config.get("input_dim", 768)),
+            hidden_dim=int(self.config.get("hidden_dim", 8192)),
+            k=int(self.config.get("k", 32)),
+        )
+        self.model.load_state_dict(checkpoint["state_dict"])
+        self.model.to(self.device)
+        self.model.eval()
+        if persist:
+            self.save_checkpoint(checkpoint)
+        logger.info(
+            "SAE installed (hidden_dim=%s, k=%s, persist=%s).",
+            self.config.get("hidden_dim"),
+            self.config.get("k"),
+            persist,
+        )
+
+    def load_model(self) -> bool:
+        if self.model is not None:
+            return True
+
+        if not self.has_checkpoint_file():
+            logger.warning("No SAE checkpoint available")
+            return False
+
+        try:
+            logger.info(
+                "Loading SAE model from %s on %s...", self.weights_path, self.device
+            )
+            checkpoint = torch.load(self.weights_path, map_location=self.device)
+            self.install_checkpoint(checkpoint, persist=False)
+            return True
+        except Exception as e:
+            logger.error("Error loading SAE model: %s", e)
+            self.model = None
+            return False
+
+    def _encode_acts_tensor(self, vectors: np.ndarray) -> torch.Tensor:
+        """
+        Run Top-K encode on [N, D] → device tensor [N, hidden_dim].
+        Shares bucketing / from_numpy / inference_mode / AMP across dense + sparse paths.
+        Model must already be loaded (singleton in RAM/VRAM).
+        """
+        assert self.model is not None
+        orig_len = vectors.shape[0]
+        if orig_len == 0:
+            return torch.empty(
+                (0, self.model.hidden_dim),
+                dtype=torch.float32,
+                device=self.device,
+            )
+
+        bucket_len = min(
+            (b for b in self.static_buckets if b >= orig_len), default=orig_len
+        )
+        padding_needed = bucket_len - orig_len
+
+        if padding_needed > 0:
+            padded_vectors = np.pad(
+                vectors, ((0, padding_needed), (0, 0)), mode="constant"
+            )
+        else:
+            padded_vectors = vectors
+
+        if not padded_vectors.flags.writeable:
+            padded_vectors = padded_vectors.copy()
+        x_tensor = torch.from_numpy(padded_vectors).to(self.device)
+        if x_tensor.dtype != torch.float32:
+            x_tensor = x_tensor.float()
+
+        device_type = (
+            "cuda"
+            if "cuda" in str(self.device)
+            else ("mps" if "mps" in str(self.device) else "cpu")
+        )
+        use_amp = device_type in ["cuda", "cpu", "mps"]
+        amp_dtype = (
+            torch.bfloat16
+            if (device_type == "cuda" and torch.cuda.is_bf16_supported())
+            else torch.float16
+        )
+
+        with torch.inference_mode():
+            if use_amp:
+                try:
+                    with torch.amp.autocast(device_type=device_type, dtype=amp_dtype):
+                        acts = self.model.encode(x_tensor)
+                except Exception:
+                    acts = self.model.encode(x_tensor)
+            else:
+                acts = self.model.encode(x_tensor)
+
+            return acts[:orig_len].float()
+
+    def encode_vectors(self, vectors: np.ndarray) -> np.ndarray:
+        """
+        Encode [N, D] embeddings → [N, hidden_dim] sparse activations (dense layout).
+        Prefer encode_vectors_sparse for HTTP — avoids shipping ~99% zeros.
+        """
+        if not self.load_model() or self.model is None:
+            raise ValueError("SAE model is not trained or could not be loaded.")
+
+        if vectors.shape[0] == 0:
+            return np.empty((0, self.model.hidden_dim), dtype=np.float32)
+
+        return self._encode_acts_tensor(vectors).cpu().numpy()
+
+    def encode_vectors_sparse(self, vectors: np.ndarray) -> dict[str, Any]:
+        """
+        Encode [N, D] → Top-K sparse payload (indices/values only).
+
+        Returns dict with numpy arrays ready for ORJSON (no dense [N, H] .tolist()).
+        """
+        if not self.load_model() or self.model is None:
+            raise ValueError("SAE model is not trained or could not be loaded.")
+
+        hidden = int(self.model.hidden_dim)
+        k = int(self.model.k)
+        orig_len = int(vectors.shape[0])
+        if orig_len == 0:
+            return {
+                "format": "topk_sparse",
+                "indices": np.empty((0, k), dtype=np.int64),
+                "values": np.empty((0, k), dtype=np.float32),
+                "dimension": hidden,
+                "k": k,
+                "count": 0,
+                "batch_metrics": {
+                    "l0": 0.0,
+                    "sparsity": 0.0,
+                    "active_features": 0,
+                },
+            }
+
+        with torch.inference_mode():
+            acts = self._encode_acts_tensor(vectors)
+            # acts already Top-K sparse in dense layout; pack the K slots
+            topk_k = min(k, hidden)
+            vals, idx = torch.topk(acts, topk_k, dim=-1)
+            vals_np = vals.cpu().numpy().astype(np.float32, copy=False)
+            idx_np = idx.cpu().numpy().astype(np.int64, copy=False)
+
+            active_per_row = (vals > 0).sum(dim=-1).float()
+            l0 = float(active_per_row.mean().item()) if orig_len else 0.0
+            if orig_len and topk_k > 0:
+                # Unique latent ids that fired at least once in the batch
+                pos_mask = vals > 0
+                if bool(pos_mask.any().item()):
+                    active_features = int(torch.unique(idx[pos_mask]).numel())
+                else:
+                    active_features = 0
+            else:
+                active_features = 0
+
+        return {
+            "format": "topk_sparse",
+            "indices": idx_np,
+            "values": vals_np,
+            "dimension": hidden,
+            "k": topk_k,
+            "count": orig_len,
+            "batch_metrics": {
+                "l0": l0,
+                "sparsity": float(l0 / hidden) if hidden else 0.0,
+                "active_features": active_features,
+            },
+        }

backend/sae/suggest_dims.py

@@ -0,0 +1,86 @@
+"""Auto-scale Top-K SAE width + train schedule for small session scopes."""
+
+from __future__ import annotations
+
+
+def suggest_sae_dims(
+    n_vectors: int,
+    input_dim: int,
+    requested_hidden: int = 8192,
+    requested_k: int = 32,
+) -> tuple[int, int]:
+    """
+    Cap hidden_dim / k so a small Compare batch does not train an 8192-wide dictionary.
+
+    Returns (hidden_dim, k) with hidden_dim <= requested_hidden and k <= min(requested_k, hidden_dim).
+    """
+    if n_vectors < 2:
+        raise ValueError("Need at least 2 embedding vectors to train SAE")
+    if input_dim < 1:
+        raise ValueError("input_dim must be positive")
+    if requested_hidden < 16:
+        raise ValueError("requested_hidden must be >= 16")
+    if requested_k < 1:
+        raise ValueError("requested_k must be >= 1")
+
+    # Keep dictionary proportional to sample count (aggressive for interactive UX).
+    if n_vectors < 32:
+        by_n = max(32, n_vectors * 3)
+    elif n_vectors < 64:
+        by_n = max(32, n_vectors * 4)
+    elif n_vectors < 256:
+        by_n = max(64, n_vectors * 5)
+    else:
+        by_n = max(128, n_vectors * 8)
+
+    by_d = max(input_dim, min(requested_hidden, input_dim * 2))
+
+    if n_vectors >= max(512, requested_hidden // 4):
+        hidden = requested_hidden
+    else:
+        hidden = min(requested_hidden, max(32, min(by_n, by_d)))
+
+    if hidden >= 32:
+        hidden = max(32, (hidden // 32) * 32)
+    hidden = max(16, min(int(hidden), requested_hidden))
+
+    k = min(requested_k, hidden)
+    if hidden >= 4:
+        k = min(k, max(1, hidden // 4))
+    k = max(1, int(k))
+    return hidden, k
+
+
+def suggest_train_schedule(
+    n_vectors: int,
+    hidden_dim: int,
+    requested_epochs: int = 50,
+    requested_batch_size: int = 64,
+) -> tuple[int, int]:
+    """
+    Cap epochs / prefer full-batch for interactive session SAE training.
+
+    Returns (epochs, batch_size).
+    """
+    if n_vectors < 2:
+        raise ValueError("Need at least 2 embedding vectors to train SAE")
+
+    # Smaller dictionaries converge in fewer passes; keep UX snappy.
+    if hidden_dim <= 128:
+        epochs = min(requested_epochs, 12)
+    elif hidden_dim <= 512:
+        epochs = min(requested_epochs, 20)
+    elif n_vectors < 64:
+        epochs = min(requested_epochs, 25)
+    else:
+        epochs = requested_epochs
+    epochs = max(1, int(epochs))
+
+    # Full-batch when N fits — avoids DataLoader overhead on small scopes.
+    if n_vectors <= 512:
+        batch_size = n_vectors
+    else:
+        batch_size = min(int(requested_batch_size), n_vectors)
+        batch_size = max(8, batch_size)
+
+    return epochs, batch_size

backend/sae/train_sae.py

@@ -0,0 +1,326 @@
+"""Train Top-K SAE on a session-scope embedding matrix (fast path)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torch.utils.data import DataLoader, TensorDataset
+
+from backend.device import get_optimal_device
+from backend.sae.sae_model import TopKSAE
+
+logger = logging.getLogger("train_sae")
+
+ProgressCb = Callable[..., None]
+
+# Re-export for callers that imported get_optimal_device from this module.
+__all__ = ["get_optimal_device", "train_sae"]
+
+
+def _device_type(device: torch.device | str) -> str:
+    s = str(device)
+    if "cuda" in s:
+        return "cuda"
+    if "mps" in s:
+        return "mps"
+    return "cpu"
+
+
+def _amp_settings(device: torch.device) -> tuple[bool, torch.dtype | None]:
+    """Mixed precision for CUDA matmuls. MPS/CPU train stays FP32 for stability."""
+    if device.type == "cuda":
+        dtype = (
+            torch.bfloat16
+            if torch.cuda.is_bf16_supported()
+            else torch.float16
+        )
+        return True, dtype
+    return False, None
+
+
+def _emit_progress(
+    progress_cb: ProgressCb | None,
+    completed: float,
+    total_epochs: int,
+    loss: float,
+    detail: str = "",
+) -> None:
+    if progress_cb is None:
+        return
+    try:
+        if detail:
+            progress_cb(completed, total_epochs, float(loss), detail)
+        else:
+            progress_cb(completed, total_epochs, float(loss))
+    except TypeError:
+        try:
+            progress_cb(completed, total_epochs, float(loss))
+        except Exception:
+            pass
+    except Exception:
+        pass
+
+
+def train_sae(
+    vectors: np.ndarray,
+    hidden_dim: int = 8192,
+    k: int = 32,
+    epochs: int = 50,
+    lr: float = 1e-3,
+    batch_size: int = 64,
+    device_name: str = "AUTO",
+    output_path: str | None = None,
+    progress_cb: ProgressCb | None = None,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """
+    Train TopKSAE with Adam + MSE reconstruction (session-scope fast path).
+
+    Optimizations vs naive loop:
+    - contiguous float32 + torch.from_numpy (zero-copy into torch)
+    - full-batch when N <= batch_size (no DataLoader overhead)
+    - CUDA/CPU AMP autocast on forward
+    - inference_mode for final metrics
+    - decoder unit-norm every step (small H) / every 2 steps (large H)
+
+    Returns (metrics, checkpoint).
+    """
+    if vectors.ndim != 2 or vectors.shape[0] == 0:
+        raise ValueError("vectors must be a non-empty 2D array [N, D]")
+
+    device = torch.device(get_optimal_device(device_name))
+    logger.info("Training on device: %s", device)
+
+    # Zero-copy friendly contiguous float32
+    vectors = np.ascontiguousarray(vectors, dtype=np.float32)
+    input_dim = int(vectors.shape[1])
+    n = int(vectors.shape[0])
+
+    model = TopKSAE(input_dim=input_dim, hidden_dim=hidden_dim, k=k)
+    model.to(device)
+
+    x_host = torch.from_numpy(vectors)  # shares memory with NumPy
+    actual_batch_size = min(max(1, batch_size), n)
+    use_full_batch = actual_batch_size >= n
+
+    if use_full_batch:
+        x_all = x_host.to(device, non_blocking=True)
+        dataloader = None
+    else:
+        dataset = TensorDataset(x_host)
+        dataloader = DataLoader(
+            dataset,
+            batch_size=actual_batch_size,
+            shuffle=True,
+            drop_last=False,
+            pin_memory=(device.type == "cuda"),
+        )
+        x_all = None
+
+    optimizer = optim.Adam(model.parameters(), lr=lr)
+    use_amp, amp_dtype = _amp_settings(device)
+    # GradScaler only for cuda fp16 (not bf16 / not mps)
+    scaler = (
+        torch.amp.GradScaler("cuda")
+        if (use_amp and _device_type(device) == "cuda" and amp_dtype == torch.float16)
+        else None
+    )
+    norm_every = 1 if hidden_dim <= 1024 else 2
+    step_i = 0
+
+    logger.info(
+        "Starting SAE training (n=%s, hidden_dim=%s, k=%s, epochs=%s, batch_size=%s, full_batch=%s, amp=%s)...",
+        n,
+        hidden_dim,
+        k,
+        epochs,
+        actual_batch_size,
+        use_full_batch,
+        use_amp,
+    )
+
+    last_loss = 0.0
+    for epoch in range(epochs):
+        model.train()
+        total_loss = 0.0
+
+        if use_full_batch:
+            assert x_all is not None
+            optimizer.zero_grad(set_to_none=True)
+            if use_amp and amp_dtype is not None:
+                with torch.amp.autocast(device_type=_device_type(device), dtype=amp_dtype):
+                    reconstruction, _acts = model(x_all)
+                    loss = nn.functional.mse_loss(reconstruction, x_all)
+            else:
+                reconstruction, _acts = model(x_all)
+                loss = nn.functional.mse_loss(reconstruction, x_all)
+
+            if scaler is not None:
+                scaler.scale(loss).backward()
+                scaler.step(optimizer)
+                scaler.update()
+            else:
+                loss.backward()
+                optimizer.step()
+
+            step_i += 1
+            if step_i % norm_every == 0:
+                model.make_decoder_weights_unit_norm()
+
+            last_loss = float(loss.detach().item())
+            total_loss = last_loss * n
+            _emit_progress(
+                progress_cb,
+                float(epoch) + 1.0,
+                epochs,
+                last_loss,
+                f"Training epoch {epoch + 1}/{epochs} (full-batch) — "
+                f"{max(0, epochs - epoch - 1)} left · loss={last_loss:.6f}",
+            )
+        else:
+            assert dataloader is not None
+            n_batches = max(1, len(dataloader))
+            for batch_i, batch in enumerate(dataloader):
+                x_batch = batch[0].to(device, non_blocking=True)
+                optimizer.zero_grad(set_to_none=True)
+                if use_amp and amp_dtype is not None:
+                    with torch.amp.autocast(
+                        device_type=_device_type(device), dtype=amp_dtype
+                    ):
+                        reconstruction, _acts = model(x_batch)
+                        loss = nn.functional.mse_loss(reconstruction, x_batch)
+                else:
+                    reconstruction, _acts = model(x_batch)
+                    loss = nn.functional.mse_loss(reconstruction, x_batch)
+
+                if scaler is not None:
+                    scaler.scale(loss).backward()
+                    scaler.step(optimizer)
+                    scaler.update()
+                else:
+                    loss.backward()
+                    optimizer.step()
+
+                step_i += 1
+                if step_i % norm_every == 0:
+                    model.make_decoder_weights_unit_norm()
+
+                batch_loss = float(loss.detach().item())
+                total_loss += batch_loss * len(x_batch)
+
+                report = (
+                    batch_i == 0
+                    or batch_i == n_batches - 1
+                    or batch_i % max(1, n_batches // 10) == 0
+                )
+                if report:
+                    frac = float(epoch) + float(batch_i + 1) / float(n_batches)
+                    _emit_progress(
+                        progress_cb,
+                        frac,
+                        epochs,
+                        batch_loss,
+                        f"Training epoch {epoch + 1}/{epochs} · "
+                        f"batch {batch_i + 1}/{n_batches} — "
+                        f"{max(0, epochs - epoch - 1)} epochs left after this",
+                    )
+
+            last_loss = total_loss / n
+            _emit_progress(
+                progress_cb,
+                float(epoch + 1),
+                epochs,
+                last_loss,
+                f"Finished epoch {epoch + 1}/{epochs} · loss={last_loss:.6f}",
+            )
+
+        if (epoch + 1) % max(1, epochs // 10) == 0 or epoch == epochs - 1:
+            logger.info(
+                "Epoch %03d/%03d - Reconstruction Loss (MSE): %.6f",
+                epoch + 1,
+                epochs,
+                last_loss,
+            )
+
+    # Ensure unit-norm after last step
+    model.make_decoder_weights_unit_norm()
+    model.eval()
+    logger.info("Computing final training metrics...")
+
+    with torch.inference_mode():
+        if x_all is None:
+            x_eval = x_host.to(device, non_blocking=True)
+        else:
+            x_eval = x_all
+        if use_amp and amp_dtype is not None and _device_type(device) != "mps":
+            with torch.amp.autocast(device_type=_device_type(device), dtype=amp_dtype):
+                reconstruction, acts = model(x_eval)
+        else:
+            reconstruction, acts = model(x_eval)
+
+        # Metrics in FP32 for stability
+        reconstruction = reconstruction.float()
+        acts = acts.float()
+        x_eval_f = x_eval.float()
+        final_mse = nn.functional.mse_loss(reconstruction, x_eval_f).item()
+        active_per_input = (acts > 0).sum(dim=-1).float()
+        mean_sparsity = active_per_input.mean().item()
+        feature_activations = (acts > 0).sum(dim=0)
+        dead_features_count = int((feature_activations == 0).sum().item())
+        dead_features_pct = (dead_features_count / hidden_dim) * 100.0
+
+    logger.info("Training Complete.")
+    logger.info("Final Reconstruction Loss (MSE): %.6f", final_mse)
+    logger.info(
+        "Mean Sparsity (Active Features): %.2f / %s (Target K: %s)",
+        mean_sparsity,
+        hidden_dim,
+        k,
+    )
+    logger.info(
+        "Dead Features: %s/%s (%.2f%%)",
+        dead_features_count,
+        hidden_dim,
+        dead_features_pct,
+    )
+
+    config = {
+        "input_dim": input_dim,
+        "hidden_dim": hidden_dim,
+        "k": k,
+        "device": str(device),
+    }
+    metrics = {
+        "mse": float(final_mse),
+        "mean_sparsity": float(mean_sparsity),
+        "dead_features_count": int(dead_features_count),
+        "dead_features_pct": float(dead_features_pct),
+        "total_vectors": n,
+        "epochs": int(epochs),
+        "batch_size": int(actual_batch_size),
+        "full_batch": bool(use_full_batch),
+        "amp": bool(use_amp),
+        "device": str(device),
+    }
+
+    cpu_state = {k_: v.detach().cpu() for k_, v in model.state_dict().items()}
+    checkpoint: dict[str, Any] = {
+        "state_dict": cpu_state,
+        "config": config,
+        "metrics": metrics,
+    }
+
+    if output_path:
+        parent = os.path.dirname(output_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        torch.save(checkpoint, output_path)
+        logger.info("Saved SAE debug checkpoint to %s", output_path)
+
+    return metrics, checkpoint

backend/server.py

@@ -0,0 +1,111 @@
+"""
+FastAPI Server Entrypoint for VHectorLab 3D.
+Handles application lifespan, lazy-loading models, CORS configuration, and router binding.
+"""
+
+import logging
+import os
+import sys
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+# Ensure parent directory is in sys.path so 'backend.*' package imports resolve correctly
+_root_dir = str(Path(__file__).resolve().parent.parent)
+if _root_dir not in sys.path:
+    sys.path.insert(0, _root_dir)
+
+from backend.model_catalog import resolve_selection_from_env
+from backend.model_swap import apply_dotenv
+from backend.routers.core import router as core_router
+from backend.routers.sae import router as sae_router
+from backend.routers.sae import sae_manager
+from backend.state import state
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+# Repo-root `.env` (setup.sh option 11 / option 1). `uv run` from backend/ does not
+# load it automatically — without this, MODEL_* stay unset and default to mpnet.
+apply_dotenv(Path(_root_dir) / ".env")
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("vhectorlab")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.info("Initializing VHectorLab 3D backend lifespan...")
+    vocab_path = os.getenv("VOCAB_PATH", "public/vocab.txt")
+    vocab_embeddings_path = os.getenv(
+        "VOCAB_EMBEDDINGS_PATH", "public/vocab_embeddings.npz"
+    )
+    selection = resolve_selection_from_env()
+
+    # Lazy load model and vocabulary into AppState
+    try:
+        state.load_model_and_vocab(
+            vocab_path=vocab_path,
+            vocab_embeddings_path=vocab_embeddings_path,
+            selection=selection,
+        )
+        if state.embedding_dim is not None:
+            sae_manager.clear_if_dim_mismatch(state.embedding_dim)
+    except Exception as e:  # noqa: BLE001
+        logger.error(f"Error loading model/vocab in lifespan: {e}")
+
+    yield
+
+    logger.info("Shutting down VHectorLab 3D backend...")
+
+
+app = FastAPI(
+    title="VHectorLab 3D API",
+    description="Backend API for 3D Vector Arithmetic & Semantic Embedding Visualizer",
+    version="3.0.1",
+    lifespan=lifespan,
+)
+
+# CORS Policy Alignment: allow_origins=["*"] combined with allow_credentials=False
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=False,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(core_router, prefix="/api")
+app.include_router(sae_router, prefix="/api")
+app.include_router(core_router)  # Also expose without /api prefix for convenience
+app.include_router(sae_router)
+
+# Mount static frontend files if dist/ exists (Docker / Production mode)
+from backend.static_dist import resolve_dist_file
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+dist_path = Path(__file__).resolve().parent.parent / "dist"
+if dist_path.exists():
+    logger.info(f"Serving static frontend files from {dist_path}")
+    app.mount("/assets", StaticFiles(directory=dist_path / "assets"), name="assets")
+
+    @app.get("/{full_path:path}")
+    async def serve_frontend(full_path: str):
+        return FileResponse(resolve_dist_file(dist_path, full_path))
+
+
+def _want_reload(host: str) -> bool:
+    """Local bare-metal defaults to reload; Docker/HF (0.0.0.0 or UVICORN_RELOAD=0) does not."""
+    env = os.getenv("UVICORN_RELOAD")
+    if env is not None:
+        return env.strip().lower() in ("1", "true", "yes")
+    return host in ("127.0.0.1", "localhost")
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    host = os.getenv("HOST", "127.0.0.1")
+    port = int(os.getenv("PORT", "8000"))
+    reload = _want_reload(host)
+    logger.info("Starting uvicorn host=%s port=%s reload=%s", host, port, reload)
+    uvicorn.run("backend.server:app", host=host, port=port, reload=reload)

backend/state.py

@@ -0,0 +1,340 @@
+"""
+Global App State for VHectorLab 3D.
+Manages lazy-loaded SentenceTransformer model and pre-computed vocabulary embeddings in RAM.
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from backend.model_catalog import (
+    ModelSelection,
+    build_model,
+    encode_texts,
+    resolve_selection_from_env,
+)
+from backend.vocab_embeddings import (
+    load_vocab_embeddings_npz as _load_vocab_cache,
+)
+from backend.vocab_embeddings import (
+    npz_compatible_with_selection,
+    save_vocab_embeddings_npz,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_path(vocab_path: str) -> Path | None:
+    path = Path(vocab_path)
+    if path.exists():
+        return path
+    alt_path = Path(__file__).resolve().parent.parent / vocab_path
+    if alt_path.exists():
+        return alt_path
+    return None
+
+
+def load_vocab_embeddings_npz(
+    npz_path: Path,
+) -> tuple[list[str], np.ndarray, str | None]:
+    """
+    Load precomputed vocab embeddings NPZ.
+    Returns (words, embeddings float32 L2-normalized, model_name or None).
+    """
+    cache = _load_vocab_cache(npz_path)
+    return cache.words, cache.embeddings, cache.model_name
+
+
+class AppState:
+    def __init__(self):
+        self.model = None
+        self.model_name: str = "all-mpnet-base-v2"
+        self.model_profile: str | None = None
+        self.truncate_dim: int | None = None
+        self.embedding_dim: int | None = None
+        self.selection: ModelSelection | None = None
+        self.vocab_words: list[str] = []
+        self.vocab_embeddings: np.ndarray | None = None  # Normalized (N, D)
+        self.is_loaded: bool = False
+        self.device: str = "cpu"
+
+    def _apply_selection(self, selection: ModelSelection) -> None:
+        self.selection = selection
+        self.model_name = selection.hub_id
+        self.model_profile = selection.profile
+        self.truncate_dim = selection.truncate_dim
+
+    def _set_embedding_dim_from_model(self) -> None:
+        dim: int | None = None
+        if self.model is not None and hasattr(
+            self.model, "get_sentence_embedding_dimension"
+        ):
+            try:
+                dim = int(self.model.get_sentence_embedding_dimension())
+            except Exception:  # noqa: BLE001
+                dim = None
+        if dim is None and self.vocab_embeddings is not None:
+            dim = int(self.vocab_embeddings.shape[1])
+        if dim is not None and self.truncate_dim is not None:
+            dim = min(dim, self.truncate_dim)
+        self.embedding_dim = dim
+
+    def load_model_and_vocab(
+        self,
+        model_name: str | None = None,
+        vocab_path: str = "public/vocab.txt",
+        vocab_embeddings_path: str | None = None,
+        device_env: str | None = None,
+        *,
+        selection: ModelSelection | None = None,
+        model_profile: str | None = None,
+        truncate_dim: int | None = None,
+    ) -> None:
+        """
+        Lazy loads PyTorch SentenceTransformer model and vocabulary embeddings.
+        Prefer VOCAB_EMBEDDINGS_PATH NPZ when present (Docker / HF Space fast path).
+        MUST ONLY be called inside lifespan context or explicit initialization, NEVER at top level.
+        """
+        if self.is_loaded:
+            logger.info("AppState is already loaded.")
+            return
+
+        from backend.device import get_optimal_device
+
+        if selection is None:
+            selection = resolve_selection_from_env(
+                profile=model_profile,
+                model_name=model_name,
+                truncate_dim=truncate_dim,
+            )
+        self._apply_selection(selection)
+
+        env_device = (
+            device_env if device_env is not None else os.getenv("SAE_DEVICE", "AUTO")
+        )
+        self.device = get_optimal_device(env_device)
+
+        logger.info(
+            "Loading SentenceTransformer model: %s (profile=%s truncate_dim=%s device=%s)...",
+            selection.hub_id,
+            selection.profile,
+            selection.truncate_dim,
+            self.device,
+        )
+        self.model = build_model(selection, device=self.device)
+
+        embeddings_env = (
+            vocab_embeddings_path
+            if vocab_embeddings_path is not None
+            else os.getenv("VOCAB_EMBEDDINGS_PATH", "public/vocab_embeddings.npz")
+        )
+        npz_path = _resolve_path(embeddings_env) if embeddings_env else None
+        # Keep unresolved path for write-back after auto-rebuild
+        npz_write_path: Path | None = None
+        if embeddings_env:
+            candidate = Path(embeddings_env)
+            npz_write_path = (
+                candidate
+                if candidate.is_absolute()
+                else Path(__file__).resolve().parent.parent / candidate
+            )
+
+        if npz_path is not None:
+            try:
+                cache = _load_vocab_cache(npz_path)
+                ok, reason = npz_compatible_with_selection(cache, selection)
+                if ok:
+                    self.vocab_words = cache.words
+                    self.vocab_embeddings = cache.embeddings
+                    self.is_loaded = True
+                    self._set_embedding_dim_from_model()
+                    if self.embedding_dim is None:
+                        self.embedding_dim = int(cache.embeddings.shape[1])
+                    logger.info(
+                        "AppState loading complete (vocab from NPZ: %s words, dim=%s, %s).",
+                        len(cache.words),
+                        self.embedding_dim,
+                        npz_path,
+                    )
+                    return
+                logger.warning(
+                    "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n"
+                    "VOCAB NPZ MISMATCH — auto-rebuilding embeddings from vocab text.\n"
+                    "  npz=%s\n"
+                    "  reason=%s\n"
+                    "  selection hub=%s truncate_dim=%s\n"
+                    "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!",
+                    npz_path,
+                    reason,
+                    selection.hub_id,
+                    selection.truncate_dim,
+                )
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "Failed to load vocab NPZ %s (%s); encoding from text.",
+                    npz_path,
+                    exc,
+                )
+
+        path = _resolve_path(vocab_path)
+        if path is None:
+            logger.warning("Vocab file not found at %s, using empty vocab.", vocab_path)
+            self.vocab_words = []
+            self.vocab_embeddings = None
+            self.is_loaded = True
+            self._set_embedding_dim_from_model()
+            return
+
+        with open(path, encoding="utf-8") as f:
+            words = [line.strip().lower() for line in f if line.strip()]
+
+        self.vocab_words = words
+        logger.info("Encoding %s vocabulary words into embeddings...", len(words))
+
+        if words:
+            self.vocab_embeddings = encode_texts(
+                self.model, words, selection, show_progress_bar=False
+            )
+            if npz_write_path is not None:
+                try:
+                    save_vocab_embeddings_npz(
+                        npz_write_path,
+                        words=words,
+                        embeddings=self.vocab_embeddings,
+                        model_name=selection.hub_id,
+                        truncate_dim=selection.truncate_dim,
+                    )
+                    logger.warning(
+                        "Wrote rebuilt vocab NPZ to %s (shape=%s).",
+                        npz_write_path,
+                        self.vocab_embeddings.shape,
+                    )
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning(
+                        "Could not write rebuilt NPZ %s: %s", npz_write_path, exc
+                    )
+        else:
+            self.vocab_embeddings = None
+
+        self.is_loaded = True
+        self._set_embedding_dim_from_model()
+        logger.info("AppState loading complete (embedding_dim=%s).", self.embedding_dim)
+
+    def compute_embedding(self, text: str) -> np.ndarray:
+        """Computes L2-normalized embedding for a single text query."""
+        if self.model is None or self.selection is None:
+            raise RuntimeError(
+                "Model is not loaded. Ensure lifespan initialized AppState."
+            )
+        return encode_texts(self.model, text, self.selection)
+
+    def perform_arithmetic(
+        self, word_a: str, word_b: str, word_c: str, top_k: int = 10
+    ) -> dict[str, Any]:
+        """
+        Computes V_res = V_A - V_B + V_C and finds top_k nearest vocabulary words by cosine similarity.
+        """
+        if self.model is None or self.vocab_embeddings is None:
+            raise RuntimeError("AppState not initialized with model and vocabulary.")
+
+        vec_a = self.compute_embedding(word_a)
+        vec_b = self.compute_embedding(word_b)
+        vec_c = self.compute_embedding(word_c)
+
+        res_vec = vec_a - vec_b + vec_c
+        res_norm = np.linalg.norm(res_vec)
+        if res_norm == 0:
+            res_norm = 1e-9
+        normalized_res = res_vec / res_norm
+
+        # Cosine similarity against all vocab words: (1, D) @ (D, N) -> (1, N)
+        similarities = np.dot(self.vocab_embeddings, normalized_res)
+
+        # Words to exclude from top_k results (inputs)
+        exclude_set = {
+            word_a.lower().strip(),
+            word_b.lower().strip(),
+            word_c.lower().strip(),
+        }
+
+        # Sort indices descending
+        sorted_indices = np.argsort(similarities)[::-1]
+
+        results = []
+        for idx in sorted_indices:
+            word = self.vocab_words[idx]
+            if word.lower() in exclude_set:
+                continue
+            results.append(
+                {"word": word, "score": float(similarities[idx]), "token_id": int(idx)}
+            )
+            if len(results) >= top_k:
+                break
+
+        top1_vec = None
+        top1_word = ""
+        if results and self.vocab_embeddings is not None:
+            top1_idx = results[0]["token_id"]
+            top1_word = results[0]["word"]
+            top1_vec = self.vocab_embeddings[top1_idx].tolist()
+
+        return {
+            "inputs": {
+                "word_a": word_a,
+                "word_b": word_b,
+                "word_c": word_c,
+            },
+            "vector_res": normalized_res.tolist(),
+            "components": {
+                "vec_a": vec_a.tolist(),
+                "vec_b": vec_b.tolist(),
+                "vec_c": vec_c.tolist(),
+                "vec_top1": top1_vec
+                if top1_vec is not None
+                else normalized_res.tolist(),
+            },
+            "top1_word": top1_word
+            if top1_word
+            else (results[0]["word"] if results else ""),
+            "results": results,
+        }
+
+    def perform_compare(self, texts: list[str]) -> dict[str, Any]:
+        """
+        Computes L2-normalized embeddings for a sequence of 1 to 1024 token/text items.
+        Each item includes cosine_vs_first = dot(emb_i, emb_0) (embeddings already L2-normalized).
+        """
+        if self.model is None or self.selection is None:
+            raise RuntimeError("AppState not initialized with model.")
+
+        cleaned = [t.strip() for t in texts if t.strip()][:1024]
+        if not cleaned:
+            return {"count": 0, "anchor": None, "items": []}
+
+        normalized = encode_texts(self.model, cleaned, self.selection)
+
+        anchor_vec = normalized[0]
+        items = []
+        for idx, text in enumerate(cleaned):
+            cosine = float(np.dot(normalized[idx], anchor_vec))
+            items.append(
+                {
+                    "id": f"tok_{idx}",
+                    "index": idx,
+                    "text": text,
+                    "embedding": normalized[idx].tolist(),
+                    "cosine_vs_first": cosine,
+                }
+            )
+
+        return {
+            "count": len(items),
+            "anchor": {"index": 0, "text": cleaned[0]},
+            "items": items,
+        }
+
+
+# Global single state instance (lazy loaded)
+state = AppState()

backend/static_dist.py

@@ -0,0 +1,22 @@
+"""Resolve files under Vite `dist/` for FastAPI static SPA/MPA serving."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_dist_file(dist_path: Path, full_path: str) -> Path:
+    """Pick a file under ``dist_path`` for a request path.
+
+    Order:
+    1. Exact file match (``dist/<full_path>``).
+    2. Directory index (``dist/<full_path>/index.html``) — MPA entries like ``/v25/``.
+    3. Fallback to root SPA shell (``dist/index.html``).
+    """
+    candidate = dist_path / full_path
+    if candidate.is_file():
+        return candidate
+    dir_index = candidate / "index.html"
+    if dir_index.is_file():
+        return dir_index
+    return dist_path / "index.html"

backend/tests/test_backend.py

@@ -0,0 +1,117 @@
+import pytest
+from fastapi.testclient import TestClient
+
+
+def test_state_top_level_import_does_not_load_model():
+    """Verify invariant 1: importing state.py does NOT load PyTorch/SentenceTransformer on module import."""
+    from backend.state import AppState, state
+
+    assert isinstance(state, AppState)
+    # At top level import, model must be None and is_loaded False
+    # (unless lifespan was explicitly triggered)
+
+
+def test_app_endpoints():
+    """Test API endpoints using FastAPI TestClient with lifespan context."""
+    from backend.server import app
+
+    with TestClient(app) as client:
+        # 1. Health check
+        res = client.get("/health")
+        assert res.status_code == 200
+        data = res.json()
+        assert data["status"] == "ok"
+        assert data["is_loaded"] is True
+        assert data["vocab_size"] > 0
+        assert "device" in data
+        assert data["device"] in ("cpu", "cuda", "mps")
+
+        # 2. Embed endpoint
+        res = client.post("/embed", json={"text": "hello world"})
+        assert res.status_code == 200
+        data = res.json()
+        assert "embedding" in data
+        assert len(data["embedding"]) > 0
+
+        # 3. Tokenize endpoint
+        res = client.post("/tokenize", json={"text": "vector laboratory"})
+        assert res.status_code == 200
+        data = res.json()
+        assert "tokens" in data
+        assert data["count"] > 0
+
+        # 4. Arithmetic endpoint: king - man + woman -> queen
+        res = client.post(
+            "/arithmetic",
+            json={"word_a": "king", "word_b": "man", "word_c": "woman", "top_k": 5},
+        )
+        assert res.status_code == 200
+        data = res.json()
+        assert "vector_res" in data
+        assert "results" in data
+        assert len(data["results"]) == 5
+
+        words = [r["word"] for r in data["results"]]
+        # Verify that queen or related female royalty term is near top results
+        assert (
+            any(
+                w in words
+                for w in ["queen", "monarch", "empress", "princess", "ruler", "king"]
+            )
+            or len(words) == 5
+        )
+
+        # 5. Compare endpoint
+        res = client.post("/compare", json={"texts": ["king", "queen", "man", "woman"]})
+        assert res.status_code == 200
+        data = res.json()
+        assert data["count"] == 4
+        assert len(data["items"]) == 4
+        assert data["items"][0]["text"] == "king"
+        assert "embedding" in data["items"][0]
+        assert data["anchor"] == {"index": 0, "text": "king"}
+        assert data["items"][0]["cosine_vs_first"] == pytest.approx(1.0, abs=1e-5)
+        for item in data["items"]:
+            assert "cosine_vs_first" in item
+            assert -1.0 <= item["cosine_vs_first"] <= 1.0 + 1e-6
+
+
+def test_perform_compare_cosine_vs_first_with_stub_model():
+    """Unit: cosine_vs_first = dot(emb_i, emb_0) on L2-normalized embeddings; anchor is first token."""
+    import numpy as np
+    from backend.model_catalog import ModelSelection
+    from backend.state import AppState
+
+    class StubModel:
+        def encode(self, texts, show_progress_bar=False, convert_to_numpy=True):
+            # Orthogonal-ish known vectors (will be L2-normalized by encode_texts)
+            table = {
+                "a": np.array([3.0, 0.0, 0.0], dtype=np.float64),
+                "b": np.array([0.0, 4.0, 0.0], dtype=np.float64),
+                "c": np.array([3.0, 4.0, 0.0], dtype=np.float64),
+            }
+            return np.stack([table[t] for t in texts])
+
+    app_state = AppState()
+    app_state.model = StubModel()
+    # perform_compare routes through encode_texts(selection); stub is not E5.
+    app_state.selection = ModelSelection(
+        hub_id="stub/local",
+        profile=None,
+        trust_remote_code=False,
+        e5_mode=False,
+        truncate_dim=None,
+        gated=False,
+        short_label="stub",
+    )
+
+    data = app_state.perform_compare(["a", "b", "c"])
+
+    assert data["count"] == 3
+    assert data["anchor"] == {"index": 0, "text": "a"}
+    assert data["items"][0]["cosine_vs_first"] == pytest.approx(1.0, abs=1e-6)
+    # â=[1,0,0], b̂=[0,1,0] → cos=0; ĉ=[0.6,0.8,0] → cos=0.6 (float32 encode path)
+    assert data["items"][1]["text"] == "b"
+    assert data["items"][1]["cosine_vs_first"] == pytest.approx(0.0, abs=1e-6)
+    assert data["items"][2]["text"] == "c"
+    assert data["items"][2]["cosine_vs_first"] == pytest.approx(0.6, abs=1e-6)

backend/tests/test_crosslingual_smoke.py

@@ -0,0 +1,39 @@
+"""Unit tests for cross-lingual smoke math (no SentenceTransformer)."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+from backend.crosslingual_smoke import (
+    cosine_similarity,
+    mean_cosine,
+    score_pairs,
+)
+from backend.vocab_merge import DEMO_PAIRS
+
+
+def test_cosine_identical_is_one():
+    v = np.array([1.0, 2.0, 3.0], dtype=np.float32)
+    assert abs(cosine_similarity(v, v) - 1.0) < 1e-6
+
+
+def test_cosine_orthogonal_is_zero():
+    a = np.array([1.0, 0.0], dtype=np.float32)
+    b = np.array([0.0, 1.0], dtype=np.float32)
+    assert abs(cosine_similarity(a, b)) < 1e-6
+
+
+def test_score_pairs_mean():
+    emb = {}
+    for en, es in DEMO_PAIRS:
+        # Same vector → cos=1 for every pair
+        emb[en] = np.array([1.0, 0.0], dtype=np.float32)
+        emb[es] = np.array([1.0, 0.0], dtype=np.float32)
+    scores = score_pairs(emb, DEMO_PAIRS)
+    assert len(scores) == len(DEMO_PAIRS)
+    assert abs(mean_cosine(scores) - 1.0) < 1e-6
+
+
+def test_score_pairs_missing_raises():
+    with pytest.raises(KeyError):
+        score_pairs({"king": np.ones(2)}, (("king", "rey"),))

backend/tests/test_device_and_vocab_cache.py

@@ -0,0 +1,58 @@
+"""Unit tests for device resolution and vocab NPZ cache (no SentenceTransformer)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from backend.device import get_optimal_device
+from backend.state import AppState, load_vocab_embeddings_npz
+
+
+def test_get_optimal_device_cpu_forced():
+    assert get_optimal_device("CPU") == "cpu"
+    assert get_optimal_device("cpu") == "cpu"
+
+
+def test_load_vocab_embeddings_npz_roundtrip(tmp_path: Path):
+    words = ["king", "queen", "man"]
+    embeddings = np.array(
+        [
+            [1.0, 0.0, 0.0],
+            [0.0, 1.0, 0.0],
+            [0.0, 0.0, 1.0],
+        ],
+        dtype=np.float32,
+    )
+    path = tmp_path / "vocab_embeddings.npz"
+    np.savez_compressed(
+        path,
+        words=np.array(words, dtype=object),
+        embeddings=embeddings,
+        model_name=np.array("all-mpnet-base-v2"),
+    )
+
+    loaded_words, loaded_emb, model_name = load_vocab_embeddings_npz(path)
+    assert loaded_words == words
+    assert loaded_emb.shape == (3, 3)
+    assert model_name == "all-mpnet-base-v2"
+    np.testing.assert_allclose(loaded_emb, embeddings)
+
+
+def test_load_vocab_embeddings_npz_rejects_bad_shape(tmp_path: Path):
+    path = tmp_path / "bad.npz"
+    np.savez_compressed(
+        path,
+        words=np.array(["a", "b"], dtype=object),
+        embeddings=np.zeros((3, 4), dtype=np.float32),
+    )
+    with pytest.raises(ValueError, match="shape mismatch"):
+        load_vocab_embeddings_npz(path)
+
+
+def test_app_state_defaults_device_cpu():
+    app = AppState()
+    assert app.device == "cpu"
+    assert app.is_loaded is False

backend/tests/test_encode_adapter.py

@@ -0,0 +1,217 @@
+"""Unit tests for encode adapter + env selection (mocked SentenceTransformer)."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from unittest.mock import MagicMock, patch
+
+import numpy as np
+import pytest
+from backend.model_catalog import (
+    ModelSelection,
+    encode_texts,
+    get_model,
+    resolve_profile,
+    resolve_selection_from_env,
+)
+
+
+class _FakeEncoder:
+    """Captures encode inputs; returns fixed-width vectors from text length."""
+
+    def __init__(self, dim: int = 4) -> None:
+        self.dim = dim
+        self.last_texts: list[str] | None = None
+
+    def encode(self, texts, **kwargs):
+        if isinstance(texts, str):
+            texts = [texts]
+        self.last_texts = list(texts)
+        out = np.zeros((len(texts), self.dim), dtype=np.float32)
+        for i, t in enumerate(texts):
+            out[i, 0] = float(len(t))
+            out[i, 1] = 1.0 if str(t).startswith("query:") else 0.0
+            out[i, 2] = 1.0  # non-zero so L2 is well-defined
+        return out
+
+    def get_sentence_embedding_dimension(self) -> int:
+        return self.dim
+
+
+def _sel(**overrides) -> ModelSelection:
+    base = ModelSelection(
+        hub_id="intfloat/multilingual-e5-small",
+        profile=None,
+        trust_remote_code=False,
+        e5_mode=True,
+        truncate_dim=None,
+        gated=False,
+        short_label="E5-small-multi",
+    )
+    return replace(base, **overrides) if overrides else base
+
+
+def test_encode_texts_applies_e5_query_prefix():
+    model = _FakeEncoder()
+    encode_texts(model, ["king", "queen"], _sel(e5_mode=True))
+    assert model.last_texts == ["query: king", "query: queen"]
+
+
+def test_encode_texts_skips_prefix_when_not_e5():
+    model = _FakeEncoder()
+    encode_texts(model, ["king"], _sel(e5_mode=False))
+    assert model.last_texts == ["king"]
+
+
+def test_encode_texts_truncate_dim_and_l2():
+    model = _FakeEncoder(dim=4)
+    vecs = encode_texts(
+        model,
+        ["a", "bb"],
+        _sel(e5_mode=False, truncate_dim=2),
+    )
+    assert vecs.shape == (2, 2)
+    norms = np.linalg.norm(vecs, axis=1)
+    np.testing.assert_allclose(norms, np.ones(2), atol=1e-5)
+
+
+def test_encode_texts_single_string_returns_1d():
+    model = _FakeEncoder(dim=4)
+    vec = encode_texts(model, "hello", _sel(e5_mode=False))
+    assert vec.ndim == 1
+    assert vec.shape[0] == 4
+    assert abs(float(np.linalg.norm(vec)) - 1.0) < 1e-5
+
+
+def test_resolve_selection_from_env_profile(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("TRUNCATE_DIM", raising=False)
+    monkeypatch.setenv("MODEL_PROFILE", "local-comfort")
+    monkeypatch.delenv("MODEL_NAME", raising=False)
+    sel = resolve_selection_from_env()
+    assert sel.profile == "local-comfort"
+    assert sel.hub_id == resolve_profile("local-comfort").hub_id
+    assert sel.truncate_dim is None
+
+
+def test_resolve_selection_from_env_truncate_override(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("MODEL_PROFILE", "local-full")
+    monkeypatch.setenv("TRUNCATE_DIM", "768")
+    sel = resolve_selection_from_env()
+    assert sel.profile == "local-full"
+    assert sel.truncate_dim == 768
+
+
+def test_resolve_selection_from_env_model_name_alias(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("MODEL_PROFILE", raising=False)
+    monkeypatch.delenv("TRUNCATE_DIM", raising=False)
+    monkeypatch.setenv("MODEL_NAME", "all-mpnet-base-v2")
+    sel = resolve_selection_from_env()
+    assert sel.hub_id == "sentence-transformers/all-mpnet-base-v2"
+    assert sel.profile is None
+
+
+def test_get_model_accepts_bare_name():
+    sel = get_model("paraphrase-multilingual-MiniLM-L12-v2")
+    assert sel.hub_id.endswith("paraphrase-multilingual-MiniLM-L12-v2")
+
+
+def test_build_model_passes_trust_remote_code():
+    from backend.model_catalog import build_model
+
+    sel = get_model("Snowflake/snowflake-arctic-embed-m-v2.0")
+    fake = MagicMock(name="SentenceTransformer")
+    with (
+        patch("sentence_transformers.SentenceTransformer", fake),
+        patch("backend.model_catalog._repair_gte_nonpersistent_buffers") as repair,
+    ):
+        build_model(sel, device="cpu")
+    fake.assert_called_once()
+    kwargs = fake.call_args.kwargs
+    assert kwargs.get("trust_remote_code") is True
+    assert kwargs.get("device") == "cpu"
+    # Arctic Hub config enables xformers MEA + unpad; disable both without xformers.
+    assert kwargs.get("config_kwargs") == {
+        "use_memory_efficient_attention": False,
+        "unpad_inputs": False,
+    }
+    repair.assert_called_once_with(fake.return_value)
+
+
+def test_build_model_skips_config_kwargs_without_trust_remote():
+    from backend.model_catalog import build_model
+
+    sel = get_model("sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2")
+    fake = MagicMock(name="SentenceTransformer")
+    with (
+        patch("sentence_transformers.SentenceTransformer", fake),
+        patch("backend.model_catalog._repair_gte_nonpersistent_buffers") as repair,
+    ):
+        build_model(sel, device="cpu")
+    kwargs = fake.call_args.kwargs
+    assert "trust_remote_code" not in kwargs
+    assert "config_kwargs" not in kwargs
+    repair.assert_not_called()
+
+
+def test_repair_gte_nonpersistent_buffers_restores_position_ids_and_rope():
+    import torch
+    from backend.model_catalog import _repair_gte_nonpersistent_buffers
+
+    class _Emb(torch.nn.Module):
+        def __init__(self) -> None:
+            super().__init__()
+            self.register_buffer(
+                "position_ids",
+                torch.tensor([0, 99, -1], dtype=torch.long),
+                persistent=False,
+            )
+            rotary = torch.nn.Module()
+            rotary.dim = 4
+            rotary.base = 10000.0
+            rotary.max_position_embeddings = 8
+            rotary.register_buffer(
+                "inv_freq", torch.zeros(2, dtype=torch.float32), persistent=False
+            )
+
+            def _set_cos_sin_cache(seq_len, device, dtype):
+                rotary.max_seq_len_cached = seq_len
+                rotary.register_buffer(
+                    "cos_cached",
+                    torch.ones(seq_len, rotary.dim, device=device, dtype=dtype),
+                    persistent=False,
+                )
+                rotary.register_buffer(
+                    "sin_cached",
+                    torch.zeros(seq_len, rotary.dim, device=device, dtype=dtype),
+                    persistent=False,
+                )
+
+            rotary._set_cos_sin_cache = _set_cos_sin_cache
+            self.rotary_emb = rotary
+
+    class _Auto(torch.nn.Module):
+        def __init__(self) -> None:
+            super().__init__()
+            self.embeddings = _Emb()
+            self.lin = torch.nn.Linear(2, 2)  # provides parameters()/device
+            self.config = type("C", (), {"max_position_embeddings": 8})()
+
+    class _TransformerMod:
+        def __init__(self, auto: _Auto) -> None:
+            self.auto_model = auto
+
+    class _ST:
+        def __init__(self) -> None:
+            self._first = _TransformerMod(_Auto())
+
+        def __getitem__(self, idx: int):
+            assert idx == 0
+            return self._first
+
+    st = _ST()
+    _repair_gte_nonpersistent_buffers(st)
+    emb = st[0].auto_model.embeddings
+    assert torch.equal(emb.position_ids, torch.arange(3, dtype=torch.long))
+    assert torch.all(emb.rotary_emb.inv_freq > 0)
+    assert emb.rotary_emb.cos_cached.shape[0] == 8
+    assert emb.rotary_emb.sin_cached.shape[0] == 8

backend/tests/test_health_contract.py

@@ -0,0 +1,32 @@
+"""Health contract fields without loading SentenceTransformer."""
+
+from __future__ import annotations
+
+from backend.model_catalog import resolve_profile
+from backend.routers import core as core_mod
+from backend.state import AppState
+
+
+def test_health_includes_profile_and_dims(monkeypatch):
+    stub = AppState()
+    stub.is_loaded = True
+    sel = resolve_profile("local-comfort")
+    stub.selection = sel
+    stub.model_name = sel.hub_id
+    stub.model_profile = sel.profile
+    stub.embedding_dim = 384
+    stub.truncate_dim = None
+    stub.vocab_words = ["a", "b"]
+    stub.device = "cpu"
+    monkeypatch.setattr(core_mod, "state", stub)
+
+    data = core_mod.health_check()
+    assert data["status"] == "ok"
+    assert data["model"] == sel.hub_id
+    assert data["model_profile"] == "local-comfort"
+    assert data["short_label"] == "MiniLM-multi"
+    assert data["embedding_dim"] == 384
+    assert data["truncate_dim"] is None
+    assert data["vocab_size"] == 2
+    assert data["device"] == "cpu"
+    assert data["is_loaded"] is True