@bacano/sdk 1.1.17 → 1.1.19

package/CONTENT_TYPE_MANAGEMENT.md

@@ -2,7 +2,8 @@
 
 `@bacano/sdk/content-management` permite que una herramienta administrativa o
 un agente autorizado consulte y mantenga **tipos, componentes, grupos, listas
-de opciones, entradas e imágenes** de Bacano Content. Cada capacidad requiere
+de opciones, entradas e imágenes** de Bacano Content, y **formularios web**.
+Cada capacidad requiere
 un permiso explícito. El acceso no autoriza productos, ventas, clientes,
 configuración general, GraphQL, SQL ni acceso directo a Storage.
 
@@ -12,7 +13,7 @@ dentro del bundle del sitio web.
 
 ## Activar un acceso temporal
 
-1. En Bacano, abre **Sitios web → Contenido → Tipos** o **Componentes**.
+1. En Bacano, abre **Sitios web → Contenido → Tipos**, **Componentes** o **Formularios**.
 2. Selecciona **Conectar agente**.
 3. Elige el alcance, 15, 30 o 60 minutos y genera el acceso.
 4. Copia el token al entorno local del agente.
@@ -32,6 +33,15 @@ Scopes disponibles:
   también `content_entries:manage`.
 - `content_media:upload`: consultar imágenes de la empresa y cargar JPEG, PNG o
   WebP. Requiere también `content_entries:manage`; no permite borrar archivos.
+- `forms:manage`: consultar sitios y listas disponibles para formularios,
+  inventariar formularios y crear o reemplazar sus borradores.
+- `forms:publish`: publicar, pausar, reactivar o archivar formularios. Requiere
+  `forms:manage`. También se exige para cambiar notificaciones de formularios
+  que ya fueron publicados, porque afectan envíos en curso.
+
+Los permisos de Content no conceden acceso a formularios ni viceversa. Los
+tokens existentes no se amplían; solicita uno nuevo con el alcance necesario.
+Estos permisos no permiten leer respuestas, datos personales, leads ni métricas.
 
 No guardes el token en Git, Figma, Content, logs, variables públicas ni archivos
 que se empaqueten con el storefront.
@@ -432,6 +442,74 @@ omitas opciones existentes por accidente en una actualización.
 - Los tokens v2 no son compatibles con tokens anteriores y tienen como máximo
   60 minutos de vigencia.
 
+## Formularios: misma definición en el agente, el ERP y el storefront
+
+No modeles un formulario como un tipo de Content ni mantengas una copia de sus
+campos en el frontend. Usa el mismo cliente administrativo con `forms:manage`:
+
+1. `getContext()` confirma empresa, scopes y vencimiento.
+2. `getFormReferences()` devuelve los sitios de esa empresa y las Listas de
+   Content activas, con sus pares `value` / `label`.
+3. `listForms({ websiteId, key, limit, offset })` inventaría antes de crear.
+   Las keys son únicas por sitio, no por empresa. Pagina hasta alcanzar `total`.
+4. Presenta al usuario sitio, key, campos, acción y mensajes antes de crear.
+5. `createForm(input)` crea exclusivamente un borrador.
+6. `getForm(formId)` consulta la definición completa y su `updatedAt`.
+7. `updateForm(formId, { ...input, expectedUpdatedAt })` reemplaza el borrador
+   completo. Conserva los campos que deben permanecer; no cambia key ni sitio.
+8. Solo con aprobación humana y `forms:publish`, usa `publishForm(formId,
+   { expectedUpdatedAt })`. Crea una versión inmutable que consume el SDK público.
+
+```ts
+const { websites, optionLists } = await content.getFormReferences();
+// Elegir y confirmar con el usuario un websiteId devuelto por websites.
+const form = await content.createForm({
+  websiteId,
+  key: "solicitar-informacion",
+  name: "Solicitar información",
+  action: "CAPTURE_LEAD",
+  definition: {
+    schemaVersion: 1,
+    submitLabel: "Enviar solicitud",
+    successMessage: "Recibimos tu solicitud.",
+    unavailableMessage: "Este formulario no está disponible.",
+    fields: [
+      { key: "correo", label: "Correo electrónico", type: "email", required: true },
+      {
+        key: "intereses", label: "¿Qué te interesa?", type: "multi_select", required: true,
+        optionSource: { kind: "INLINE", options: [
+          { value: "sitio_web", label: "Sitio web" },
+          { value: "tienda_virtual", label: "Tienda virtual" },
+        ] },
+      },
+    ],
+    sections: [],
+    steps: [],
+  },
+});
+// Tras revisar y aprobar; requiere forms:publish:
+await content.publishForm(form.id, { expectedUpdatedAt: form.updatedAt });
+```
+
+Las opciones `select`, `radio` y `multi_select` usan pares `value` / `label`
+o `optionSource: { kind: "CONTENT_LIST", listKey }`. Reutiliza únicamente una
+lista activa de `getFormReferences()`; administrarla exige el permiso separado
+de Content. Los tipos `email` y `phone` conservan la semántica de contacto.
+`CAPTURE_LEAD` utiliza la resolución de identidad ya existente: no llames además
+a la captura de campañas ni crees otro lead desde el agente.
+
+`changeFormStatus(formId, { status, expectedUpdatedAt })` acepta `ACTIVE`,
+`PAUSED` o `ARCHIVED`, con aprobación humana. Activar o pausar requiere una
+versión publicada; archivar es terminal en el flujo actual. No hay borrado ni
+restauración por este acceso.
+
+Ante `WEBSITE_FORM_REVISION_CONFLICT` (HTTP 409), vuelve a consultar y presenta
+las diferencias; nunca reintentes automáticamente reemplazando la revisión.
+Editar un borrador no publica su estructura: la versión pública anterior sigue
+vigente hasta publicar. Las respuestas y sus snapshots no se reescriben.
+Usa `BacanoForm` o `client.forms` con la key publicada y el mismo website,
+siguiendo `STOREFRONT_FORMS.md`. El token temporal jamás entra en ese bundle.
+
 ## Límites de esta versión
 
 - La carga administrativa solo admite imágenes raster JPEG, PNG y WebP. SVG,

package/README.md

@@ -21,10 +21,10 @@ 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 Bacano Content para agentes
+### Gestión de Content y formularios para agentes
 
 Un agente autorizado puede consultar y mantener tipos, componentes, grupos,
-listas de opciones y entradas con el entrypoint administrativo
+listas de opciones, entradas y formularios 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:
@@ -118,6 +118,14 @@ official `BacanoForm` renderer or consume the same typed definition through
 `useBacanoForm()` without GraphQL, HTML stored in the database or a rebuild
 after each publication.
 
