@bacano/sdk 1.1.12 → 1.1.13

package/CONTENT_TYPE_MANAGEMENT.md

@@ -1,9 +1,10 @@
-# Gestión de tipos de Content para agentes
+# Gestión segura de Content para agentes
 
 `@bacano/sdk/content-management` permite que una herramienta administrativa o
-un agente autorizado consulte, cree y mantenga **tipos y componentes** de
-Bacano Content. No permite administrar entradas, productos, ventas, clientes ni
-ningún otro dato de la empresa.
+un agente autorizado consulte y mantenga **tipos, componentes, grupos, listas
+de opciones y entradas** de Bacano Content. Cada capacidad requiere un permiso explícito. El acceso no
+autoriza productos, ventas, clientes, configuración general, GraphQL, SQL ni
+Storage.
 
 Este contrato es independiente del cliente público del storefront. Debe usarse
 solo desde un proceso local o servidor confiable; nunca desde el navegador ni
@@ -13,17 +14,34 @@ dentro del bundle del sitio web.
 
 1. En Bacano, abre **Sitios web → Contenido → Tipos** o **Componentes**.
 2. Selecciona **Conectar agente**.
-3. Elige 15, 30 o 60 minutos y genera el acceso.
+3. Elige el alcance, 15, 30 o 60 minutos y genera el acceso.
 4. Copia el token al entorno local del agente.
 
-El token está firmado, pertenece a una sola empresa y solo contiene el alcance
-`content_types:manage`. Cada petición vuelve a comprobar que el usuario que lo
-generó continúa vinculado a la empresa y conserva `websites.manage`. Al vencer
-o perder ese permiso deja de funcionar.
+El token está firmado con un secreto exclusivo, pertenece a una sola empresa y
+usuario y está respaldado por una concesión revocable. Cada petición comprueba
+la firma, vigencia, concesión, scopes exactos y que el usuario continúa
+vinculado a la empresa con `websites.manage`. Al vencer, revocarse o perder ese
+permiso deja de funcionar.
+
+Scopes disponibles:
+
+- `content_types:manage`: tipos, componentes, listas de opciones, referencias y
+  sus ciclos de vida.
+- `content_entries:manage`: grupos, entradas en borrador y sus ciclos de vida.
+- `content_entries:publish`: publicar y modificar contenido publicado; requiere
+  también `content_entries:manage`.
+- `content_media:upload`: reservado para una fase posterior; no se concede
+  mientras la carga administrativa de media no esté implementada.
 
 No guardes el token en Git, Figma, Content, logs, variables públicas ni archivos
 que se empaqueten con el storefront.
 
+Para desplegar Bacano, la API requiere
+`CONTENT_MANAGEMENT_TOKEN_SECRET`: un secreto aleatorio de al menos 32
+caracteres, exclusivo de esta capacidad y distinto de `API_SECRET`, JWT y los
+secretos de Hasura. Debe configurarse como secreto del entorno; nunca se entrega
+al agente. Rotarlo invalida inmediatamente todos los accesos temporales activos.
+
 ## Crear el cliente
 
 ```ts
@@ -35,7 +53,7 @@ const content = createContentManagementClient({
 });
 
 const context = await content.getContext();
-console.log(context.companyId, context.expiresAt);
+console.log(context.companyId, context.scopes, context.expiresAt);
 ```
 
 El cliente ofrece:
@@ -47,6 +65,75 @@ El cliente ofrece:
 - `createType(input)` y `updateType(idOrKey, input)`.
 - `inspectLifecycle(idOrKey, operation)`.
 - `applyLifecycle(idOrKey, operation)`.
