@bacano/sdk 1.1.9 → 1.1.12

package/skills/bacano-figma-web/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: bacano-figma-web
+description: Convierte diseños de Figma en webs y tiendas construidas con @bacano/sdk, preservando el cascarón, contratos, Static First y comportamiento oficial de Bacano. Usar al implementar una web desde enlaces, frames o archivos Figma; configurar o diagnosticar Figma MCP, Figma Desktop MCP, Desktop Bridge o REST; extraer un diseño por páginas; mapearlo a Content y componentes; o comparar visualmente la implementación con Figma.
+---
+
+# Bacano Figma Web
+
+Implementar Figma como fuente visual y Bacano como fuente funcional. No copiar
+una captura como HTML aislado ni reconstruir catálogo, carrito, checkout,
+autenticación, marketing o Content por fuera de `@bacano/sdk`.
+
+## 1. Confirmar el alcance
+
+Antes de extraer el diseño, identificar:
+
+- Web informativa o tienda virtual.
+- Enlace al archivo, página, sección o frame de Figma.
+- Rutas que se implementarán y sus frames desktop/mobile.
+- Repositorio y cascarón Bacano que se reutilizarán.
+- Fuente Figma disponible y política de fallback.
+
+Si falta una decisión que cambie materialmente el resultado, hacer una sola
+pregunta corta. No solicitar un token por chat ni pedir que se guarde en el
+repositorio.
+
+## 2. Resolver la conexión con Figma
+
+Ejecutar primero:
+
+```bash
+pnpm exec bacano-figma-web doctor
+```
+
+Leer [references/connection-official.md](references/connection-official.md) si
+falta instalar o autenticar el MCP oficial. Usar este orden:
+
+1. MCP remoto oficial de Figma.
+2. MCP local oficial de Figma Desktop.
+3. Desktop Bridge comunitario, local y con versión revisada/fijada.
+4. Snapshot mediante REST, únicamente con autorización explícita.
+
+No cambiar silenciosamente de fuente. Si la fuente seleccionada se agota,
+responde `429` o no expone una capacidad necesaria, conservar el avance y pedir
+permiso antes del fallback, salvo que el usuario haya aprobado modo automático.
+Leer la guía específica únicamente cuando se elija
+[Desktop Bridge](references/connection-desktop-bridge.md) o
+[REST](references/connection-rest-api.md).
+
+## 3. Extraer una vez y normalizar
+
+Leer [references/extraction-contract.md](references/extraction-contract.md).
+Crear o reutilizar un snapshot normalizado en `.bacano/designs/<proyecto>/`.
+No consultar cada sección por separado si una lectura de página/frame entrega
+el contexto suficiente.
+
+Evaluar y registrar como `DISPONIBLE`, `PARCIAL` o `AUSENTE`:
+
+- Variables y estilos.
+- Componentes y variantes.
+- Auto Layout, constraints y geometría.
+- Nombres de capas.
+- Frames desktop/mobile.
+- Estados e interacciones.
+
+La ausencia de variables o componentes no bloquea por sí sola. Inferir desde
+geometría y evidencia visual, pero registrar cada inferencia. Nunca incluir PAT,
+cookies, secretos, correos privados ni contenido no necesario en el snapshot.
+
+Validar el manifiesto:
+
+```bash
+pnpm exec bacano-figma-web validate-snapshot .bacano/designs/<proyecto>/manifest.json
+```
+
+## 4. Mapear a Bacano antes de programar
+
+Leer [references/bacano-mapping.md](references/bacano-mapping.md) y
+[references/content-workflow.md](references/content-workflow.md). Preparar una
+matriz ruta → frame → componente → fuente de datos → estado responsive y
+determinar si el trabajo comienza desde Figma, desde Bacano Content o desde
+ambas fuentes.
+
+- Reutilizar el starter, tokens y componentes existentes.
+- Consumir Bacano y Content mediante `@bacano/sdk`.
+- Mantener un solo `BacanoProvider` y un solo cliente por árbol.
+- Preservar Static First: estructura estática y estado comercial vivo mediante
+  los contratos específicos del SDK.
+- No usar GraphQL directo, endpoints internos ni lógica comercial duplicada.
+- No codificar textos editables si pertenecen a Bacano Content.
+- No alterar Baby Rex u otra referencia salvo que ese sea el proyecto indicado.
+
+Si Content todavía no existe, generar un blueprint de entrega y fixtures
+temporales fieles al contenido visible de Figma. Los fixtures deben usar el
+mismo view model que consumen los componentes y entrar por un único adaptador;
+nunca repartir datos de prueba dentro de la UI. Si Content ya existe, mapearlo
+sin sobrescribir estructuras o entradas. Si el usuario pide materializar el
+blueprint, leer la sección de automatización de
+[references/content-workflow.md](references/content-workflow.md) y el contrato
+`CONTENT_TYPE_MANAGEMENT.md` incluido en `@bacano/sdk`. Solo crear o modificar
+tipos y componentes mediante el acceso temporal oficial; las entradas y media
+permanecen en el backoffice.
+
+Antes de modificar código, indicar brevemente qué rutas y componentes se
+implementarán y qué decisiones de diseño son inferidas.
+
+## 5. Implementar por cortes verificables
+
+Trabajar por página o conjunto pequeño de secciones:
+
+1. Estructura semántica y responsive.
+2. Tokens, tipografía, espacios y media.
+3. Estados interactivos y accesibilidad.
+4. Integración Bacano real.
+5. Comparación visual y correcciones.
+
+No añadir paquetes, fuentes, iconos o assets si el proyecto ya ofrece un
+equivalente. Descargar assets mediante la fuente Figma autorizada; no incrustar
+URLs temporales ni construir transformaciones de Storage manualmente.
+
+## 6. Validar diseño y contrato
+
+Leer [references/visual-validation.md](references/visual-validation.md).
+Comparar con evidencia desktop y mobile, incluyendo viewport, captura y
+diferencias relevantes. Probar además typecheck, lint, tests y build del
+proyecto.
+
+Antes de aprobar producción, comprobar que la fuente editorial efectiva sea
+Bacano Content. Un fixture, placeholder o fallback temporal accesible en el
+build de producción es un bloqueo, aunque visualmente coincida con Figma.
+
+Al finalizar, invocar `$bacano-web` si está disponible para la auditoría de
+producción completa. Esta skill valida fidelidad y correcta integración desde
+Figma; `bacano-web` valida que el sitio pueda publicarse profesionalmente.
+
+## 7. Entregar un cierre claro
+
+Reportar:
+
+- Fuente Figma y fallback usados.
+- Páginas/frames extraídos e implementados.
+- Snapshot y versión/fecha de extracción.
+- Componentes Bacano reutilizados.
+- Inferencias y diferencias aprobadas.
+- Validaciones ejecutadas y pendientes reales.
+- Brechas del SDK, sin workarounds directos a API o GraphQL.