+Every visible region sourced from a Bacano `ContentEntry` must expose the
+entry-level marker defined in
+[`STOREFRONT_CONTENT_LOCATOR.md`](./STOREFRONT_CONTENT_LOCATOR.md). Use
+`getContentEntryLocatorAttributes(entry)` on the outer section or card so an
+authorized internal browser tool can show the entry name and open its Bacano
+editor. This contract identifies entries only; it does not expose field-level
+editing or grant backoffice access.
+
 Static and hybrid stores must also follow
 [`STOREFRONT_PERFORMANCE.md`](./STOREFRONT_PERFORMANCE.md). It defines the
 official build bootstrap, live-state refresh, responsive media and request
@@ -213,7 +221,7 @@ The public storefront remains static. Preview V1 never exposes drafts and
 automatically disables the SDK marketing runtime inside its tree. See
 [`STOREFRONT_PREVIEW.md`](./STOREFRONT_PREVIEW.md), the canonical contract for
 provider hierarchy, responsibilities, security, agent checklist, and the
-validated Baby Rex reference implementation.
+validated reference implementation.
 
 ---
 

package/STOREFRONT_CONTENT_LOCATOR.md

@@ -0,0 +1,111 @@
+# Localizador de entradas de Content
+
+Este documento define el contrato público V1 que permite reconocer desde el
+navegador qué entrada de Bacano Content produce una región visible de una web.
+El objetivo es únicamente **identificar la entrada y abrir su editor**. No es
+edición inline y no identifica campos individuales.
+
+## Contrato obligatorio
+
+Toda región visual cuyo contenido editorial provenga de un `ContentEntry` debe
+marcar su elemento DOM exterior significativo con:
+
+```html
+<section
+  data-bacano-content-entry="v1"
+  data-bacano-entry-key="seccion-de-servicios"
+  data-bacano-entry-name="Sección de servicios"
+  data-bacano-entry-locale="es-CO"
+>
+  <!-- contenido visible -->
+</section>
+```
+
+Usar el helper oficial evita diferencias en nombres, versión y normalización:
+
+```tsx
+import {
+  getContentEntryLocatorAttributes,
+  type ContentEntry,
+} from "@bacano/sdk";
+
+function ServicesSection({ entry }: { entry: ContentEntry }) {
+  return (
+    <section {...getContentEntryLocatorAttributes(entry)}>
+      {/* La sección puede consumir un view model derivado de entry. */}
+    </section>
+  );
+}
+```
+
+El helper falla si la entrada no tiene una `key` estable o un `locale`. Una
+región que no puede abrir una entrada inequívoca no debe aparentar que sí puede.
+
+## Granularidad
+
+- Marcar una vez el bloque visual administrable: `section`, `article`, banner,
+  tarjeta o contenedor equivalente.
+- No marcar títulos, párrafos, botones ni campos individuales dentro del mismo
+  bloque.
+- Si una tarjeta visible usa otra entrada referenciada, la tarjeta recibe su
+  propio marcador anidado. El espacio restante conserva el marcador de la
+  entrada contenedora.
+- Si una entrada produce varias regiones independientes, cada región puede
+  repetir el mismo marcador.
+- No marcar texto perteneciente al código/i18n, productos del catálogo,
+  configuración pública ni documentos legales como si fueran Content.
+
+Los mappers pueden transformar `contentJson`, pero deben conservar el origen
+editorial necesario para llamar el helper. Por ejemplo:
+
+```ts
+const section = {
+  locator: getContentEntryLocatorAttributes(entry),
+  title: readTitle(entry.contentJson),
+};
+```
+
+```tsx
+<section {...section.locator}>{section.title}</section>
+```
+
+## Responsabilidades del consumidor
+
+Una extensión o herramienta de inspección:
+
+1. busca `[data-bacano-content-entry="v1"]`;
+2. muestra `data-bacano-entry-name` al usuario;
+3. usa `data-bacano-entry-key` y `data-bacano-entry-locale` para construir la
+   navegación hacia el backoffice;
+4. deja autenticación, empresa y permisos bajo control de Bacano.
+
+El SDK no publica una URL de administración ni abre ventanas. Ese destino
+pertenece a la herramienta interna y puede cambiar entre ambientes.
+
+## Seguridad y salida estática
+
+Los cuatro atributos contienen exclusivamente identidad editorial ya pública:
+versión, key, nombre y locale de una entrada publicada. Nunca incluir tokens,
+URLs administrativas firmadas, secretos, IDs de usuarios ni datos privados.
+
+Los marcadores no conceden permisos. El backoffice debe autenticar y autorizar
+cualquier lectura o modificación. En exports estáticos los atributos quedan
+materializados junto con el contenido publicado y se actualizan en el siguiente
+build.
+
+## Verificación
+
+Antes de publicar una web que usa Bacano Content:
+
+- inventariar las entradas que producen regiones visibles;
+- inspeccionar el HTML final, no solo JSX o componentes;
+- comprobar que cada región tiene exactamente la key, nombre y locale de su
+  entrada fuente;
+- probar marcadores anidados cuando una entrada contenedora renderiza entradas
+  referenciadas;
+- comprobar que activar una herramienta de localización no altera navegación,
+  layout ni accesibilidad cuando vuelve a desactivarse.
+
+Una región editorial sin marcador o con una key distinta de su fuente es un
+fallo de integración, porque impide localizar de manera confiable el contenido
+que la web declara administrable.

package/STOREFRONT_FORMS.md

@@ -4,6 +4,12 @@ Los formularios públicos de Bacano son definiciones tipadas y versionadas. El
 storefront decide dónde se muestran y cómo lucen; Bacano controla su estructura,
 estado y validaciones. La definición nunca contiene HTML ni JavaScript arbitrario.
 
+Un agente puede crear y editar estas mismas definiciones desde
+`@bacano/sdk/content-management`, con el acceso temporal de **Conectar agente**.
+Lee la sección de formularios en `CONTENT_TYPE_MANAGEMENT.md`: `forms:manage`
+prepara borradores y `forms:publish` permite publicar con aprobación. Nunca
+incluyas ese cliente administrativo ni su token en el storefront público.
+
 ## Renderer oficial para React
 
 Monta un único `BacanoProvider` global y usa la key pública configurada en el ERP:
@@ -81,6 +87,47 @@ El renderer personalizado puede cambiar componentes y estilos, pero debe usar
 los campos, keys, opciones y validaciones entregados por el SDK. No debe crear
 un segundo cliente, resolver el website nuevamente ni usar GraphQL directo.
 