+- `listEntries(filters)`, `getEntry(idOrKey, locale?)`.
+- `createEntry(input)` y `updateEntry(idOrKey, input)`.
+- `inspectEntryLifecycle(idOrKey, operation)`.
+- `applyEntryLifecycle(idOrKey, operation)`.
+- `listGroups()`, `getGroup(idOrKey)`, `createGroup(input)` y
+  `updateGroup(idOrKey, input)`.
+- `inspectGroupLifecycle(idOrKey, operation)` y
+  `applyGroupLifecycle(idOrKey, operation)`.
+- `listOptionLists()`, `getOptionList(idOrKey)`, `createOptionList(input)` y
+  `updateOptionList(idOrKey, input)`.
+- `inspectOptionListLifecycle(idOrKey, operation)` y
+  `applyOptionListLifecycle(idOrKey, operation)`.
+
+## Idioma, nombres y keys
+
+Antes de proponer una estructura, resolver su idioma en este orden:
+
+1. El idioma solicitado expresamente por el usuario.
+2. La convención predominante del proyecto existente.
+3. El idioma principal del website.
+4. Si todavía existe una ambigüedad material, preguntar al usuario.
+
+Para un website en español, los nombres visibles y las keys nuevas se crean en
+español salvo instrucción contraria. Esta regla aplica a identificadores
+definidos por la empresa; los valores reservados del SDK como `entry`,
+`component`, `draft`, `website_content`, `text` o `repeater` no se traducen ni
+se reemplazan por valores inventados.
+
+Usar estas convenciones:
+
+| Elemento | Convención | Ejemplo |
+| --- | --- | --- |
+| Nombre visible | Lenguaje natural, con tildes | `Preguntas frecuentes` |
+| Key de tipo, componente, sección o campo | `snake_case`, sin tildes | `preguntas_frecuentes` |
+| Key o slug público de una entrada | `kebab-case`, sin tildes | `preguntas-frecuentes-inicio` |
+
+Las keys deben describir el significado del contenido, no detalles accidentales
+de su implementación visual. Preferir `titulo`, `descripcion`,
+`imagen_principal`, `enlace_contacto`, `preguntas`, `planes` o `pasos`. Evitar
+identificadores opacos como `data`, `content`, `items`, `field1`,
+`step1_title` o `component_2` cuando existe un nombre semántico claro.
+
+Para elementos repetidos, modelar un repetible y, cuando corresponda, un
+componente semántico. Por ejemplo, usar `pasos` con un componente `paso` que
+contenga `titulo` y `descripcion`, en vez de crear `paso1_titulo`,
+`paso1_descripcion`, `paso2_titulo` y campos sucesivos.
+
+Antes de crear algo nuevo:
+
+1. Consultar `listTypes()` y `getReferences()`.
+2. Reutilizar una estructura solo cuando conserva el mismo significado y la
+   misma forma, no únicamente porque algunos campos coinciden.
+3. Dar un nombre neutral a una estructura reutilizable, por ejemplo
+   `seccion_preguntas_frecuentes`.
+4. Incluir el contexto en el nombre cuando la estructura sea realmente
+   exclusiva, por ejemplo `calculadora_eficiencia_inicio`.
+5. Evitar nombres demasiado genéricos como `contenido` y nombres que quedarían
+   engañosos al reutilizarse, como `contenedor_principal_servicios` para una
+   página de blog.
+
+Una key activa es un contrato con el storefront. Nunca traducir, regenerar ni
+renombrar automáticamente keys existentes. La convención de idioma aplica a
+estructuras nuevas; cambiar una key utilizada requiere tratarlo como una
+migración explícita y presentar su impacto. Tampoco crear sufijos como `_2` o
+`-2` sin investigar primero el identificador existente.
+
+Antes de ejecutar `createType()`, presentar al usuario el nombre, key, idioma,
+uso, campos, componentes y decisión de creación o reutilización. Corregir
+mezclas de idiomas y errores ortográficos antes de materializar el blueprint.
 
 ## Flujo seguro para un agente
 
@@ -71,13 +158,13 @@ como una eliminación estructural y puede requerir
 
 ```ts
 await content.createType({
-  key: "cta_button",
+  key: "boton_llamada_accion",
   name: "Botón de llamada a la acción",
   kind: "component",
   status: "draft",
   fields: [
     {
-      key: "label",
+      key: "texto",
       label: "Texto",
       type: "text",
       required: true,
@@ -85,7 +172,7 @@ await content.createType({
       settings: { isVisible: true, maxLength: 80 },
     },
     {
-      key: "url",
+      key: "enlace",
       label: "Enlace",
       type: "link",
       required: true,
@@ -96,38 +183,38 @@ await content.createType({
 });
 
 await content.createType({
-  key: "home_hero",
+  key: "hero_inicio",
   name: "Hero del inicio",
   kind: "entry",
   status: "draft",
   usages: ["website_content"],
-  sections: [{ key: "content", title: "Contenido", sortOrder: 1 }],
+  sections: [{ key: "contenido", title: "Contenido", sortOrder: 1 }],
   fields: [
     {
-      key: "title",
+      key: "titulo",
       label: "Título",
       type: "text",
       required: true,
       sortOrder: 1,
-      sectionKey: "content",
+      sectionKey: "contenido",
       settings: { isVisible: true, maxLength: 120 },
     },
     {
-      key: "actions",
+      key: "acciones",
       label: "Acciones",
       type: "repeater",
       required: false,
       sortOrder: 2,
-      sectionKey: "content",
+      sectionKey: "contenido",
       settings: { isVisible: true, minRows: 0, maxRows: 3 },
       children: [
         {
-          key: "button",
+          key: "boton",
           label: "Botón",
           type: "component",
           required: true,
           sortOrder: 1,
-          componentKey: "cta_button",
+          componentKey: "boton_llamada_accion",
           settings: { isVisible: true },
         },
       ],
@@ -166,10 +253,10 @@ otros usos editoriales son `website_content` y `product_additional`.
 ## Ciclo de vida
 
 ```ts