package/skills/bacano-figma-web/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bacano Figma Web"
+  short_description: "Convierte diseños Figma en sitios Bacano"
+  default_prompt: "Usa $bacano-figma-web para implementar este diseño de Figma con el cascarón y los contratos oficiales de Bacano."

package/skills/bacano-figma-web/references/bacano-mapping.md

@@ -0,0 +1,38 @@
+# Mapeo de Figma a Bacano
+
+Figma decide presentación. Bacano decide datos, permisos, estados y reglas de
+negocio.
+
+## Matriz obligatoria
+
+Antes de programar, registrar por ruta:
+
+| Ruta | Frame | Componente | Fuente | Responsive | Estado |
+| --- | --- | --- | --- | --- | --- |
+| `/` | Home desktop/mobile | `Hero` | Content | 2 frames | pendiente |
+
+Fuentes posibles: Content, catálogo estático, live state, public config,
+checkout, auth u otra operación documentada del SDK.
+
+## Reglas
+
+- Usar componentes y tokens existentes antes de crear otros.
+- Mapear textos/imágenes editoriales a Content cuando deban ser administrables.
+- Si el equipo de Content y desarrollo trabajan en tiempos distintos, seguir
+  [content-workflow.md](content-workflow.md) y mantener un único contrato de
+  datos entre fixtures temporales y Bacano real.
+- Usar `responsiveSources` y helpers oficiales para media; no construir URLs de
+  Storage manualmente.
+- Mantener HTML semántico, canonical, metadata, JSON-LD y sitemap.
+- En tiendas, conservar rutas de producto y `product_variant_id` definidos por
+  el contrato del SDK.
+- La estructura del catálogo puede venir del build; precio, disponibilidad y
+  límites se actualizan con live state/cart oficial.
+- Montar proveedores globales una sola vez.
+- Preview reutiliza los mismos componentes y cliente; no crear un storefront
+  paralelo para “parecerse” a Figma.
+- Marketing se emite mediante el runtime/hook oficial, nunca desde clicks
+  duplicados escritos solo para una página.
+
+Si el SDK no ofrece una capacidad, documentar la brecha. No llamar GraphQL o
+endpoints internos como workaround.