+## Honeypot y confirmación de persistencia
+
+`honeypot` es un campo trampa contra bots, no un token de seguridad. No es una
+marca de tiempo, un UUID, un número aleatorio ni un identificador del visitante.
+Un usuario real debe enviarlo siempre vacío.
+
+- `BacanoForm` administra el honeypot internamente. El storefront no debe crear
+  otro ni asignarle un valor.
+- Un renderer personalizado debe omitir `honeypot` en
+  `client.forms.submitResponse(...)` salvo que implemente deliberadamente un
+  input trampa oculto. El SDK lo enviará como cadena vacía por defecto.
+- Si se implementa el input trampa, debe quedar fuera del flujo visual y del
+  teclado, con autocompletado desactivado. Nunca debe reutilizar un campo real ni
+  recibir sugerencias del navegador o de un gestor de contraseñas.
+- Bacano responde de manera deliberadamente genérica ante un honeypot lleno:
+  `accepted: true` y `responseId: null`. La respuesta no se persiste y el bot no
+  descubre que fue detectado.
+- Para una prueba funcional o aprobación de producción, el envío debe devolver
+  `accepted: true` y un UUID en `responseId`, y debe aparecer una sola vez en
+  Respuestas dentro de Bacano.
+
+No uses `responseId: null` para mostrar información distinta al visitante. Es
+una señal técnica para pruebas y observabilidad segura, no un mensaje que deba
+revelar la protección antispam.
+
+## Tipos semánticos de contacto
+
+La etiqueta y la key no sustituyen el tipo del campo. Si un dato representa un
+correo o un teléfono, el formulario debe definirlo como `email` o `phone`:
+
+- Bacano valida el formato según el tipo declarado.
+- Las respuestas conservan todos los valores, pero solo los campos `email` y
+  `phone` alimentan los datos de contacto normalizados de la respuesta.
+- Un campo `text` llamado `correo`, `email`, `telefono` o similar continúa
+  siendo texto libre. No debe dependerse de su nombre para CRM, leads o futuras
+  automatizaciones.
+
+Antes de publicar, revisa que los campos destinados a identificar o contactar a
+la persona tengan el tipo correcto. Cambiar únicamente su etiqueta no corrige el
+contrato de datos.
+
 ## Next.js y Static First
 
 Obtén la definición durante el build o desde un Server Component usando el
@@ -127,15 +174,32 @@ consultarlo.
   validación del navegador mejora la experiencia, pero no es autoritativa.
 - URL, referidor y atribución se sanean. Las respuestas y datos personales no
   se escriben en logs.
-- Una falla futura de correo, CRM o automatización no revierte la respuesta.
-- `CAPTURE_LEAD` se procesa en una fase posterior. Toda respuesta se conserva
-  primero y de forma independiente.
+- `pageUrl`, `referrerUrl` y la URL de atribución aceptan únicamente HTTP o
+  HTTPS. No envíes protocolos locales, ejecutables o de datos.
+- Los teléfonos admiten un `+` inicial y separadores habituales; Bacano los
+  normaliza antes de resolver identidad y rechaza letras o signos mal ubicados.
+- Los números usan notación decimal o científica explícita. Valores ambiguos
+  como `0x10` o `3 unidades` se rechazan aunque JavaScript pudiera convertirlos.
+- Un checkbox opcional omitido se conserva como `null`; uno requerido debe
+  enviarse expresamente como `true`.
+- Una falla de correo, CRM o automatización no revierte la respuesta.
+- `STORE_RESPONSE` conserva la respuesta sin crear un lead.
+- `CAPTURE_LEAD` conserva primero la respuesta y después resuelve internamente
+  la identidad canónica. Reutiliza un lead o cliente existente, crea un lead
+  cuando corresponde y manda a revisión las coincidencias contradictorias de
+  correo y teléfono sin fusionarlas automáticamente.
+- El resultado público continúa siendo deliberadamente genérico. El storefront
+  no recibe ni debe inferir si Bacano creó un lead, encontró un cliente o marcó
+  una identidad para revisión.
 
 ## Checklist mínimo del storefront
 
 - Usar un solo `BacanoProvider` y el cliente global ya inicializado.
 - Renderizar con `BacanoForm` o con `useBacanoForm`; nunca copiar la definición
   a un esquema local ni consultar GraphQL directamente.
+- Pueden coexistir varios `BacanoForm` en una página. El renderer oficial aísla
+  los identificadores de sus controles; no construyas IDs globales solo con la
+  key del campo.
 - Entregar `initialForm` cuando la página se genera de forma estática.
 - Respetar `ACTIVE`, `PAUSED`, versión y `definitionHash` sin inferir estados.
 - Mantener una `idempotencyKey` estable durante los reintentos del mismo envío.
@@ -143,5 +207,11 @@ consultarlo.
   reintento idempotente y error de red.
 - Confirmar en Bacano que una respuesta real quedó persistida antes de aprobar
   el flujo; no basta con mostrar el mensaje de éxito del navegador.
-- No prometer correo, lead, solicitud o automatización mientras la capacidad no
-  esté implementada y activa en Bacano.
+- Probar autocompletado del navegador y gestores de contraseñas: ningún campo
+  real puede llenar el honeypot. Un envío real debe devolver un UUID como
+  `responseId`; `null` no demuestra persistencia.
+- Verificar que correos y teléfonos utilicen los tipos `email` y `phone`, no
+  campos de texto con una etiqueta parecida.
+- No prometer correo, cupón, solicitud ni automatización mientras la capacidad
+  no esté implementada y activa en Bacano. Aunque `CAPTURE_LEAD` esté activo,
+  el mensaje público no debe afirmar qué identidad interna se creó o reutilizó.

package/STOREFRONT_LEADS.md