-const preview = await content.inspectLifecycle("home_hero", "delete");
+const preview = await content.inspectLifecycle("hero_inicio", "delete");
 
 if (preview.allowed && userConfirmed) {
-  await content.applyLifecycle("home_hero", "delete");
+  await content.applyLifecycle("hero_inicio", "delete");
 }
 ```
 
@@ -178,15 +265,137 @@ eliminar cuando existe contenido histórico. El backend aplica las mismas reglas
 de dependencias, keys, componentes, secciones y cambios destructivos que el
 backoffice; el SDK no crea un camino alterno.
 
+## Entradas
+
+Antes de crear una entrada, confirma que su tipo existe y que la estructura
+aprobada ya está activa. Las entradas nacen en `draft` salvo que el usuario haya
+concedido explícitamente `content_entries:publish`.
+
+```ts
+const existing = await content.listEntries({
+  contentType: "hero_inicio",
+  locale: "es-CO",
+  limit: 100,
+});
+
+const current = existing.entries.find(
+  (entry) => entry.key === "hero-principal-inicio",
+);
+
+if (!current) {
+  await content.createEntry({
+    contentType: "hero_inicio",
+    key: "hero-principal-inicio",
+    name: "Hero principal del inicio",
+    locale: "es-CO",
+    status: "draft",
+    content: {
+      titulo: "Encuentra lo mejor para cada etapa",
+      descripcion: "Compra productos seleccionados para tu familia.",
+    },
+  });
+} else {
+  await content.updateEntry(current.id, {
+    contentType: current.contentType.id,
+    key: current.key,
+    name: current.name,
+    locale: current.locale,
+    status: "draft",
+    content: {
+      ...current.content,
+      titulo: "Encuentra lo mejor para cada etapa",
+    },
+    expectedUpdatedAt: current.updatedAt,
+  });
+}
+```
+
+Reglas obligatorias:
+
+1. Inventariar por tipo, key y locale antes de crear; nunca fusionar por nombre.
+2. Usar `expectedUpdatedAt` al actualizar. Un conflicto exige volver a consultar
+   y presentar el cambio; no se sobrescribe silenciosamente.
+3. Enviar el documento completo que debe permanecer. `updateEntry()` reemplaza
+   el contenido de la entrada después de aplicar las validaciones oficiales.
+4. Reutilizar únicamente `fileId` ya existentes y pertenecientes a la misma
+   empresa. Este acceso no sube media ni acepta URLs arbitrarias.
+5. Rich text usa el JSON controlado por Bacano, nunca HTML crudo.
+6. Publicar, retirar o modificar una entrada publicada requiere
+   `content_entries:publish` y aprobación humana explícita.
+7. Inspeccionar el ciclo de vida antes de archivar, restaurar o eliminar.
+
+La API reutiliza el mismo servicio de guardado del backoffice: campos
+obligatorios, componentes anidados, repetibles, listas, referencias, rich text,
+media y pertenencia a la empresa se validan de forma autoritativa.
+
+## Grupos y listas de opciones
+
+Los grupos organizan entradas y usan el scope `content_entries:manage`. Las
+listas proporcionan valores controlados para campos `select`, usan
+`content_types:manage` y conservan sus relaciones padre-hijo.
+
+```ts
+const group = await content.createGroup({
+  key: "pagina-principal",
+  name: "Página principal",
+  status: "active",
+});
+
+const materials = await content.createOptionList({
+  key: "materiales",
+  name: "Materiales",
+  status: "draft",
+  isExtensible: false,
+  items: [
+    { value: "algodon", label: "Algodón", sortOrder: 1 },
+    { value: "lino", label: "Lino", sortOrder: 2 },
+  ],
+});
+
+await content.updateOptionList(materials.id, {
+  key: materials.key,
+  name: materials.name,
+  status: "active",
+  isExtensible: materials.isExtensible,
+  items: materials.items.map((item) => ({
+    id: item.id,
+    value: item.value,
+    label: item.label,
+    parentItemId: item.parentItemId,
+    sortOrder: item.sortOrder,
+    isActive: item.isActive,
+    metadata: item.metadata,
+  })),
+});
+```
+
+`updateGroup()` y `updateOptionList()` reciben el documento completo que debe
+permanecer. Las keys existentes son inmutables. Para retirar elementos,
+archivar, restaurar o eliminar, primero usa la operación `inspect*Lifecycle()`.
+El backend bloquea desactivar o retirar opciones que todavía usan listas
+dependientes y exige `confirmDestructiveChanges` cuando corresponde; nunca
+omitas opciones existentes por accidente en una actualización.
+
+## Seguridad y auditoría
+
+- El `companyId` y el usuario provienen del token; no se aceptan desde el body.
+- Cada consulta y mutación está filtrada por la empresa firmada.
+- UUIDs o keys de otra empresa responden como inexistentes y no se modifican.
+- Las concesiones pueden revocarse individualmente desde Bacano.
+- Emisión, revocación y mutaciones quedan en una auditoría inmutable sin guardar
+  el bearer token ni el documento completo.
+- Las respuestas del endpoint usan `no-store`, límites de tamaño y rate limit.
+- Los tokens v2 no son compatibles con tokens anteriores y tienen como máximo
+  60 minutos de vigencia.
+
 ## Límites de esta versión
 
-- No crea ni modifica entradas de Content.
-- No carga archivos ni media.
-- No crea listas de opciones.
+- No carga archivos ni crea media; puede relacionar media existente validada.
 - No funciona desde el cliente público del storefront.
 - No acepta GraphQL directo ni credenciales administrativas permanentes.
+- No previsualiza borradores desde el storefront público.
 
 El resultado esperado del flujo Figma es: el agente propone el blueprint, el
-usuario habilita el acceso temporal, el agente crea o ajusta los tipos y
-componentes aprobados, y el equipo editorial completa las entradas desde
-Bacano.
+usuario habilita únicamente los scopes necesarios, el agente crea o ajusta la
+estructura y prepara entradas en borrador, y una persona revisa antes de
+publicar.

package/README.md

@@ -21,20 +21,23 @@ React hooks are available from `@bacano/sdk/react` and require `react >= 18`
 as a peer dependency. The core client has no runtime dependencies and works
 without React.
 
-### Gestión de tipos de Content para agentes
+### Gestión de Bacano Content para agentes
 
-Un agente autorizado puede consultar, crear y mantener tipos y componentes con
-el entrypoint administrativo `@bacano/sdk/content-management`. El acceso se
-genera temporalmente desde Bacano, está limitado a una empresa y nunca debe
-incluirse en el storefront:
+Un agente autorizado puede consultar y mantener tipos, componentes, grupos,
+listas de opciones y entradas con el entrypoint administrativo
+`@bacano/sdk/content-management`. Cada capacidad exige un scope explícito. El
+acceso se genera temporalmente desde Bacano, está limitado a una empresa y
+nunca debe incluirse en el storefront:
 
 ```ts
 import { createContentManagementClient } from "@bacano/sdk/content-management";
 ```
 
 Lee [`CONTENT_TYPE_MANAGEMENT.md`](./CONTENT_TYPE_MANAGEMENT.md) antes de usarlo.
-La guía contiene el flujo de autorización, contratos de campos, referencias,
-cambios destructivos y límites de seguridad.
+La guía contiene el flujo de autorización, contratos de campos y entradas,
+estados, referencias, cambios destructivos y límites de seguridad. La carga de
+media continúa en el backoffice hasta que exista un contrato administrativo
+oficial para ella.
 
 ### Auditoría del storefront
 
@@ -62,8 +65,8 @@ el usuario o agente invoca la skill.
 ### Implementación desde Figma
 
 El SDK también incluye `bacano-figma-web`, la skill oficial para convertir un
-diseño Figma en una web informativa o tienda que conserve el cascarón, Static
-First y contratos públicos de Bacano:
+diseño Figma en una web informativa, tienda o sitio híbrido que conserve el
+cascarón, Static First y contratos públicos de Bacano:
 
 ```bash
 pnpm exec bacano-figma-web install --agent all