package/skills/bacano-figma-web/references/connection-desktop-bridge.md

@@ -0,0 +1,45 @@
+# Desktop Bridge comunitario
+
+“Figma Desktop Bridge” no es el MCP local oficial de Figma. Esta guía se refiere
+al bridge incluido por el proyecto comunitario `southleft/figma-console-mcp`,
+que conecta un plugin de Figma Desktop con su servidor MCP.
+
+Usarlo solo cuando el MCP oficial no exponga datos locales necesarios, por
+ejemplo determinadas variables o descripciones accesibles mediante Plugin API.
+
+## Reglas de seguridad
+
+- Preferir modo local.
+- Revisar el repositorio y fijar una versión o commit aprobado; no depender de
+  `@latest` en automatizaciones reproducibles.
+- Mantener Figma Desktop abierto y el plugin activo durante la extracción.
+- No exponer ni redirigir a Internet los puertos locales `9223`–`9232`.
+- Guardar el PAT en el almacén de secretos o entorno del cliente MCP, nunca en
+  `.mcp.json`, el repositorio, el snapshot o los logs.
+- No habilitar cloud relay o escritura sin autorización explícita.
+
+## Instalación orientativa
+
+El proyecto upstream publica instrucciones actualizadas en:
+
+- https://github.com/southleft/figma-console-mcp
+- https://github.com/southleft/figma-console-mcp/blob/main/figma-desktop-bridge/README.md
+
+Seguir la versión revisada de esas instrucciones para:
+
+1. Instalar/configurar el servidor MCP comunitario.
+2. Importar el manifest del plugin generado por el servidor.
+3. Abrir el plugin dentro del archivo Figma.
+4. Confirmar la conexión local del bridge.
+5. Ejecutar una lectura mínima antes de extraer todas las páginas.
+
+El comando `pnpm exec bacano-figma-web doctor` solo detecta puertos locales
+compatibles. No demuestra que el plugin esté conectado, que el archivo sea el
+correcto ni que el servidor sea confiable; esas tres condiciones deben
+verificarse dentro del agente.
+
+## Salida esperada
+
+Normalizar la respuesta del bridge al mismo manifiesto definido en
+`extraction-contract.md`. No permitir que detalles propios del bridge se filtren
+a los componentes React ni a los contratos públicos de Bacano.

package/skills/bacano-figma-web/references/connection-official.md

