@bacano/sdk 1.1.10 → 1.1.13

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

@@ -13,7 +13,9 @@ autenticación, marketing o Content por fuera de `@bacano/sdk`.
 
 Antes de extraer el diseño, identificar:
 
-- Web informativa o tienda virtual.
+- Web informativa, tienda virtual o sitio híbrido. Si permite una compra
+  completa, aplicar también los contratos de tienda a su superficie
+  transaccional.
 - 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.
@@ -74,11 +76,12 @@ pnpm exec bacano-figma-web validate-snapshot .bacano/designs/<proyecto>/manifest
 
 ## 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.
+Leer [references/bacano-mapping.md](references/bacano-mapping.md),
+[references/content-workflow.md](references/content-workflow.md) y
+[references/implementation-quality.md](references/implementation-quality.md).
+Preparar una matriz ruta → frame → componente → fuente de datos → Content →
+responsive → preview → estado, 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`.
@@ -93,9 +96,19 @@ 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. En esta versión la skill no crea ni
-modifica contenido en Bacano: esas acciones permanecen en el backoffice y
-requieren autorización independiente.
+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`. Crear o modificar tipos,
+componentes, grupos, listas y entradas únicamente mediante el acceso temporal
+y los scopes oficiales. Inventariar esos recursos antes de crear otros y
+preparar entradas en borrador por defecto; la media permanece en el
+backoffice y publicar requiere permiso y aprobación explícitos.
+
+Al proponer keys nuevas, resolver primero el idioma según
+`CONTENT_TYPE_MANAGEMENT.md`: instrucción explícita, convención existente y
+después idioma principal del website. No traducir ni renombrar contratos ya
+utilizados por el storefront.
 
 Antes de modificar código, indicar brevemente qué rutas y componentes se
 implementarán y qué decisiones de diseño son inferidas.
@@ -110,6 +123,10 @@ Trabajar por página o conjunto pequeño de secciones:
 4. Integración Bacano real.
 5. Comparación visual y correcciones.
 
+No dar una página por validada únicamente porque compila. Comparar estructura,
+contenido, responsive e interacciones del corte antes de continuar y registrar
+lo pendiente cuando la revisión visual quede a cargo del usuario.
+
 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.

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

@@ -7,9 +7,9 @@ negocio.
 
 Antes de programar, registrar por ruta:
 
-| Ruta | Frame | Componente | Fuente | Responsive | Estado |
-| --- | --- | --- | --- | --- | --- |
-| `/` | Home desktop/mobile | `Hero` | Content | 2 frames | pendiente |
+| Ruta | Frame | Componente | Fuente | Content | Responsive | Preview | Estado |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `/` | Home desktop/mobile | `Hero` | Content | `hero_inicio` | 2 frames | activa | pendiente |
 
 Fuentes posibles: Content, catálogo estático, live state, public config,
 checkout, auth u otra operación documentada del SDK.

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

@@ -19,12 +19,30 @@ Antes de crear campos o fixtures, asignar cada valor a una fuente:
 No duplicar en Content información que ya tiene una fuente funcional. Un valor
 visible en Figma no implica que sea editorial.
 
+## Modelar sin extremos
+
+No convertir una página extensa en un único tipo gigante ni crear un componente
+para cada bloque visual. Separar una sección cuando tenga ciclo editorial,
+responsable, reutilización o repetición propios. Crear un componente compartido
+solo cuando coincidan tanto la estructura como el significado y la abstracción
+reduzca duplicación real.
+
+- Usar grupos para organizar entradas relacionadas por dominio o página.
+- Usar repetibles para pasos, integrantes, preguntas, tarjetas y otras
+  colecciones homogéneas.
+- Mantener directamente en el tipo los campos de un bloque exclusivo y simple.
+- Crear primero listas y componentes realmente compartidos; después los tipos
+  consumidores.
+- No hacer depender la UI del shape crudo de Content: fixture y mapper real
+  deben converger en el mismo view model.
+
 ## 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`.