@@ -82,10 +85,11 @@ la presencia del token REST. El OAuth del MCP remoto debe confirmarse dentro del
 agente con las herramientas de Figma. La extracción se conserva como snapshot
 normalizado. Cuando el equipo de Content y desarrollo trabajan en tiempos
 distintos, la skill genera un blueprint de entrega y permite fixtures locales
-con el mismo contrato de los componentes. Las entradas reales continúan
-creándose desde Bacano. Con autorización temporal, la skill puede crear o
-ajustar tipos y componentes mediante el entrypoint administrativo oficial; un
-fixture activo bloquea la aprobación de producción.
+con el mismo contrato de los componentes. Con autorización temporal y scopes
+explícitos, puede crear o ajustar tipos, componentes, grupos, listas y entradas
+mediante el entrypoint administrativo oficial. Las entradas nacen en borrador;
+publicar exige permiso y aprobación humana. Un fixture activo en producción
+bloquea la aprobación del sitio.
 
 El snapshot puede validarse con:
 

package/content-management-types.d.ts

@@ -0,0 +1,260 @@
+export type ContentManagementTypeKind = "entry" | "component";
+export type ContentManagementTypeStatus = "draft" | "active" | "archived";
+export type ContentManagementTypeUsage = "website_content" | "product_additional" | "product_specification";
+export type ContentManagementScope = "content_types:manage" | "content_entries:manage" | "content_media:upload" | "content_entries:publish";
+export type ContentManagementFieldType = "boolean" | "component" | "date" | "link" | "measure" | "media" | "number" | "reference" | "repeater" | "rich_text" | "rich_text_full" | "select" | "slug" | "text" | "textarea";
+export interface ContentManagementChildFieldInput {
+    id?: string | null;
+    key: string;
+    label: string;
+    type: ContentManagementFieldType;
+    required?: boolean;
+    sortOrder: number;
+    settings?: Record<string, unknown>;
+    componentKey?: string | null;
+}
+export interface ContentManagementFieldInput extends ContentManagementChildFieldInput {
+    sectionKey?: string | null;
+    children?: ContentManagementChildFieldInput[];
+}
+export interface ContentManagementTypeInput {
+    key: string;
+    name: string;
+    description?: string;
+    kind: ContentManagementTypeKind;
+    status?: "draft" | "active";
+    settings?: Record<string, unknown>;
+    usages?: ContentManagementTypeUsage[];
+    sections?: Array<{
+        key: string;
+        title: string;
+        description?: string;
+        sortOrder: number;
+    }>;
+    specificationScopes?: Array<{
+        category?: string | null;
+        subcategoryId?: string | null;
+    }>;
+    deletedPaths?: string[];
+    confirmDestructiveChanges?: boolean;
+    fields?: ContentManagementFieldInput[];
+}
+export interface ContentManagementType extends Omit<ContentManagementTypeInput, "status"> {
+    id: string;
+    companyId: string;
+    description: string;
+    status: ContentManagementTypeStatus;
+    settings: Record<string, unknown>;
+    usages: ContentManagementTypeUsage[];
+    sections: Array<{
+        id: string;
+        key: string;
+        title: string;
+        description: string;
+        sortOrder: number;
+    }>;
+    specificationScopes: Array<{
+        id: string;
+        category: string | null;
+        subcategoryId: string | null;
+    }>;
+    fields: ContentManagementFieldInput[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ContentManagementContext {
+    companyId: string;
+    /** @deprecated Use scopes to inspect the complete grant. */
+    scope: "content_types:manage";
+    scopes: ContentManagementScope[];
+    expiresAt: string;
+}
+export type ContentManagementEntryStatus = "draft" | "published" | "archived";
+export interface ContentManagementEntryInput {
+    contentType: string;
+    key: string;
+    name: string;
+    locale?: string;
+    categoryKey?: string;
+    categoryName?: string;
+    status?: Exclude<ContentManagementEntryStatus, "archived">;
+    tagIds?: string[];
+    content?: Record<string, unknown>;
+    expectedUpdatedAt?: string;
+}
+export interface ContentManagementEntry {
+    id: string;
+    companyId: string;
+    contentType: {
+        id: string;
+        key: string;
+        name: string;
+    };
+    key: string;
+    name: string;
+    locale: string;
+    categoryKey: string;
+    status: ContentManagementEntryStatus;
+    tagIds: string[];
+    tags: string[];
+    content: Record<string, unknown>;
+    publishedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ContentManagementEntryListInput {
+    contentType?: string;
+    locale?: string;
+    status?: ContentManagementEntryStatus;
+    limit?: number;
+    offset?: number;
+}
+export interface ContentManagementEntryList {
+    entries: ContentManagementEntry[];
+    total: number;
+}
+export interface ContentManagementReferences {
+    categories: Array<{
+        code: string;
+        name: string;
+        subcategories: Array<{
+            id: string;
+            name: string;
+        }>;
+    }>;
+    optionLists: Array<{
+        key: string;
+        name: string;
+        isExtensible: boolean;
+        options: Array<{
+            value: string;
+            label: string;
+        }>;
+    }>;
+    measureDimensions: Array<{
+        code: string;
+        name: string;
+        canonicalUnitCode: string;
+        units: Array<{
+            code: string;
+            name: string;
+            symbol: string;
+        }>;
+    }>;
+}
+export type ContentManagementGroupStatus = "active" | "inactive";
+export interface ContentManagementGroupInput {
+    key: string;
+    name: string;
+    description?: string;
+    sortOrder?: number;
+    status?: ContentManagementGroupStatus;
+}
+export interface ContentManagementGroup {
+    id: string;
+    companyId: string;
+    key: string;
+    name: string;
+    description: string;
+    sortOrder: number;
+    status: ContentManagementGroupStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+export type ContentManagementOptionListStatus = "draft" | "active" | "archived";
+export interface ContentManagementOptionListItemInput {
+    id?: string | null;
+    value: string;
+    label: string;
+    parentItemId?: string | null;
+    sortOrder: number;
+    isActive?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface ContentManagementOptionListInput {
+    key: string;
+    name: string;
+    description?: string;
+    status?: Exclude<ContentManagementOptionListStatus, "archived">;
+    parentListId?: string | null;
+    isExtensible?: boolean;
+    confirmDestructiveChanges?: boolean;
+    items?: ContentManagementOptionListItemInput[];
+}
+export interface ContentManagementOptionListItem {
+    id: string;
+    value: string;
+    label: string;
+    parentItemId: string | null;
+    sortOrder: number;
+    isActive: boolean;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ContentManagementOptionList {
+    id: string;
+    companyId: string;
+    key: string;
+    name: string;
+    description: string;
+    status: ContentManagementOptionListStatus;
+    parentListId: string | null;
+    isExtensible: boolean;
+    items: ContentManagementOptionListItem[];
+    createdAt: string;
+    updatedAt: string;
+}
+export type ContentManagementLifecycleOperation = "archive" | "restore" | "delete";
+export interface ContentManagementLifecycleResult {
+    success: boolean;
+    allowed: boolean;
+    applied: boolean;
+    entity_id: string | null;
+    entity_type: "type" | "component" | "entry" | "group" | "option_list" | null;
+    operation: ContentManagementLifecycleOperation | null;
+    name: string | null;
+    status: string | null;
+    dependencies: Array<{
+        code: string;
+        label: string;
+        count: number;
+        blocking: boolean;
+    }>;
+    message: string | null;
+    errors: string[];
+}
+export type ContentManagementAccessTokenProvider = () => string | Promise<string>;
+export interface ContentManagementClientConfig {
+    apiUrl: string;
+    accessToken: string | ContentManagementAccessTokenProvider;
+    fetch?: typeof fetch;
+}
+export interface ContentManagementClient {
+    getContext(): Promise<ContentManagementContext>;
+    getReferences(): Promise<ContentManagementReferences>;
+    listTypes(): Promise<ContentManagementType[]>;
+    getType(identifier: string): Promise<ContentManagementType>;
+    createType(input: ContentManagementTypeInput): Promise<ContentManagementType>;
+    updateType(identifier: string, input: ContentManagementTypeInput): Promise<ContentManagementType>;
+    inspectLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+    applyLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+    listEntries(input?: ContentManagementEntryListInput): Promise<ContentManagementEntryList>;
+    getEntry(identifier: string, locale?: string): Promise<ContentManagementEntry>;
+    createEntry(input: ContentManagementEntryInput): Promise<ContentManagementEntry>;
+    updateEntry(identifier: string, input: ContentManagementEntryInput): Promise<ContentManagementEntry>;
+    inspectEntryLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+    applyEntryLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+    listGroups(): Promise<ContentManagementGroup[]>;
+    getGroup(identifier: string): Promise<ContentManagementGroup>;
+    createGroup(input: ContentManagementGroupInput): Promise<ContentManagementGroup>;
+    updateGroup(identifier: string, input: ContentManagementGroupInput): Promise<ContentManagementGroup>;
+    inspectGroupLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+    applyGroupLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+    listOptionLists(): Promise<ContentManagementOptionList[]>;
+    getOptionList(identifier: string): Promise<ContentManagementOptionList>;
+    createOptionList(input: ContentManagementOptionListInput): Promise<ContentManagementOptionList>;
+    updateOptionList(identifier: string, input: ContentManagementOptionListInput): Promise<ContentManagementOptionList>;
+    inspectOptionListLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+    applyOptionListLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+}

package/content-management.cjs

@@ -58,6 +58,16 @@ function encodeIdentifier(identifier) {
   }
   return encodeURIComponent(normalized);
 }
+function entryListPath(input = {}) {
+  const search = new URLSearchParams();
+  if (input.contentType) search.set("contentType", input.contentType);
+  if (input.locale) search.set("locale", input.locale);
+  if (input.status) search.set("status", input.status);
+  if (input.limit !== void 0) search.set("limit", String(input.limit));
+  if (input.offset !== void 0) search.set("offset", String(input.offset));
+  const query = search.toString();
+  return query ? `/entries?${query}` : "/entries";
+}
 function createContentManagementClient(config) {
   const apiUrl = normalizeApiUrl(config.apiUrl);
   const fetchImplementation = config.fetch ?? globalThis.fetch;
@@ -109,8 +119,8 @@ function createContentManagementClient(config) {
     }
     return payload.data;
   };
-  const lifecycle = (identifier, operation, dryRun) => request(
-    `/types/${encodeIdentifier(identifier)}/lifecycle`,
+  const lifecycle = (resource, identifier, operation, dryRun) => request(
+    `/${resource}/${encodeIdentifier(identifier)}/lifecycle`,
     {
       method: "POST",
       body: JSON.stringify({ operation, dryRun })
@@ -129,7 +139,61 @@ function createContentManagementClient(config) {
       method: "PUT",
       body: JSON.stringify(input)
     }),
-    inspectLifecycle: (identifier, operation) => lifecycle(identifier, operation, true),
-    applyLifecycle: (identifier, operation) => lifecycle(identifier, operation, false)
+    inspectLifecycle: (identifier, operation) => lifecycle("types", identifier, operation, true),
+    applyLifecycle: (identifier, operation) => lifecycle("types", identifier, operation, false),
+    listEntries: (input) => request(entryListPath(input)),
+    getEntry: (identifier, locale) => {
+      const query = locale ? `?locale=${encodeURIComponent(locale.trim())}` : "";
+      return request(
+        `/entries/${encodeIdentifier(identifier)}${query}`
+      );
+    },
+    createEntry: (input) => request("/entries", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateEntry: (identifier, input) => request(
+      `/entries/${encodeIdentifier(identifier)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(input)
+      }
+    ),
+    inspectEntryLifecycle: (identifier, operation) => lifecycle("entries", identifier, operation, true),
+    applyEntryLifecycle: (identifier, operation) => lifecycle("entries", identifier, operation, false),
+    listGroups: () => request("/groups"),
+    getGroup: (identifier) => request(
+      `/groups/${encodeIdentifier(identifier)}`
+    ),
+    createGroup: (input) => request("/groups", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateGroup: (identifier, input) => request(
+      `/groups/${encodeIdentifier(identifier)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(input)
+      }
+    ),
+    inspectGroupLifecycle: (identifier, operation) => lifecycle("groups", identifier, operation, true),
+    applyGroupLifecycle: (identifier, operation) => lifecycle("groups", identifier, operation, false),
+    listOptionLists: () => request("/option-lists"),
+    getOptionList: (identifier) => request(
+      `/option-lists/${encodeIdentifier(identifier)}`
+    ),
+    createOptionList: (input) => request("/option-lists", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateOptionList: (identifier, input) => request(
+      `/option-lists/${encodeIdentifier(identifier)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(input)
+      }
+    ),
+    inspectOptionListLifecycle: (identifier, operation) => lifecycle("option-lists", identifier, operation, true),
+    applyOptionListLifecycle: (identifier, operation) => lifecycle("option-lists", identifier, operation, false)
   };
 }

package/content-management.d.ts

@@ -1,125 +1,5 @@
-export type ContentManagementTypeKind = "entry" | "component";
-export type ContentManagementTypeStatus = "draft" | "active" | "archived";
-export type ContentManagementTypeUsage = "website_content" | "product_additional" | "product_specification";
-export type ContentManagementFieldType = "boolean" | "component" | "date" | "link" | "measure" | "media" | "number" | "reference" | "repeater" | "rich_text" | "rich_text_full" | "select" | "slug" | "text" | "textarea";
-export interface ContentManagementChildFieldInput {
-    id?: string | null;
-    key: string;
-    label: string;
-    type: ContentManagementFieldType;
-    required?: boolean;
-    sortOrder: number;
-    settings?: Record<string, unknown>;
-    componentKey?: string | null;
-}
-export interface ContentManagementFieldInput extends ContentManagementChildFieldInput {
-    sectionKey?: string | null;
-    children?: ContentManagementChildFieldInput[];
-}
-export interface ContentManagementTypeInput {
-    key: string;
-    name: string;
-    description?: string;
-    kind: ContentManagementTypeKind;
-    status?: "draft" | "active";
-    settings?: Record<string, unknown>;
-    usages?: ContentManagementTypeUsage[];
-    sections?: Array<{
-        key: string;
-        title: string;
-        description?: string;
-        sortOrder: number;
-    }>;
-    specificationScopes?: Array<{
-        category?: string | null;
-        subcategoryId?: string | null;
-    }>;
-    deletedPaths?: string[];
-    confirmDestructiveChanges?: boolean;
-    fields?: ContentManagementFieldInput[];
-}
-export interface ContentManagementType extends Omit<ContentManagementTypeInput, "status"> {
-    id: string;
-    companyId: string;
-    description: string;
-    status: ContentManagementTypeStatus;
-    settings: Record<string, unknown>;
-    usages: ContentManagementTypeUsage[];
-    sections: Array<{
-        id: string;
-        key: string;
-        title: string;
-        description: string;
-        sortOrder: number;
-    }>;
-    specificationScopes: Array<{
-        id: string;
-        category: string | null;
-        subcategoryId: string | null;
-    }>;
-    fields: ContentManagementFieldInput[];
-    createdAt: string;
-    updatedAt: string;
-}
-export interface ContentManagementContext {
-    companyId: string;
-    scope: "content_types:manage";
-    expiresAt: string;
-}
-export interface ContentManagementReferences {
-    categories: Array<{
-        code: string;
-        name: string;
-        subcategories: Array<{
-            id: string;
-            name: string;
-        }>;
-    }>;
-    optionLists: Array<{
-        key: string;
-        name: string;
-        isExtensible: boolean;
-        options: Array<{
-            value: string;
-            label: string;
-        }>;
-    }>;
-    measureDimensions: Array<{
-        code: string;
-        name: string;
-        canonicalUnitCode: string;
-        units: Array<{
-            code: string;
-            name: string;
-            symbol: string;
-        }>;
-    }>;
-}
-export type ContentManagementLifecycleOperation = "archive" | "restore" | "delete";
-export interface ContentManagementLifecycleResult {
-    success: boolean;
-    allowed: boolean;
-    applied: boolean;
-    entity_id: string | null;
-    entity_type: "type" | "component" | null;
-    operation: ContentManagementLifecycleOperation | null;
-    name: string | null;
-    status: string | null;
-    dependencies: Array<{
-        code: string;
-        label: string;
-        count: number;
-        blocking: boolean;
-    }>;
-    message: string | null;
-    errors: string[];
-}
-export type ContentManagementAccessTokenProvider = () => string | Promise<string>;
-export interface ContentManagementClientConfig {
-    apiUrl: string;
-    accessToken: string | ContentManagementAccessTokenProvider;
-    fetch?: typeof fetch;
-}
+import type { ContentManagementClient, ContentManagementClientConfig } from "./content-management-types";
+export * from "./content-management-types";
 export declare class ContentManagementError extends Error {
     readonly code: string;
     readonly status: number;
@@ -131,14 +11,4 @@ export declare class ContentManagementError extends Error {
         details?: unknown;
     });
 }
-export interface ContentManagementClient {
-    getContext(): Promise<ContentManagementContext>;
-    getReferences(): Promise<ContentManagementReferences>;
-    listTypes(): Promise<ContentManagementType[]>;
-    getType(identifier: string): Promise<ContentManagementType>;
-    createType(input: ContentManagementTypeInput): Promise<ContentManagementType>;
-    updateType(identifier: string, input: ContentManagementTypeInput): Promise<ContentManagementType>;
-    inspectLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
-    applyLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
-}
 export declare function createContentManagementClient(config: ContentManagementClientConfig): ContentManagementClient;

package/content-management.js

@@ -33,6 +33,16 @@ function encodeIdentifier(identifier) {
   }
   return encodeURIComponent(normalized);
 }
+function entryListPath(input = {}) {
+  const search = new URLSearchParams();
+  if (input.contentType) search.set("contentType", input.contentType);
+  if (input.locale) search.set("locale", input.locale);
+  if (input.status) search.set("status", input.status);
+  if (input.limit !== void 0) search.set("limit", String(input.limit));
+  if (input.offset !== void 0) search.set("offset", String(input.offset));
+  const query = search.toString();
+  return query ? `/entries?${query}` : "/entries";
+}
 function createContentManagementClient(config) {
   const apiUrl = normalizeApiUrl(config.apiUrl);
   const fetchImplementation = config.fetch ?? globalThis.fetch;
@@ -84,8 +94,8 @@ function createContentManagementClient(config) {
     }
     return payload.data;
   };
-  const lifecycle = (identifier, operation, dryRun) => request(
-    `/types/${encodeIdentifier(identifier)}/lifecycle`,
+  const lifecycle = (resource, identifier, operation, dryRun) => request(
+    `/${resource}/${encodeIdentifier(identifier)}/lifecycle`,
     {
       method: "POST",
       body: JSON.stringify({ operation, dryRun })
@@ -104,8 +114,62 @@ function createContentManagementClient(config) {
       method: "PUT",
       body: JSON.stringify(input)
     }),
-    inspectLifecycle: (identifier, operation) => lifecycle(identifier, operation, true),
-    applyLifecycle: (identifier, operation) => lifecycle(identifier, operation, false)
+    inspectLifecycle: (identifier, operation) => lifecycle("types", identifier, operation, true),
+    applyLifecycle: (identifier, operation) => lifecycle("types", identifier, operation, false),
+    listEntries: (input) => request(entryListPath(input)),
+    getEntry: (identifier, locale) => {
+      const query = locale ? `?locale=${encodeURIComponent(locale.trim())}` : "";
+      return request(
+        `/entries/${encodeIdentifier(identifier)}${query}`
+      );
+    },
+    createEntry: (input) => request("/entries", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateEntry: (identifier, input) => request(
+      `/entries/${encodeIdentifier(identifier)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(input)
+      }
+    ),
+    inspectEntryLifecycle: (identifier, operation) => lifecycle("entries", identifier, operation, true),
+    applyEntryLifecycle: (identifier, operation) => lifecycle("entries", identifier, operation, false),
+    listGroups: () => request("/groups"),
+    getGroup: (identifier) => request(
+      `/groups/${encodeIdentifier(identifier)}`
+    ),
+    createGroup: (input) => request("/groups", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateGroup: (identifier, input) => request(
+      `/groups/${encodeIdentifier(identifier)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(input)
+      }
+    ),
+    inspectGroupLifecycle: (identifier, operation) => lifecycle("groups", identifier, operation, true),
+    applyGroupLifecycle: (identifier, operation) => lifecycle("groups", identifier, operation, false),
+    listOptionLists: () => request("/option-lists"),
+    getOptionList: (identifier) => request(
+      `/option-lists/${encodeIdentifier(identifier)}`
+    ),
+    createOptionList: (input) => request("/option-lists", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateOptionList: (identifier, input) => request(
+      `/option-lists/${encodeIdentifier(identifier)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(input)
+      }
+    ),
+    inspectOptionListLifecycle: (identifier, operation) => lifecycle("option-lists", identifier, operation, true),
+    applyOptionListLifecycle: (identifier, operation) => lifecycle("option-lists", identifier, operation, false)
   };
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacano/sdk",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "description": "TypeScript SDK for building websites on the Bacano ERP",
   "main": "./index.cjs",
   "module": "./index.js",

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`.
@@ -96,9 +99,16 @@ 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.
+`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.
@@ -113,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
 
@@ -132,9 +152,10 @@ Entregar una tabla legible con:
 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.
+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
 
@@ -159,11 +180,23 @@ 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()`.
+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 componentes y luego tipos consumidores, siempre en borrador.
-6. Para archivar o eliminar, inspeccionar dependencias y confirmar nuevamente.
+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. Las entradas y media permanecen bajo gestión editorial en Bacano.
+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.