@@ -0,0 +1,127 @@
+# Conexión oficial con Figma
+
+Elegir preferiblemente el MCP remoto oficial. Requiere autorización de la
+cuenta Figma, pero no mantener Figma Desktop abierto.
+
+## MCP remoto oficial
+
+Endpoint oficial:
+
+```text
+https://mcp.figma.com/mcp
+```
+
+### Codex CLI
+
+```bash
+codex mcp add figma --url https://mcp.figma.com/mcp
+```
+
+Completar OAuth cuando Codex lo solicite. En la aplicación Codex también puede
+instalarse/conectarse el plugin oficial de Figma desde Plugins.
+
+### Claude Code
+
+Figma recomienda primero su plugin oficial:
+
+```bash
+claude plugin install figma@claude-plugins-official
+```
+
+Configuración manual equivalente:
+
+```bash
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+```
+
+Usar `--scope user` únicamente si la conexión debe estar disponible en todos
+los proyectos de ese usuario.
+
+### VS Code y clientes MCP compatibles
+
+```json
+{
+  "inputs": [],
+  "servers": {
+    "figma": {
+      "url": "https://mcp.figma.com/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+No copiar tokens dentro del archivo. El cliente debe realizar OAuth.
+
+### Cursor
+
+Figma recomienda instalar su plugin oficial desde el chat del agente:
+
+```text
+/add-plugin figma
+```
+
+En otros agentes, comprobar primero que aparezcan en el catálogo de clientes
+admitidos por Figma. No asumir que cualquier cliente MCP puede completar el
+OAuth del servidor remoto.
+
+## MCP local oficial de Figma Desktop
+
+Usarlo cuando se necesite trabajar con la selección actual del archivo o el MCP
+remoto no sea apropiado para la organización.
+
+1. Actualizar y abrir Figma Desktop.
+2. Abrir un archivo Design.
+3. Activar Dev Mode con `Shift+D`.
+4. En el panel Inspect, habilitar Desktop MCP.
+5. Mantener Figma Desktop y el archivo abiertos.
+
+Endpoint local:
+
+```text
+http://127.0.0.1:3845/mcp
+```
+
+Claude Code:
+
+```bash
+claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
+```
+
+Configuración genérica:
+
+```json
+{
+  "servers": {
+    "figma-desktop": {
+      "url": "http://127.0.0.1:3845/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+## Verificación dentro del agente
+
+La CLI de Bacano no puede inspeccionar el registro MCP ni el OAuth privado de
+todos los agentes. Dentro de la conversación, comprobar:
+
+1. Que exista una herramienta Figma disponible.
+2. Ejecutar `whoami` cuando el servidor la exponga.
+3. Leer un frame pequeño mediante su enlace exacto.
+4. Confirmar que el agente recibe contexto de diseño, no solo una captura.
+
+El servidor remoto trabaja mediante un enlace exacto al frame/capa. La
+selección actual sin enlace está disponible únicamente con el servidor Desktop.
+
+Según Figma, los límites dependen del plan y asiento. Actualmente un asiento Dev
+o Full en Professional admite hasta 200 lecturas diarias y 10 por minuto; Figma
+puede modificar esos límites. Ante `429`, conservar el snapshot y reanudar
+después, sin repetir nodos ya extraídos.
+
+Fuentes oficiales:
+
+- https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/
+- https://developers.figma.com/docs/figma-mcp-server/local-server-installation/
+- https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/
+- https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/

package/skills/bacano-figma-web/references/connection-rest-api.md

@@ -0,0 +1,35 @@
+# REST API como respaldo
+
+Usar REST solamente cuando el usuario autorice crear un snapshot y el MCP
+oficial/Desktop/Bridge no estén disponibles. REST entrega datos más crudos y no
+reemplaza el contexto preparado por `get_design_context`.
+
+## Autenticación
+
+Figma admite OAuth y personal access tokens. Para una tarea local controlada,
+inyectar el token mediante el entorno del proceso:
+
+```bash
+export FIGMA_ACCESS_TOKEN="..."
+```
+
+No escribirlo en `.env` versionado, argumentos de terminal persistidos,
+manifiestos, código cliente, capturas o registros. `doctor` informa únicamente
+si la variable existe; nunca lee ni muestra su valor.
+
+## Extracción responsable
+
+1. Obtener el file key desde el enlace autorizado.
+2. Consultar solo páginas/nodos necesarios.
+3. Registrar versión/fecha del archivo en el snapshot.
+4. Descargar imágenes/assets una vez y conservar su procedencia.
+5. Respetar `429` y encabezados de espera; no crear reintentos agresivos.
+6. No guardar el JSON completo si contiene páginas ajenas al alcance.
+
+El snapshot resultante debe seguir `extraction-contract.md`. Nunca incluir el
+token ni URLs firmadas temporales como contrato permanente.
+
+Fuentes oficiales:
+
+- https://developers.figma.com/docs/rest-api/authentication/
+- https://developers.figma.com/docs/rest-api/rate-limits/

package/skills/bacano-figma-web/references/content-workflow.md

@@ -0,0 +1,169 @@
+# Flujo de contenido entre Figma, desarrollo y Bacano
+
+Diseño, programación y gestión editorial pueden comenzar en cualquier orden.
+La coordinación se hace mediante un blueprint de contenido; Figma no se
+convierte en base de datos y los componentes no dependen de datos temporales.
+
+## 1. Clasificar la propiedad de cada dato
+
+Antes de crear campos o fixtures, asignar cada valor a una fuente:
+
+| Información | Fuente habitual |
+| --- | --- |
+| Títulos, textos, banners y bloques editoriales | Bacano Content |
+| Productos, variantes, precios y disponibilidad | Catálogo y live state del SDK |
+| Legal, branding y configuración del sitio | `publicConfig` |
+| Carrito, checkout, cliente y pedidos | Módulo correspondiente del SDK |
+| Etiquetas permanentes de interfaz | Código e i18n del storefront |
+
+No duplicar en Content información que ya tiene una fuente funcional. Un valor
+visible en Figma no implica que sea editorial.
+
+## 2. Elegir el punto de partida
+
+### Figma primero
+
+1. Extraer el contenido público visible y sus assets autorizados.
+2. Proponer tipos, keys, campos y entradas en `content-blueprint.json`.
+3. Crear fixtures locales que implementen el view model de la página.
+4. Implementar y validar el diseño contra esos fixtures.
+5. Entregar el blueprint al equipo de Content para crearlo en Bacano.
+6. Conectar las keys reales sin modificar los componentes visuales.
+
+### Bacano Content primero
+
+1. Inventariar tipos, campos, keys y entradas existentes mediante contratos
+   públicos documentados.
+2. Mapear los frames de Figma al contenido real.
+3. Señalar incompatibilidades de estructura antes de programar.
+4. Reutilizar las keys existentes; no crear aliases o estructuras paralelas
+   únicamente para hacer coincidir un frame.
+
+### Fuentes en paralelo
+
+Comparar el blueprint propuesto con Bacano. Clasificar cada sección como
+`ready`, `missing`, `needs-mapping` o `blocked` y asignar responsable. No
+sobrescribir datos reales ni asumir que el diseño más reciente autoriza una
+migración editorial.
+
+## 3. Blueprint de entrega
+
+Guardar el archivo junto al snapshot:
+
+```text
+.bacano/designs/<proyecto>/content-blueprint.json
+```
+
+Estructura recomendada:
+
+```json
+{
+  "schemaVersion": 1,
+  "project": "mi-storefront",
+  "source": "figma",
+  "routes": [
+    {
+      "route": "/",
+      "sections": [
+        {
+          "sectionKey": "home-hero",
+          "figmaNodeId": "1:20",
+          "component": "HomeHero",
+          "ownership": "content",
+          "contentTypeKey": "home_hero",
+          "entryKey": "home-main-hero",
+          "status": "missing",
+          "fields": [
+            {
+              "key": "title",
+              "type": "text",
+              "required": true,
+              "sampleValue": "Compra para cada etapa"
+            }
+          ],
+          "fixture": "fixtures/home-hero.json"
+        }
+      ]
+    }
+  ]
+}
+```
+
+El blueprint es una propuesta y una evidencia de coordinación, no una orden de
+escritura. No incluir IDs internos innecesarios, secretos, datos personales ni
+respuestas crudas de GraphQL. Mantener keys estables y registrar cambios que
+rompan el contrato.
+
+## 4. Fixtures temporales
+
+- Usar contenido real del diseño cuando esté disponible; evitar Lorem ipsum.
+- Guardarlos en un único directorio y cargarlos mediante un adaptador explícito.
+- Hacer que implementen el view model que consumen los componentes, no una
+  copia inventada de respuestas GraphQL ni de internals del SDK.
+- Mantener el mapper de Bacano separado: `Content` real y fixture deben terminar
+  en el mismo view model.
+- Incluir estados vacío, incompleto y contenido largo en pruebas separadas; no
+  convertirlos en el contenido principal de la página.
+- No crear fixtures para precios, stock, autenticación, carrito, checkout,
+  pedidos o atribución.
+
+Una forma válida de separación es:
+
+```text
+fixture ───────┐
+               ├─> PageContentViewModel ─> componentes
+Bacano mapper ─┘
+```
+
+El cambio de fuente debe ocurrir en el loader o repositorio de contenido, nunca
+mediante condicionales repartidos por los componentes.
+
+## 5. Entrega al equipo de Content
+
+Entregar una tabla legible con:
+
+- Ruta y sección visible.
+- Tipo y entry key sugeridos.
+- Campos, tipo, obligatoriedad y ejemplo tomado de Figma.
+- Assets desktop/mobile, proporción y uso esperado.
+- Estado y responsable.
+- Dependencias entre componentes, listas y entradas.
+
+El equipo de Content puede crear o ajustar la estructura desde Bacano. Si el
+usuario autoriza que el agente materialice el blueprint, usar exclusivamente
+`@bacano/sdk/content-management` y el token temporal generado desde **Conectar
+agente**. Confirmar la empresa, inventariar primero, crear componentes antes de
+sus consumidores y trabajar inicialmente en borrador. La skill no crea entradas,
+importaciones ni cargas de media.
+
+## 6. Cambio a Bacano real
+
+Antes de retirar el fixture:
+
+1. Confirmar que las keys reales coinciden con el blueprint.
+2. Validar campos requeridos, media y contenido largo.
+3. Comparar la página con Figma usando Content real.
+4. Verificar preview si la capacidad está activa.
+5. Eliminar el fixture del camino de ejecución, no necesariamente de los tests.
+
+En producción no se permite fallback silencioso a fixtures. Si una página
+depende de contenido temporal, reportar `❌ NO LISTO` con las rutas y secciones
+afectadas. Los fixtures pueden conservarse como datos de pruebas unitarias o
+visuales siempre que no entren en el bundle o loader de producción.
+
+## 7. Automatización administrativa
+
+La gestión de tipos pertenece al entrypoint separado
+`@bacano/sdk/content-management`, no al cliente público del storefront. Antes de
+escribir:
+
+1. Pedir al usuario que genere un acceso temporal de 15, 30 o 60 minutos.
+2. Guardarlo solo en el entorno local del proceso del agente.
+3. Ejecutar `getContext()`, `listTypes()` y `getReferences()`.
+4. Mostrar el plan y esperar aprobación cuando altere estructuras existentes.
+5. Crear primero componentes y luego tipos consumidores, siempre en borrador.
+6. Para archivar o eliminar, inspeccionar dependencias y confirmar nuevamente.
+
+Nunca exponer el token en el navegador, commit, blueprint, salida de consola o
+chat. Nunca convertir el blueprint en una importación implícita ni usar GraphQL
+directo. Las entradas y media permanecen bajo gestión editorial en Bacano.

package/skills/bacano-figma-web/references/extraction-contract.md

@@ -0,0 +1,102 @@
+# Contrato de extracción normalizado
+
+Cada fuente Figma debe producir el mismo checkpoint para que cambiar de MCP a
+Desktop o REST no obligue a rehacer la implementación.
+
+## Estructura sugerida
+
+```text
+.bacano/designs/<proyecto>/
+├── manifest.json
+├── tokens.json
+├── content-blueprint.json
+├── fixtures/
+├── assets/
+└── screenshots/
+```
+
+`content-blueprint.json` y `fixtures/` son necesarios únicamente cuando el
+diseño contiene información editorial que todavía no existe o no está lista en
+Bacano. Su contrato se define en
+[content-workflow.md](content-workflow.md). No crear fixtures para catálogo,
+precios, inventario, checkout, identidad ni otras fuentes funcionales del SDK.
+
+No modificar `.gitignore` automáticamente. Preguntar o seguir la política del
+proyecto antes de versionar imágenes o archivos grandes.
+
+Una política opcional, sin secretos, puede guardarse en
+`.bacano/designs/config.json`:
+
+```json
+{
+  "preferredSource": "figma-official",
+  "fallbackSources": [
+    "figma-desktop",
+    "desktop-bridge",
+    "rest-snapshot"
+  ],
+  "fallbackMode": "ask",
+  "reuseCachedExtraction": true
+}
+```
+
+`fallbackMode` debe ser `ask` por defecto. Usar `auto` únicamente cuando el
+usuario haya autorizado expresamente todas las fuentes declaradas.
+
+## Manifiesto mínimo
+
+```json
+{
+  "schemaVersion": 1,
+  "project": "mi-storefront",
+  "source": {
+    "adapter": "figma-official",
+    "fileKey": "opcional",
+    "fileVersion": "opcional",
+    "extractedAt": "2026-08-24T12:00:00.000Z"
+  },
+  "capabilities": {
+    "variables": "partial",
+    "components": "available",
+    "autoLayout": "available",
+    "responsiveFrames": "partial",
+    "interactions": "partial"
+  },
+  "pages": [
+    {
+      "route": "/",
+      "name": "Home",
+      "status": "extracted",
+      "desktop": { "nodeId": "1:2", "url": "https://figma.com/..." },
+      "mobile": { "nodeId": "1:3", "url": "https://figma.com/..." }
+    }
+  ],
+  "assumptions": []
+}
+```
+
+Valores de `adapter`:
+
+- `figma-official`: MCP remoto oficial.
+- `figma-desktop`: MCP local oficial.
+- `desktop-bridge`: bridge comunitario.
+- `rest-snapshot`: REST autorizado.
+
+Capacidades: `available`, `partial` o `missing`.
+Estado de página: `pending`, `extracted`, `implemented` o `validated`.
+
+Cada página requiere `route`, `name`, `status` y al menos un frame desktop o
+mobile con `nodeId` o `url`. No guardar secretos ni respuestas MCP completas.
+
+## Estrategia de consultas
+
+- Obtener metadata suficiente para construir el mapa de páginas.
+- Extraer cada frame principal una vez.
+- Solicitar subnodos solo si el contexto principal es incompleto.
+- Reutilizar tokens/assets comunes entre páginas.
+- Al reanudar, comparar `fileVersion` y repetir únicamente nodos cambiados.
+- Conservar las inferencias en `assumptions` para revisión humana.
+
+Para sitios medianos, una extracción organizada suele requerir decenas de
+lecturas, no una consulta por cada capa. La cifra exacta depende de la calidad y
+estructura del archivo, no únicamente del número de páginas.