+2. Resolver el idioma y proponer tipos, keys, campos y entradas en
+   `content-blueprint.json` siguiendo `CONTENT_TYPE_MANAGEMENT.md`.
 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.
@@ -66,22 +84,22 @@ Estructura recomendada:
       "route": "/",
       "sections": [
         {
-          "sectionKey": "home-hero",
+          "sectionKey": "hero-inicio",
           "figmaNodeId": "1:20",
           "component": "HomeHero",
           "ownership": "content",
-          "contentTypeKey": "home_hero",
-          "entryKey": "home-main-hero",
+          "contentTypeKey": "hero_inicio",
+          "entryKey": "hero-principal-inicio",
           "status": "missing",
           "fields": [
             {
-              "key": "title",
+              "key": "titulo",
               "type": "text",
               "required": true,
               "sampleValue": "Compra para cada etapa"
             }
           ],
-          "fixture": "fixtures/home-hero.json"
+          "fixture": "fixtures/hero-inicio.json"
         }
       ]
     }
@@ -92,7 +110,9 @@ Estructura recomendada:
 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.
+rompan el contrato. Las propiedades técnicas del formato del blueprint
+permanecen en inglés; los valores que representan tipos, componentes, campos y
+entradas definidos por la empresa siguen el idioma resuelto para el proyecto.
 
 ## 4. Fixtures temporales
 
@@ -129,10 +149,13 @@ Entregar una tabla legible con:
 - Estado y responsable.
 - Dependencias entre componentes, listas y entradas.
 
-El equipo de Content crea o ajusta la estructura desde Bacano. En esta versión
-la skill no ejecuta escrituras, importaciones ni cargas de media en Bacano. Si
-la creación real es necesaria para continuar, solicitar confirmación al usuario
-en vez de simular que ocurrió.
+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 y los scopes, inventariar primero, crear
+componentes antes de sus consumidores y trabajar inicialmente en borrador. La
+skill puede preparar entradas cuando el usuario conceda
+`content_entries:manage`; no carga media ni publica sin el scope específico.
 
 ## 6. Cambio a Bacano real
 
@@ -149,10 +172,31 @@ 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 futura
-
-La creación automática debe pertenecer a una herramienta administrativa
-separada del SDK público del storefront. Requiere autenticación con alcance por
-empresa/website, previsualización de cambios, idempotencia, auditoría y
-confirmación antes de escribir. Nunca exponer esas credenciales en el navegador
-ni convertir el blueprint en una importación implícita.
+## 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()`, comprobar sus `scopes`, y después `listTypes()`,
+   `listGroups()`, `listOptionLists()` y `getReferences()`.
+4. Mostrar el plan y esperar aprobación cuando altere estructuras existentes.
+5. Crear primero listas y componentes, luego tipos consumidores, y mantener las
+   estructuras nuevas en borrador hasta validarlas.
+6. Si se concedió `content_entries:manage`, inventariar entradas por tipo, key y
+   locale; crear las faltantes en borrador y actualizar únicamente con
+   `expectedUpdatedAt`.
+7. No fusionar por nombres, no usar HTML crudo y no relacionar URLs remotas. La
+   media debe existir en Bacano y pertenecer a la empresa autorizada.
+8. Para archivar o eliminar tipos, entradas, grupos o listas, inspeccionar
+   dependencias y confirmar nuevamente. Una actualización de lista debe enviar
+   todos los elementos que deben permanecer, incluidos sus IDs existentes.
+9. Publicar o modificar una entrada publicada solo con
+   `content_entries:publish` y una aprobación humana explícita.
+
+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. La carga de media permanece bajo gestión editorial en Bacano hasta que
+exista el scope y endpoint administrativo oficial.

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

@@ -87,6 +87,9 @@ 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.
+Antes de implementar, comprobar que las rutas no apuntan accidentalmente al
+mismo frame o `nodeId`. Una reutilización intencional debe quedar registrada en
+`assumptions`.
 
 ## Estrategia de consultas
 