@@ -50,7 +50,7 @@ if (!consent) return null;
 // Conserva esta clave en el estado del formulario mientras reintentas el envío.
 const idempotencyKey = crypto.randomUUID();
 const result = await client.marketing.captureLead({
-  campaignKey: "newsletter-baby-rex",
+  campaignKey: "newsletter-primavera",
   idempotencyKey,
   commercialConsent: true,
   contact: {

package/STOREFRONT_PREVIEW.md

@@ -227,6 +227,7 @@ export default function PreviewPage() {
 "use client";
 
 import { useSearchParams } from "next/navigation";
+import { useState } from "react";
 import {
   BacanoPreviewShell,
   interceptPreviewLink,
@@ -265,7 +266,11 @@ const loadRoute: PreviewRouteLoader<PreviewDocument> = async ({
 
 export function PreviewClient() {
   const searchParams = useSearchParams();
-  const route = normalizePreviewRoute(searchParams.get("route"));
+  // Initial value only. Held in state afterwards so `navigate` can change it
+  // without a reload; listen for `popstate` to keep the back button working.
+  const [route, setRoute] = useState(() =>
+    normalizePreviewRoute(searchParams.get("route")),
+  );
 
   return (
     <BacanoPreviewShell
@@ -274,9 +279,17 @@ export function PreviewClient() {
       loadRoute={loadRoute}
       isPreviewableRoute={(nextRoute) => previewable.has(nextRoute)}
       navigate={(nextRoute) => {
-        window.location.assign(
+        // pushState, not location.assign. A full navigation unmounts the
+        // provider, and its route cache lives in a ref on it — so assigning
+        // location throws away every already-loaded route and refetches the
+        // one you are navigating to. Keep the route in state and let the
+        // provider reload it in place.
+        window.history.pushState(
+          null,
+          "",
           `/vista-previa/?route=${encodeURIComponent(nextRoute)}`,
         );
+        setRoute(nextRoute);
       }}
       toolbar={{
         websiteName: "My store",
@@ -414,10 +427,10 @@ When the storefront follows this contract:
 The build still depends on whatever Bacano data the public static pages request
 at build time. Preview does not change or replace that build contract.
 
-## Validated reference implementation: Baby Rex
+## Validated reference implementation
 
-Baby Rex validated the official integration with `@bacano/sdk` `1.0.5` on
-2026-08-06. It uses one global `BacanoProvider`; `BacanoPreviewShell` consumes
+A customer storefront validated the official integration with `@bacano/sdk`
+`1.0.5` on 2026-08-06. It uses one global `BacanoProvider`; `BacanoPreviewShell` consumes
 that initialized client and the loader receives `{ route, force, client }`.
 
 The validated static production build generated all `417/417` pages. TypeScript,
@@ -435,7 +448,7 @@ The implementation removed these generic storefront responsibilities:
 - Pathname-based marketing suppression inside preview renderers once the SDK
   boundary covers them.
 
-Baby Rex retained these storefront-specific responsibilities:
+That storefront retained these storefront-specific responsibilities:
 
 - `/vista-previa/page.tsx` and its `noindex` metadata.
 - Sitemap exclusion.
@@ -445,9 +458,9 @@ Baby Rex retained these storefront-specific responsibilities:
   content-driven catalog sections.
 - `PreviewDocumentView` and all production renderers.
 - Storefront-specific skeleton, missing-content, and unsupported-route views.
-- The Next.js adapter that writes `?ruta={encodedRoute}`.
+- The Next.js adapter that writes `?route={encodedRoute}`.
 
-Baby Rex is the implementation reference for integration shape, not a source to
+It is the implementation reference for integration shape, not a source to
 copy blindly. Other storefronts keep their own route maps, Content keys,
 mappers, and visual components.
 

package/STOREFRONT_VOLUME_PRICING.md

@@ -124,7 +124,7 @@ confirmado.
 
 ## Prohibiciones
 
-- No calcular umbrales en Baby Rex ni en otro storefront.
+- No calcular umbrales en el storefront.
 - No seleccionar `WHOLESALE` directamente desde el navegador.
 - No enviar precios en operaciones de carrito o checkout.
 - No consultar Hasura ni tablas de precios mediante GraphQL directo.

package/content-entry-locator.d.ts

@@ -0,0 +1,16 @@
+import type { ContentEntry } from "./types";
+export declare const CONTENT_ENTRY_LOCATOR_VERSION: "v1";
+export declare const CONTENT_ENTRY_LOCATOR_SELECTOR: "[data-bacano-content-entry=\"v1\"]";
+export type ContentEntryLocatorSource = Pick<ContentEntry, "key" | "locale" | "name">;
+export interface ContentEntryLocatorAttributes {
+    "data-bacano-content-entry": typeof CONTENT_ENTRY_LOCATOR_VERSION;
+    "data-bacano-entry-key": string;
+    "data-bacano-entry-locale": string;
+    "data-bacano-entry-name": string;
+}
+/**
+ * Adds the public, non-authoritative marker consumed by Bacano's content
+ * locator. Spread the result only on the outermost meaningful DOM element
+ * whose visible editorial content is owned by the entry.
+ */
+export declare function getContentEntryLocatorAttributes(entry: ContentEntryLocatorSource): ContentEntryLocatorAttributes;

package/content-management-types.d.ts

@@ -1,7 +1,8 @@
+import type { FormManagementClient } from "./form-management-types";
 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 ContentManagementScope = "content_types:manage" | "content_entries:manage" | "content_media:upload" | "content_entries:publish" | "forms:manage" | "forms: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;
@@ -65,7 +66,7 @@ export interface ContentManagementType extends Omit<ContentManagementTypeInput,
 export interface ContentManagementContext {
     companyId: string;
     /** @deprecated Use scopes to inspect the complete grant. */
-    scope: "content_types:manage";
+    scope: ContentManagementScope;
     scopes: ContentManagementScope[];
     expiresAt: string;
 }
@@ -259,7 +260,7 @@ export interface ContentManagementClientConfig {
     accessToken: string | ContentManagementAccessTokenProvider;
     fetch?: typeof fetch;
 }
-export interface ContentManagementClient {
+export interface ContentManagementClient extends FormManagementClient {
     getContext(): Promise<ContentManagementContext>;
     getReferences(): Promise<ContentManagementReferences>;
     listTypes(): Promise<ContentManagementType[]>;

package/content-management.cjs

@@ -24,6 +24,42 @@ __export(content_management_exports, {
   createContentManagementClient: () => createContentManagementClient
 });
 module.exports = __toCommonJS(content_management_exports);
+
+// libs/sdk/src/form-management.ts
+function createFormManagementMethods(request) {
+  const path = (id) => `/forms/${encodeURIComponent(id.trim())}`;
+  return {
+    getFormReferences: () => request("/forms/references"),
+    listForms: (input = {}) => {
+      const search = new URLSearchParams();
+      for (const key of ["websiteId", "key", "limit", "offset"]) {
+        if (input[key] !== void 0) search.set(key, String(input[key]));
+      }
+      return request(
+        `/forms${search.size ? `?${search}` : ""}`
+      );
+    },
+    getForm: (id) => request(path(id)),
+    createForm: (input) => request("/forms", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateForm: (id, input) => request(path(id), {
+      method: "PUT",
+      body: JSON.stringify(input)
+    }),
+    publishForm: (id, input) => request(`${path(id)}/publish`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    changeFormStatus: (id, input) => request(`${path(id)}/status`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    })
+  };
+}
+
+// libs/sdk/src/content-management.ts
 var ContentManagementError = class extends Error {
   code;
   status;
@@ -145,6 +181,7 @@ function createContentManagementClient(config) {
     }
   );
   return {
+    ...createFormManagementMethods(request),
     getContext: () => request("/context"),
     getReferences: () => request("/references"),
     listTypes: () => request("/types"),

package/content-management.d.ts

@@ -1,5 +1,6 @@
 import type { ContentManagementClient, ContentManagementClientConfig } from "./content-management-types";
 export * from "./content-management-types";
+export * from "./form-management-types";
 export declare class ContentManagementError extends Error {
     readonly code: string;
     readonly status: number;

package/content-management.js

@@ -1,3 +1,37 @@
+// libs/sdk/src/form-management.ts
+function createFormManagementMethods(request) {
+  const path = (id) => `/forms/${encodeURIComponent(id.trim())}`;
+  return {
+    getFormReferences: () => request("/forms/references"),
+    listForms: (input = {}) => {
+      const search = new URLSearchParams();
+      for (const key of ["websiteId", "key", "limit", "offset"]) {
+        if (input[key] !== void 0) search.set(key, String(input[key]));
+      }
+      return request(
+        `/forms${search.size ? `?${search}` : ""}`
+      );
+    },
+    getForm: (id) => request(path(id)),
+    createForm: (input) => request("/forms", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateForm: (id, input) => request(path(id), {
+      method: "PUT",
+      body: JSON.stringify(input)
+    }),
+    publishForm: (id, input) => request(`${path(id)}/publish`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    changeFormStatus: (id, input) => request(`${path(id)}/status`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    })
+  };
+}
+
 // libs/sdk/src/content-management.ts
 var ContentManagementError = class extends Error {
   code;
@@ -120,6 +154,7 @@ function createContentManagementClient(config) {
     }
   );
   return {
+    ...createFormManagementMethods(request),
     getContext: () => request("/context"),
     getReferences: () => request("/references"),
     listTypes: () => request("/types"),

package/form-management-types.d.ts

@@ -0,0 +1,62 @@
+import type { WebsiteFormAction, WebsiteFormDefinition } from "./types";
+export interface ManagedFormInput {
+    websiteId: string;
+    key: string;
+    name: string;
+    description?: string;
+    action?: WebsiteFormAction;
+    notifyByEmail?: boolean;
+    notificationRecipients?: string[];
+    definition: WebsiteFormDefinition;
+}
+export interface ManagedForm extends Required<ManagedFormInput> {
+    id: string;
+    companyId: string;
+    status: "DRAFT" | "ACTIVE" | "PAUSED" | "ARCHIVED";
+    publishedVersion: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ManagedFormListInput {
+    websiteId?: string;
+    key?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ManagedFormList {
+    forms: ManagedForm[];
+    total: number;
+}
+export interface ManagedFormReferences {
+    websites: Array<{
+        id: string;
+        name: string;
+        slug: string;
+        isActive: boolean;
+    }>;
+    optionLists: Array<{
+        key: string;
+        name: string;
+        options: Array<{
+            value: string;
+            label: string;
+        }>;
+    }>;
+}
+export interface FormManagementClient {
+    getFormReferences(): Promise<ManagedFormReferences>;
+    listForms(input?: ManagedFormListInput): Promise<ManagedFormList>;
+    getForm(formId: string): Promise<ManagedForm>;
+    createForm(input: ManagedFormInput): Promise<ManagedForm>;
+    /** Replaces the full draft. Preserve existing fields and use the last read revision. */
+    updateForm(formId: string, input: ManagedFormInput & {
+        expectedUpdatedAt: string;
+    }): Promise<ManagedForm>;
+    publishForm(formId: string, input: {
+        expectedUpdatedAt: string;
+    }): Promise<ManagedForm>;
+    changeFormStatus(formId: string, input: {
+        status: "ACTIVE" | "PAUSED" | "ARCHIVED";
+        expectedUpdatedAt: string;
+    }): Promise<ManagedForm>;
+}

package/form-management.d.ts

@@ -0,0 +1,2 @@
+import type { FormManagementClient } from "./form-management-types";
+export declare function createFormManagementMethods(request: <T>(path: string, init?: RequestInit) => Promise<T>): FormManagementClient;

package/index.cjs

@@ -21,6 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthError: () => AuthError,
+  CONTENT_ENTRY_LOCATOR_SELECTOR: () => CONTENT_ENTRY_LOCATOR_SELECTOR,
+  CONTENT_ENTRY_LOCATOR_VERSION: () => CONTENT_ENTRY_LOCATOR_VERSION,
   CheckoutError: () => CheckoutError,
   GraphQLRequestError: () => GraphQLRequestError,
   MARKETING_SCHEMA_VERSION: () => MARKETING_SCHEMA_VERSION,
@@ -38,6 +40,7 @@ __export(index_exports, {
   createWebsiteMarketingRuntime: () => createWebsiteMarketingRuntime,
   formatMediaSrcSet: () => formatMediaSrcSet,
   getAllowedMarketingParameters: () => getAllowedMarketingParameters,
+  getContentEntryLocatorAttributes: () => getContentEntryLocatorAttributes,
   getPrimaryProductImage: () => getPrimaryProductImage,
   getProductDetailVariants: () => getProductDetailVariants,
   getProductImages: () => getProductImages,
@@ -6904,3 +6907,23 @@ function createBacanoClient(config) {
     }
   };
 }
+
+// libs/sdk/src/content-entry-locator.ts
+var CONTENT_ENTRY_LOCATOR_VERSION = "v1";
+var CONTENT_ENTRY_LOCATOR_SELECTOR = `[data-bacano-content-entry="${CONTENT_ENTRY_LOCATOR_VERSION}"]`;
+function getContentEntryLocatorAttributes(entry) {
+  const key = entry.key?.trim();
+  if (!key) {
+    throw new Error("A Bacano Content locator requires a stable entry key.");
+  }
+  const locale = entry.locale.trim();
+  if (!locale) {
+    throw new Error("A Bacano Content locator requires an entry locale.");
+  }
+  return {
+    "data-bacano-content-entry": CONTENT_ENTRY_LOCATOR_VERSION,
+    "data-bacano-entry-key": key,
+    "data-bacano-entry-locale": locale,
+    "data-bacano-entry-name": entry.name.trim() || key
+  };
+}

package/index.d.ts

@@ -1,5 +1,7 @@
 export type { BacanoClient } from "./client";
 export { createBacanoClient } from "./client";
+export type { ContentEntryLocatorAttributes, ContentEntryLocatorSource, } from "./content-entry-locator";
+export { CONTENT_ENTRY_LOCATOR_SELECTOR, CONTENT_ENTRY_LOCATOR_VERSION, getContentEntryLocatorAttributes, } from "./content-entry-locator";
 export { AuthError, CheckoutError, GraphQLRequestError, NotInitializedError, RateLimitError, WebsiteError, } from "./errors";
 export type { WebsiteAdvertisingConsent, WebsiteMarketingAttribution, WebsiteMarketingBrowserEvent, WebsiteMarketingBrowserEventName, WebsiteMarketingContactPlacement, WebsiteMarketingDiagnostic, WebsiteMarketingItem, WebsiteMarketingRuntime, WebsiteMarketingRuntimeOptions, WebsiteMarketingScriptLoadStrategy, WebsiteMarketingTouchpoint, } from "./marketing";
 export { captureWebsiteMarketingAttribution, createWebsiteMarketingRuntime, getAllowedMarketingParameters, getWebsiteMarketingAttribution, MARKETING_SCHEMA_VERSION, sanitizeMarketingUrl, WEBSITE_MARKETING_CONTACT_PLACEMENTS, } from "./marketing";

package/index.js

@@ -6850,8 +6850,30 @@ function createBacanoClient(config) {
     }
   };
 }
+
+// libs/sdk/src/content-entry-locator.ts
+var CONTENT_ENTRY_LOCATOR_VERSION = "v1";
+var CONTENT_ENTRY_LOCATOR_SELECTOR = `[data-bacano-content-entry="${CONTENT_ENTRY_LOCATOR_VERSION}"]`;
+function getContentEntryLocatorAttributes(entry) {
+  const key = entry.key?.trim();
+  if (!key) {
+    throw new Error("A Bacano Content locator requires a stable entry key.");
+  }
+  const locale = entry.locale.trim();
+  if (!locale) {
+    throw new Error("A Bacano Content locator requires an entry locale.");
+  }
+  return {
+    "data-bacano-content-entry": CONTENT_ENTRY_LOCATOR_VERSION,
+    "data-bacano-entry-key": key,
+    "data-bacano-entry-locale": locale,
+    "data-bacano-entry-name": entry.name.trim() || key
+  };
+}
 export {
   AuthError,
+  CONTENT_ENTRY_LOCATOR_SELECTOR,
+  CONTENT_ENTRY_LOCATOR_VERSION,
   CheckoutError,
   GraphQLRequestError,
   MARKETING_SCHEMA_VERSION,
@@ -6869,6 +6891,7 @@ export {
   createWebsiteMarketingRuntime,
   formatMediaSrcSet,
   getAllowedMarketingParameters,
+  getContentEntryLocatorAttributes,
   getPrimaryProductImage,
   getProductDetailVariants,
   getProductImages,

package/package.json

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

package/react/form-field-control.d.ts

@@ -3,6 +3,7 @@ import type { BacanoFormValues } from "./forms";
 type BacanoFormValue = BacanoFormValues[string];
 export declare function BacanoFormFieldControl(props: {
     field: WebsiteFormField;
+    id?: string;
     className?: string;
     value: BacanoFormValue;
     onChange(value: BacanoFormValue): void;

package/react/forms.cjs

@@ -30,8 +30,9 @@ var import_react3 = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
 function BacanoFormFieldControl(props) {
   const { field, className, value, onChange } = props;
+  const controlId = props.id ?? field.key;
   const common = {
-    id: field.key,
+    id: controlId,
     name: field.key,
     required: field.required,
     className
@@ -71,7 +72,7 @@ function BacanoFormFieldControl(props) {
     );
   }
   if (field.type === "radio") {
-    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { role: "radiogroup", "aria-labelledby": `${field.key}-label`, children: (field.options ?? []).map((option) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("label", { children: [
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { role: "radiogroup", "aria-labelledby": `${controlId}-label`, children: (field.options ?? []).map((option) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("label", { children: [
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
         "input",
         {
@@ -210,13 +211,14 @@ function useBacanoForm(formKey, options) {
 }
 function FormFields(props) {
   return props.fields.map((field) => {
+    const controlId = `${props.idPrefix}-${field.key}`;
     const value = props.values[field.key] ?? (field.type === "checkbox" ? false : field.type === "multi_select" ? [] : "");
     return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: props.classNames?.field, children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
         "label",
         {
-          id: `${field.key}-label`,
-          htmlFor: field.type === "radio" ? void 0 : field.key,
+          id: `${controlId}-label`,
+          htmlFor: field.type === "radio" ? void 0 : controlId,
           className: props.classNames?.label,
           children: field.label
         }
@@ -225,6 +227,7 @@ function FormFields(props) {
         BacanoFormFieldControl,
         {
           field,
+          id: controlId,
           value,
           className: props.classNames?.input,
           onChange: (nextValue) => props.onChange(field.key, nextValue)
@@ -242,6 +245,7 @@ function FormSections(props) {
       FormFields,
       {
         fields: section.fields,
+        idPrefix: props.idPrefix,
         values: props.values,
         classNames: props.classNames,
         onChange: props.onChange
@@ -250,6 +254,8 @@ function FormSections(props) {
   ] }, section.key));
 }
 function BacanoForm(props) {
+  const reactId = (0, import_react3.useId)();
+  const idPrefix = `${props.formKey}-${reactId.replace(/:/g, "")}`;
   const { client } = useBacanoState();
   const { form, loading, error } = useBacanoForm(props.formKey, {
     initialForm: props.initialForm
@@ -382,6 +388,7 @@ function BacanoForm(props) {
             FormFields,
             {
               fields: activeStep.fields,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -391,6 +398,7 @@ function BacanoForm(props) {
             FormSections,
             {
               sections: activeStep.sections,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -401,6 +409,7 @@ function BacanoForm(props) {
             FormFields,
             {
               fields,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -410,6 +419,7 @@ function BacanoForm(props) {
             FormSections,
             {
               sections,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue

package/react/forms.js

@@ -2,6 +2,7 @@
 import {
   useCallback as useCallback2,
   useEffect as useEffect2,
+  useId,
   useMemo,
   useRef as useRef2,
   useState as useState2
@@ -11,8 +12,9 @@ import {
 import { jsx, jsxs } from "react/jsx-runtime";
 function BacanoFormFieldControl(props) {
   const { field, className, value, onChange } = props;
+  const controlId = props.id ?? field.key;
   const common = {
-    id: field.key,
+    id: controlId,
     name: field.key,
     required: field.required,
     className
@@ -52,7 +54,7 @@ function BacanoFormFieldControl(props) {
     );
   }
   if (field.type === "radio") {
-    return /* @__PURE__ */ jsx("div", { role: "radiogroup", "aria-labelledby": `${field.key}-label`, children: (field.options ?? []).map((option) => /* @__PURE__ */ jsxs("label", { children: [
+    return /* @__PURE__ */ jsx("div", { role: "radiogroup", "aria-labelledby": `${controlId}-label`, children: (field.options ?? []).map((option) => /* @__PURE__ */ jsxs("label", { children: [
       /* @__PURE__ */ jsx(
         "input",
         {
@@ -191,13 +193,14 @@ function useBacanoForm(formKey, options) {
 }
 function FormFields(props) {
   return props.fields.map((field) => {
+    const controlId = `${props.idPrefix}-${field.key}`;
     const value = props.values[field.key] ?? (field.type === "checkbox" ? false : field.type === "multi_select" ? [] : "");
     return /* @__PURE__ */ jsxs2("div", { className: props.classNames?.field, children: [
       /* @__PURE__ */ jsx2(
         "label",
         {
-          id: `${field.key}-label`,
-          htmlFor: field.type === "radio" ? void 0 : field.key,
+          id: `${controlId}-label`,
+          htmlFor: field.type === "radio" ? void 0 : controlId,
           className: props.classNames?.label,
           children: field.label
         }
@@ -206,6 +209,7 @@ function FormFields(props) {
         BacanoFormFieldControl,
         {
           field,
+          id: controlId,
           value,
           className: props.classNames?.input,
           onChange: (nextValue) => props.onChange(field.key, nextValue)
@@ -223,6 +227,7 @@ function FormSections(props) {
       FormFields,
       {
         fields: section.fields,
+        idPrefix: props.idPrefix,
         values: props.values,
         classNames: props.classNames,
         onChange: props.onChange
@@ -231,6 +236,8 @@ function FormSections(props) {
   ] }, section.key));
 }
 function BacanoForm(props) {
+  const reactId = useId();
+  const idPrefix = `${props.formKey}-${reactId.replace(/:/g, "")}`;
   const { client } = useBacanoState();
   const { form, loading, error } = useBacanoForm(props.formKey, {
     initialForm: props.initialForm
@@ -363,6 +370,7 @@ function BacanoForm(props) {
             FormFields,
             {
               fields: activeStep.fields,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -372,6 +380,7 @@ function BacanoForm(props) {
             FormSections,
             {
               sections: activeStep.sections,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -382,6 +391,7 @@ function BacanoForm(props) {
             FormFields,
             {
               fields,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -391,6 +401,7 @@ function BacanoForm(props) {
             FormSections,
             {
               sections,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue

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

@@ -91,7 +91,12 @@ Figma, desde Bacano Content o desde ambas fuentes.
   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.
+- Marcar obligatoriamente cada región visual proveniente de un `ContentEntry`
+  con `getContentEntryLocatorAttributes(entry)`. El marcador identifica la
+  entrada completa, nunca campos individuales. Conservar esta identidad al
+  transformar Content en view models y seguir
+  `STOREFRONT_CONTENT_LOCATOR.md`.
+- No alterar el storefront de 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
@@ -147,6 +152,9 @@ 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.
+Inspeccionar además el HTML final: toda región alimentada por una entrada debe
+conservar su marcador V1 con la key, nombre y locale correctos. Una región
+editorial sin marcador bloquea la aprobación.
 
 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

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

@@ -7,9 +7,9 @@ negocio.
 
 Antes de programar, registrar por ruta:
 
-| Ruta | Frame | Componente | Fuente | Content | Responsive | Preview | Estado |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `/` | Home desktop/mobile | `Hero` | Content | `hero_inicio` | 2 frames | activa | pendiente |
+| Ruta | Frame | Componente | Fuente | Content | Localizador | Responsive | Preview | Estado |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `/` | Home desktop/mobile | `Hero` | Content | `hero_inicio` | entrada V1 | 2 frames | activa | pendiente |
 
 Fuentes posibles: Content, catálogo estático, live state, public config,
 checkout, auth u otra operación documentada del SDK.
@@ -18,6 +18,8 @@ checkout, auth u otra operación documentada del SDK.
 
 - Usar componentes y tokens existentes antes de crear otros.
 - Mapear textos/imágenes editoriales a Content cuando deban ser administrables.
+- Para cada fuente `ContentEntry`, conservar y renderizar el marcador de entrada
+  definido en `STOREFRONT_CONTENT_LOCATOR.md`; no bajar a nivel de campo.
 - 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.

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

@@ -11,6 +11,7 @@ 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 |
+| Campos, opciones, pasos y validaciones de formularios | Formularios de Bacano; nunca tipos de 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 |
@@ -19,6 +20,12 @@ 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.
 
+Para materializar un formulario del diseño, seguir `STOREFRONT_FORMS.md` y la
+sección de formularios de `CONTENT_TYPE_MANAGEMENT.md`. El cliente temporal
+admite `forms:manage` para crear/editar borradores y `forms:publish` para publicar
+con confirmación. Reutilizar la definición del ERP y sus pares value/label;
+no inventar un esquema paralelo. Los conflictos de revisión requieren releer.
+
 ## Modelar sin extremos
 
 No convertir una página extensa en un único tipo gigante ni crear un componente
@@ -35,6 +42,10 @@ reduzca duplicación real.
   consumidores.
 - No hacer depender la UI del shape crudo de Content: fixture y mapper real
   deben converger en el mismo view model.
+- Conservar en ese view model los atributos producidos por
+  `getContentEntryLocatorAttributes(entry)`. Toda región visual administrada
+  por una entrada debe exponerlos en su contenedor DOM exterior; no se marcan
+  campos individuales.
 
 ## 2. Elegir el punto de partida
 
@@ -138,6 +149,10 @@ Bacano mapper ─┘
 El cambio de fuente debe ocurrir en el loader o repositorio de contenido, nunca
 mediante condicionales repartidos por los componentes.
 
+Los fixtures pueden simular el view model, pero no deben inventar marcadores de
+entrada en producción. El marcador definitivo se deriva del `ContentEntry`
+real para que nombre, key y locale no diverjan.
+
 ## 5. Entrega al equipo de Content
 
 Entregar una tabla legible con:
@@ -167,7 +182,9 @@ Antes de retirar el fixture:
 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.
+5. Inspeccionar el HTML y confirmar los marcadores definidos en
+   `STOREFRONT_CONTENT_LOCATOR.md` para cada región editorial.
+6. 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

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

@@ -58,6 +58,18 @@ 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.
 
+## Trazabilidad editorial
+
+Al mapear un `ContentEntry`, conservar los atributos retornados por
+`getContentEntryLocatorAttributes(entry)` hasta el componente visual. Aplicar
+el spread al `section`, `article`, banner o tarjeta exterior que representa la
+entrada. No repetirlo en cada título o párrafo. Si una tarjeta proviene de otra
+entrada referenciada, esa tarjeta lleva su propio marcador anidado.
+
+La salida final debe cumplir `STOREFRONT_CONTENT_LOCATOR.md`. Verificar el HTML
+generado; encontrar la llamada al helper en TypeScript no demuestra que el
+marcador haya llegado al DOM.
+
 ## Diagnóstico antes de cambiar código
 
 Un `ORIGIN_NOT_ALLOWED` o un `403` al resolver la configuración durante el

package/skills/bacano-web/SKILL.md

@@ -47,7 +47,8 @@ Después leer solo:
 Si `@bacano/sdk` está disponible, leer sus contratos canónicos aplicables antes
 de proponer cambios. Como mínimo revisar `STOREFRONT_LEGAL.md`,
 `STOREFRONT_MARKETING.md`, `STOREFRONT_PERFORMANCE.md` y
-`STOREFRONT_PREVIEW.md`; añadir
+`STOREFRONT_PREVIEW.md`; si el sitio renderiza Bacano Content, leer también y
+aplicar obligatoriamente `STOREFRONT_CONTENT_LOCATOR.md`; añadir
 `AUTHENTICATION.md`, `STOREFRONT_LEADS.md`, `STOREFRONT_CLARITY.md` y
 otros contratos únicamente cuando esas capacidades existan. Leer
 `STOREFRONT_CONSTRUCTION.md` cuando el website permita ocultarse temporalmente.
@@ -70,6 +71,8 @@ ejecutar compras/pagos sin autorización explícita.
 5. Comparar router, salida del build y sitemap; ninguna ruta pública debe
    omitirse silenciosamente.
 6. Inspeccionar HTML generado, metadata, JSON-LD, media y enlaces internos.
+   Si existe Content, comparar las entradas renderizadas con los marcadores V1
+   presentes en ese HTML; revisar únicamente el JSX no es evidencia suficiente.
 7. Si existe un dominio o una aplicación ejecutable, auditar sus rutas reales,
    la consola y un trace de red con nombres y conteos de operaciones GraphQL.
 8. Probar vistas representativas desktop y mobile.

package/skills/bacano-web/references/common.md

@@ -29,6 +29,13 @@ función apagada en un bloqueo artificial.
 - Comprobar que preview, callbacks, cuenta, checkout y respuestas de pago no se
   indexen cuando corresponda.
 - Validar estados vacío, loading, error y ausencia de Content opcional.
+- `P0`: toda región visual cuya fuente sea un `ContentEntry` expone en el HTML
+  final el marcador de `STOREFRONT_CONTENT_LOCATOR.md`, con la key, nombre y
+  locale de la entrada fuente. El control es por entrada completa, no por campo.
+- Comparar inventario de entradas y regiones. Permitir marcadores repetidos si
+  una entrada aparece en varios lugares y marcadores anidados cuando una tarjeta
+  proviene de otra entrada referenciada. No exigirlos a código/i18n, catálogo,
+  `publicConfig` ni documentos legales.
 
 ## SEO y compartición
 

package/skills/bacano-web/references/forms.md

@@ -3,6 +3,19 @@
 Aplicar este contrato cuando el sitio muestre al menos un formulario administrado
 desde Bacano. Leer también `STOREFRONT_FORMS.md` completo desde el paquete SDK.
 
+## Creación asistida y sincronización
+
+Si falta el formulario, proponer su definición y pedir el acceso temporal de
+**Conectar agente** en Formularios o Content. Leer `CONTENT_TYPE_MANAGEMENT.md`.
+Usar `createContentManagementClient` con `forms:manage`; inventariar sitios,
+listas y formularios antes de crear. Editar mediante `updateForm()` enviando
+el documento completo y `expectedUpdatedAt`. Los conflictos exigen releer,
+no sobreescribir. Publicar o retirar requiere `forms:publish` y confirmación.
+No duplicar las definiciones en Content, GraphQL, SQL ni en fixtures permanentes.
+El storefront consume la key y versión publicada usando el SDK público.
+El acceso administrativo no permite leer respuestas ni PII. `CAPTURE_LEAD`
+ya resuelve la identidad; no ejecutar una segunda captura por campaña.
+
 ## Implementación oficial
 
 - Clasificar formularios como `ACTIVA`, `INACTIVA` o `BLOQUEADA` en la matriz de
@@ -23,12 +36,25 @@ desde Bacano. Leer también `STOREFRONT_FORMS.md` completo desde el paquete SDK.
 
 - Enviar mediante `client.forms.submitResponse()` o el envío interno de
   `BacanoForm`.
+- `honeypot` es un campo trampa, no un nonce, timestamp, UUID ni dato del
+  visitante. `BacanoForm` lo administra. En un renderer manual, omitirlo salvo
+  que exista un input trampa realmente oculto; para una persona siempre debe
+  permanecer vacío y el autocompletado no debe llenarlo.
+- `accepted: true` con `responseId: null` es una aceptación silenciosa antispam:
+  no demuestra que la respuesta fue guardada. La verificación funcional exige
+  un UUID y la respuesta visible una sola vez en Bacano.
+- Los datos de contacto deben conservar su semántica: usar campos `email` y
+  `phone`. Un campo `text` llamado correo o teléfono se guarda como texto libre
+  y no alimenta los datos de contacto normalizados para CRM o automatizaciones.
 - Conservar una `idempotencyKey` durante reintentos del mismo intento lógico.
 - Enviar la versión y `definitionHash` exactos de la definición renderizada.
 - Respetar estados `ACTIVE` y `PAUSED`; no renderizar borradores o archivados.
 - No escribir respuestas o PII en consola, analítica, URLs o logs del storefront.
-- No afirmar que se creó un lead, se envió un correo o se abrió una solicitud si
-  esa acción aún no está implementada y verificada en Bacano.
+- En `CAPTURE_LEAD`, Bacano conserva primero la respuesta y resuelve la identidad
+  internamente. No afirmar al visitante que se creó un lead o que ya era cliente:
+  la respuesta pública es genérica y no expone ese resultado.
+- No afirmar que se envió un correo, se entregó un cupón o se abrió una solicitud
+  si esa acción aún no está implementada y verificada en Bacano.
 - Una brecha del SDK se reporta; nunca se resuelve con GraphQL directo ni una API
   paralela del storefront.
 
@@ -41,6 +67,10 @@ desde Bacano. Leer también `STOREFRONT_FORMS.md` completo desde el paquete SDK.
 - Error de red: estado recuperable sin promesa falsa de recepción.
 - Persistencia: la respuesta aparece una sola vez en Bacano con versión, origen y
   snapshot correctos.
+- Autocompletado: completar datos con el navegador o un gestor de contraseñas no
+  llena el honeypot ni produce `responseId: null`.
+- Semántica: correo y teléfono usan `email` y `phone`; no se infieren por label o
+  key.
 - Accesibilidad: label asociado, foco, teclado, mensajes de error y progreso de
   pasos comprensibles.
 - Static First: el HTML exportado conserva el formulario cuando corresponde.

package/types.d.ts

@@ -224,11 +224,15 @@ export interface WebsiteFormResponseInput {
     idempotencyKey: string;
     values: Record<string, WebsiteFormResponseValue>;
     source?: WebsiteFormResponseSource;
-    /** Bot-trap field. Storefronts should render it visually hidden and leave it empty. */
+    /**
+     * Bot-trap field, not a token or nonce. Omit it unless a real hidden trap is
+     * rendered; legitimate visitors must always submit an empty value.
+     */
     honeypot?: string;
 }
 export interface WebsiteFormResponseResult {
     accepted: boolean;
+    /** A null value is not proof of persistence (for example, an anti-bot response). */
     responseId: string | null;
     message: string;
 }