package/skills/bacano-figma-web/references/implementation-quality.md

@@ -0,0 +1,67 @@
+# Calidad de implementación desde Figma
+
+Aplicar estas reglas al construir la interfaz. Son criterios de resultado, no
+una obligación de usar una librería concreta.
+
+## Responsive e inferencias
+
+Si Figma no incluye un frame móvil, construir una adaptación mobile first y
+registrarla como inferencia. Conservar jerarquía, contenido, orden semántico y
+acciones principales; apilar columnas cuando corresponda y evitar overflow
+horizontal. Verificar al menos móvil, tablet y escritorio.
+
+No convertir automáticamente toda colección en carrusel. Usarlo únicamente
+cuando mejore la exploración y asegurar scroll táctil, teclado, controles
+accesibles, dimensiones estables y pausa durante la interacción. Respetar
+`prefers-reduced-motion` cuando exista autoplay o movimiento.
+
+## Componentes e interacción
+
+Inspeccionar dependencias y componentes del proyecto antes de añadir paquetes.
+No imponer HeroUI, Embla, Motion, CSS Modules u otra librería; reutilizar el
+sistema existente y pedir autorización antes de introducir una dependencia
+visual relevante.
+
+Todo control interactivo necesita estado de hover cuando aplique,
+`focus-visible`, teclado, contraste y área táctil suficiente. Usar
+`aria-current="page"` en la navegación activa y no comunicar estados solo con
+color. Las animaciones no deben cambiar el layout final, dejar contenido útil
+oculto sin JavaScript ni ejecutarse contra la preferencia de movimiento
+reducido.
+
+## Perfil de exportación estática
+
+Cuando el hosting y el proyecto estén definidos como export estático, comprobar
+la configuración efectiva del framework. En Next.js suele incluir
+`output: "export"`, `trailingSlash: true` y una estrategia de imágenes
+compatible con exportación estática.
+
+Materializar durante el build contenido, rutas, metadata, sitemap y JSON-LD.
+Las rutas dinámicas editoriales deben enumerar todas las entradas publicadas y
+fallar de forma explícita si el snapshot esperado está vacío o incompleto.
+
+No introducir Route Handlers, API Routes, Server Actions, middleware, ISR,
+`force-dynamic` ni secretos de servidor en un proyecto que debe producir solo
+archivos estáticos. Esta prohibición no aplica automáticamente a un storefront
+híbrido o SSR: primero clasificar su arquitectura.
+
+Mantener un único bootstrap de configuración pública y un cliente Bacano por
+worker o árbol. Reutilizar esa misma información para páginas, metadata,
+sitemap, JSON-LD y provider; no consultar cada ruta por separado si existe un
+snapshot oficial compartido.
+
+## Preview y rutas editoriales
+
+Mantener una allowlist finita de patrones editoriales. Los índices pueden ser
+explícitos y los slugs de detalle pueden derivarse de las entradas publicadas;
+no aceptar una ruta arbitraria solo porque coincide con una cadena. Preview
+reutiliza componentes y mappers de producción, permanece fuera del sitemap y
+no habilita funciones transaccionales o marketing.
+
+## Diagnóstico antes de cambiar código
+
+Un `ORIGIN_NOT_ALLOWED` o un `403` al resolver la configuración durante el
+build suele indicar que el origen utilizado no está autorizado para el website.
+Verificar dominio canónico, orígenes permitidos y ambiente antes de alterar el
+cliente SDK. Una advertencia aislada sobre ausencia de caché del build no prueba
+por sí sola que el storefront esté defectuoso.

package/skills/bacano-figma-web/references/visual-validation.md

@@ -2,6 +2,10 @@
 
 Validar por cortes para evitar corregir 70 secciones al final.
 
+Para cada corte, distinguir `implementado`, `validado`, `pendiente de revisión
+humana`, `no aplica` y `bloqueado`. Si el usuario conserva la validación visual,
+no convertir su ausencia en una aprobación automática.
+
 ## Evidencia mínima por página
 
 - URL/ruta implementada.