Saltar al contenido
Elena Tech

Construye con Avileo

Tu tienda en internet, construida por tu agente.

Para dueños que quieren una web conectada a su negocio y para quienes la construyen para otros. Trabaja con un agente de código, el starter oficial y el SDK público; mantén el catálogo en Avileo y adapta la web a tu proyecto.

Seguir la guíaInstrucciones para tu agente

Para tiendas · Cambios administrativos con aprobación humana

Tu agente

Claude Code, Codex u otro compatible

Avileo

Catálogo y operación del negocio

Tu web

Código y despliegue a tu cargo

Agente ↔ Avileo
Skill + CLI, con una Agent Key secreta.
Web ↔ Avileo
SDK público, con una Client Key para el catálogo público.
Dos conexiones distintas. Ninguna clave secreta en la web.

Cómo funciona

Del negocio al código, en cuatro pasos.

Tú defines el proyecto. El agente ayuda con el código; Avileo mantiene los datos del negocio.

CLIAvileoABCD-2345

1 · Conecta

Instala la skill oficial y vincula la CLI con el negocio autorizado. Conserva la credencial secreta fuera del proyecto web y del chat.

2 · Aprueba

Para cambiar datos en Avileo o crear una Client Key, el agente propone y una persona autorizada revisa el diff y aprueba. Esto no aprueba los cambios al código de tu web.

3 · Construye

Parte del starter oficial con catálogo, carrito y envío de pedidos. Tú y tu agente adaptan identidad, contenido y diseño para el negocio.

4 · Verifica y publica

Prueba el catálogo y el envío de un pedido antes de desplegar. Elige y configura tu propio alojamiento y dominio; Avileo no hospeda esta web.

Del negocio a la web · guía de trabajo

Qué haces tú. Qué hace tu agente.

Para el dueño que quiere una web y para quien la implementa: sigue los pasos en orden, confirma el negocio y aprueba cada cambio administrativo. Esta página orienta; no crea cuentas, vincula agentes ni modifica datos.

Esta guía está preparada para Tienda en producción: https://tienda.theelena.me. Los enlaces y comandos ya usan esa URL.

0 de 10 pasos marcados por ti

Las marcas son solo una ayuda local: se reinician al salir o recargar. No verifican tu cuenta ni representan una autorización en Avileo.

  1. Responsable: Dueño del negocio

    Crea la cuenta y confirma el negocio Tienda

    Abre el registro de Avileo, crea tu cuenta y completa los datos del negocio como Tienda / comercio minorista. Si ya tienes cuenta, inicia sesión y confirma el negocio antes de continuar.

    La cuenta queda bajo control del dueño. Una agencia trabaja con un negocio y credenciales propios por cliente, no con una cuenta compartida que mezcle catálogos.

    Terminado cuando: Puedes entrar a tu negocio, su identidad es correcta y el rubro es Tienda / comercio minorista.

  2. Responsable: Dueño, con apoyo del implementador

    Prepara y habilita el catálogo del negocio

    En Productos, agrega o revisa los productos, sus variantes y precios; completa imágenes y stock según tu operación. No uses productos ficticios como si estuvieran a la venta.

    Abre Configuración → Página web y catálogo → Integraciones SDK y Agentes de catálogo. Verifica que el negocio tenga habilitados el catálogo público y el acceso para agentes. Si no aparecen estas opciones, pide revisar la habilitación del negocio; instalar una skill no concede esos permisos.

    Terminado cuando: El catálogo y el acceso para agentes están disponibles; hay productos reales con variantes, precios, imágenes y stock revisados.

  3. Responsable: Implementador o agencia

    Instala las dos skills en tu agente de código

    avileo-catalog administra el catálogo con aprobación. avileo-storefront construye la web pública. Instálalas en el host donde trabaja tu agente:

    Terminal · instalar las dos skillsBash
    npx skills add leobar37/elena-tech --skill avileo-catalog
npx skills add leobar37/elena-tech --skill avileo-storefront
    ¿No se pudo copiar? Seleccionar el texto manualmente

    El instalador detecta hosts compatibles, como Claude Code o Codex. Más opciones en la guía de skills. Entrega al agente el prompt completo de abajo, sin secretos.

    Terminado cuando: El host de tu agente reconoce ambas skills y tienes Node.js 20+, Git y Bun disponibles.

  4. Responsable: Implementador ejecuta; dueño autoriza

    Vincula al agente y elige sus permisos

    Ejecuta la CLI pública 0.3.4 para conectar con Tienda en producción:

    Terminal · solicitar vinculaciónBash
    npx --yes @tarileo/avileo-catalog-cli@0.3.4 auth login --base-url https://tienda.theelena.me --json
    ¿No se pudo copiar? Seleccionar el texto manualmente

    El dueño abre la URL de verificación que devuelve el comando, inicia sesión en Avileo y elige Solo lectura para inspeccionar, o Lectura y mutación para proponer cambios y crear la clave pública. No inventes una URL de autorización ni pegues claves en el chat.

    La CLI guarda la Agent Key secreta en el host de confianza. No va en la web ni en sus variables de entorno. El modo se puede revisar en Agentes de catálogo; consulta también la referencia CLI.

    Terminado cuando: El dueño aprobó la vinculación al negocio correcto y eligió los permisos necesarios.

  5. Responsable: Agente e implementador, con confirmación del dueño

    Conoce el negocio antes de diseñar

    Primero revisa la conexión, sin consultar todavía el negocio:

    Terminal · comprobar el origenBash
    npx --yes @tarileo/avileo-catalog-cli@0.3.4 auth status --json
    ¿No se pudo copiar? Seleccionar el texto manualmente

    Comprueba que baseUrl sea https://tienda.theelena.me. Si no coincide, conecta con ese origen antes de continuar, sin reutilizar la credencial de otro destino. Después identifica el negocio:

    Terminal · confirmar el negocioBash
    npx --yes @tarileo/avileo-catalog-cli@0.3.4 business show --json
    ¿No se pudo copiar? Seleccionar el texto manualmente

    Confirma que es el negocio esperado y que tienes permisos de lectura. Solo entonces consulta su perfil, una muestra de hasta 12 productos y las categorías, sin modificar datos:

    Terminal · conocer el perfil y el catálogoBash
    npx --yes @tarileo/avileo-catalog-cli@0.3.4 business profile show --json
npx --yes @tarileo/avileo-catalog-cli@0.3.4 catalog product list --limit 12 --offset 0 --json
npx --yes @tarileo/avileo-catalog-cli@0.3.4 catalog category list --json
    ¿No se pudo copiar? Seleccionar el texto manualmente

    Revisa status.completeness y status.missing del perfil, categorías, imágenes y variantes disponibles. Lee detalles adicionales solo si hacen falta. Si existe una web, usa la publicUrl del negocio o una URL confirmada por el dueño.

    Resume en cinco puntos: qué vende, a quién, qué lo diferencia, estilo e identidad visual, y contacto y entrega. Separa hechos observados de lo desconocido. Pregunta como máximo tres datos faltantes que cambien el sitio, usando la pregunta del campo devuelta por el perfil cuando corresponda; no pidas al dueño repetir lo que ya ofrece Avileo ni deduzcas condiciones por el rubro.

    Con ese contexto, propone las secciones y el diseño. El dueño aprueba la estructura y el alcance antes de construir.

    Terminado cuando: El agente leyó el perfil y una muestra del catálogo, presentó el contexto y resolvió los vacíos relevantes; el dueño aprobó la estructura y el alcance.

  6. Responsable: Agente propone; dueño aprueba; agente aplica

    Propón la Client Key, apruébala y créala

    Si aún no hay una Client Key pública autorizada y disponible para esta web, propone crearla. Este comando crea una propuesta, todavía no crea la clave:

    Terminal · proponer la clave públicaBash
    npx --yes @tarileo/avileo-catalog-cli@0.3.4 catalog-key create --name "Web del negocio" --json
    ¿No se pudo copiar? Seleccionar el texto manualmente

    Conserva el JSON completo. El agente entrega al dueño el resumen, el ID real y la URL literal de .data.approvalUrl. El dueño abre esa URL exacta y aprueba la operación en Avileo. Nunca reconstruyas el enlace desde el ID ni cambies su origen.

    Terminal · aplicar solo la propuesta aprobadaBash
    # Reemplaza el marcador por el ID real de la propuesta aprobada.
APPROVAL_ID="REEMPLAZAR_POR_ID_REAL_APROBADO"
npx --yes @tarileo/avileo-catalog-cli@0.3.4 operation status "$APPROVAL_ID" --json
# Ejecuta la siguiente línea solo después de la aprobación humana.
npx --yes @tarileo/avileo-catalog-cli@0.3.4 operation apply "$APPROVAL_ID" --json
    ¿No se pudo copiar? Seleccionar el texto manualmente

    REEMPLAZAR_POR_ID_REAL_APROBADO es un marcador, no un ID válido: reemplázalo por el que devolvió esa propuesta. La respuesta exitosa de apply entrega una sola vez la nueva clave con prefijo avileo_pk_. Guárdala para configurar la web; no publiques la respuesta en el chat. Contrato de Client Keys.

    Terminado cuando: La operación aprobada terminó correctamente y guardaste la Client Key pública devuelta una sola vez.

  7. Responsable: Implementador o agencia

    Copia el starter público y configura el entorno

    Parte del starter público avileo-storefront. Usa una carpeta nueva para no sobrescribir otro proyecto:

    Terminal · copiar e instalar el starterBash
    git clone --depth 1 https://github.com/leobar37/elena-tech.git
cp -r elena-tech/starters/avileo-storefront mi-negocio-web
cd mi-negocio-web
bun install
cp .env.example .env
    ¿No se pudo copiar? Seleccionar el texto manualmente

    Edita .env en mi-negocio-web. Sustituye el marcador por la clave real obtenida en el paso anterior; el ejemplo no contiene una credencial utilizable.

    .env · únicamente configuración pública.env
    VITE_AVILEO_API_URL=https://tienda.theelena.me
# Sustituye el marcador completo por la Client Key pública recién creada.
VITE_AVILEO_CLIENT_KEY=REEMPLAZAR_POR_CLIENT_KEY_PUBLICA
# Activa el asistente solo si forma parte del alcance acordado.
VITE_AVILEO_ASSISTANT=false
    ¿No se pudo copiar? Seleccionar el texto manualmente
    Terminal · iniciar la web localBash
    bun run dev
    ¿No se pudo copiar? Seleccionar el texto manualmente

    Abre la URL local que imprime el servidor. El starter ya instala @tarileo/avileo-sdk@0.3.0. El SDK se instala y configura; lo que se crea es la clave pública. Nunca pongas una Agent Key avileo_sk_ ni una clave de sistema sak_ en este proyecto.

    Terminado cuando: La web local consulta el negocio correcto usando solo su Client Key pública.

  8. Responsable: Implementador, con contenido aprobado por el dueño

    Personaliza la web sin duplicar el catálogo

    Edita src/lib/site-config.ts para nombre, descripción, contacto y redes; src/styles/theme.css para colores y tipografía. Acuerda imágenes y textos con el dueño. Mantén productos, variantes, precios y stock en Avileo, no en listas copiadas al código.

    Empieza por perfil y catálogo. Conserva carrito y checkout solo según el alcance acordado; habilita el asistente solo si se solicita. Confirmar un pedido no equivale a cobrarlo en línea. Consulta los ejemplos del SDK y el mapa de personalización del starter.

    Terminado cuando: Identidad, contacto y diseño corresponden al negocio; el catálogo sigue viniendo de Avileo.

  9. Responsable: Implementador prueba; dueño revisa el resultado

    Valida en móvil, escritorio y build de producción

    Revisa el negocio correcto, imágenes, variantes/precios, catálogo vacío, carga y errores. Comprueba que no haya desbordes en móvil y que se pueda navegar con teclado. Si incluyes carrito o checkout, verifica cantidades y el resultado del pedido. Antes de crear un pedido real de prueba, acuerda con el dueño cómo identificarlo y gestionarlo.

    Terminal · validar y previsualizar el buildBash
    bun run test
bun run typecheck
bun run build
bun run preview
    ¿No se pudo copiar? Seleccionar el texto manualmente

    Abre la URL de preview que imprime el comando. No declares listo un flujo no probado. Consulta la guía de errores si la API rechaza el acceso; no lo resuelvas cambiando de negocio o de origen.

    Terminado cuando: Pruebas, typecheck y build pasan; el dueño revisó la web y los flujos acordados con evidencia.

  10. Responsable: Implementador despliega; dueño autoriza y recibe

    Despliega en el proveedor del cliente y entrega el control

    Acuerda proveedor, dominio, costos y acceso con el dueño. Adapta el despliegue de TanStack Start a su proveedor, configura las variables públicas en el entorno de build y verifica la URL publicada. Lee las instrucciones de despliegue del starter: no incluyen una cuenta de hosting ni credenciales de publicación.

    Entrega repositorio, URL, variables públicas, instrucciones para actualizar productos en Avileo y reconstruir la web, y evidencia de los flujos probados. Cada cliente conserva su cuenta, negocio y claves; nunca se comparte un secreto entre negocios. Revisa y revoca accesos de agente innecesarios desde Avileo. El dueño debe poder continuar sin depender de la cuenta personal de la agencia.

    Terminado cuando: Hay un deploy autorizado verificado y el dueño tiene código, accesos, instrucciones y resultados de validación.

Un encargo completo, sin secretos

Copia esto en tu agente de código.

Compártelo con Claude Code, Codex u otro host compatible. El agente conocerá tu negocio antes de proponer el diseño y te preguntará solo por lo que falta. No pegues claves secretas ni contraseñas junto a él.

Prompt completo · dueño + implementador + agenteTexto
Quiero una web para mi negocio Tienda en Avileo. Conoce el negocio antes de diseñar.

Lee estas skills; instálalas si faltan:
https://raw.githubusercontent.com/leobar37/elena-tech/main/skills/avileo-catalog/SKILL.md
https://raw.githubusercontent.com/leobar37/elena-tech/main/skills/avileo-storefront/SKILL.md
npx skills add leobar37/elena-tech --skill avileo-catalog
npx skills add leobar37/elena-tech --skill avileo-storefront

Usa Tienda producción: https://tienda.theelena.me. Conecta si hace falta:
npx --yes @tarileo/avileo-catalog-cli@0.3.4 auth login --base-url https://tienda.theelena.me --json
Yo autorizaré en la URL devuelta: Solo lectura para conocer el negocio; Lectura y mutación para proponer cambios. Conserva secretos únicamente en la CLI, nunca en chat, código ni variables públicas.

Primero:
npx --yes @tarileo/avileo-catalog-cli@0.3.4 auth status --json
Comprueba baseUrl=https://tienda.theelena.me. Si no coincide, detente y conecta correctamente sin reutilizar credenciales de otro destino. Después:
npx --yes @tarileo/avileo-catalog-cli@0.3.4 business show --json
Verifica mi negocio y permisos de lectura; aclara cualquier duda de identidad antes de continuar.

Lee sin modificar:
npx --yes @tarileo/avileo-catalog-cli@0.3.4 business profile show --json
npx --yes @tarileo/avileo-catalog-cli@0.3.4 catalog product list --limit 12 --offset 0 --json
npx --yes @tarileo/avileo-catalog-cli@0.3.4 catalog category list --json
Revisa status.completeness, status.missing y valores del perfil; categorías, imágenes y variantes de la muestra. Consulta detalles solo si hacen falta. Revisa una web existente únicamente desde publicUrl o una URL que yo confirme.

Resume el contexto en cinco puntos:
• Qué vendo.
• A quién.
• Qué me diferencia.
• Estilo e identidad visual.
• Contacto y entrega.
Separa hechos observados de desconocidos, sin inferir audiencia, diferenciación ni entrega por el rubro. Pregunta como máximo tres datos faltantes relevantes, usando field.question cuando corresponda. No me hagas repetir información de Avileo.

Propón estructura, secciones y dirección visual basadas en ese contexto. Espera mi aprobación del alcance antes de construir.

Si falta una Client Key pública disponible:
npx --yes @tarileo/avileo-catalog-cli@0.3.4 catalog-key create --name "Web del negocio" --json
Muéstrame el resumen y la URL literal .data.approvalUrl. Tras mi aprobación en Avileo, aplica el ID real con npx --yes @tarileo/avileo-catalog-cli@0.3.4 operation apply ID_REAL_APROBADO --json. Otros cambios de datos también requieren propuesta y aprobación.

Parte de https://github.com/leobar37/elena-tech/tree/main/starters/avileo-storefront con @tarileo/avileo-sdk@0.3.0. Configura VITE_AVILEO_API_URL=https://tienda.theelena.me y VITE_AVILEO_CLIENT_KEY con la clave pública avileo_pk_ real. Personaliza src/lib/site-config.ts y src/styles/theme.css; conserva el catálogo conectado. Carrito, checkout y asistente solo si los acordamos.

Prueba móvil, escritorio, imágenes, variantes/precios, carga, errores y catálogo vacío; pide permiso para pedidos reales de prueba. Ejecuta bun run test, bun run typecheck, bun run build y bun run preview. Reporta resultados reales.

Acuerda conmigo proveedor, dominio, accesos y costos antes de publicar. Entrega código, URL verificada, instrucciones de actualización y evidencia de validación. Revisemos los accesos del agente al terminar.
¿No se pudo copiar? Seleccionar el texto manualmente

Fuentes legibles por agentes: contexto de administración y contexto del SDK público. Para personas, la guía de integración explica la separación de permisos.

SDK público · versión 0.3.0

La clave se crea. El SDK se instala.

El starter ya incluye estas dependencias. Si integras una aplicación React existente, instálalas y configura las variables públicas del paso 7. La API identifica el negocio por su Client Key: no pases un businessId ni una Agent Key.

Terminal · solo para una app existenteBash
npm install @tarileo/avileo-sdk@0.3.0 @tanstack/react-query
¿No se pudo copiar? Seleccionar el texto manualmente

JavaScript / TypeScript

Un cliente compartido para loaders o helpers. El perfil y el catálogo pertenecen al negocio de la clave configurada.

SDK Core · perfil y catálogoTypeScript
import { createAvileo } from '@tarileo/avileo-sdk';

// Un cliente compartido; las variables vienen de tu .env configurado.
export const avileo = createAvileo({
  baseUrl: import.meta.env.VITE_AVILEO_API_URL,
  clientKey: import.meta.env.VITE_AVILEO_CLIENT_KEY,
});

export async function loadCatalog() {
  const business = await avileo.currentBusiness.getInfo();
  const catalog = await avileo.currentBusiness.catalog.list();
  return { business, catalog };
}
¿No se pudo copiar? Seleccionar el texto manualmente

React: provider y hooks

Monta un provider en la raíz. Este ejemplo mínimo crea un QueryClient estable; en el starter reutiliza el que ya existe. Los precios pertenecen a las variantes del producto.

React · catálogo con carga, error y vacíoTSX
import { useState } from 'react';
import { QueryClient } from '@tanstack/react-query';
import {
  AvileoProvider,
  useBusiness,
  useCatalog,
} from '@tarileo/avileo-sdk/react';

export function App() {
  const [queryClient] = useState(() => new QueryClient());
  return (
    <AvileoProvider
      baseUrl={import.meta.env.VITE_AVILEO_API_URL}
      clientKey={import.meta.env.VITE_AVILEO_CLIENT_KEY}
      queryClient={queryClient}
      presence={false}
    >
      <Catalog />
    </AvileoProvider>
  );
}

function Catalog() {
  const business = useBusiness();
  const catalog = useCatalog();

  if (business.isError || catalog.isError) {
    return <p role="alert">No se pudo cargar el catálogo.</p>;
  }
  if (business.isPending || catalog.isPending) {
    return <p role="status">Cargando catálogo…</p>;
  }

  return (
    <section>
      <h1>{business.data.name}</h1>
      {catalog.data.products.length === 0 ? (
        <p>Aún no hay productos publicados.</p>
      ) : (
        <ul>
          {catalog.data.products.map((product) => (
            <li key={product.id}>
              <h2>{product.name}</h2>
              <ul>
                {product.variants.map((variant) => (
                  <li key={variant.id}>
                    {variant.name}: S/ {variant.price}
                  </li>
                ))}
              </ul>
            </li>
          ))}
        </ul>
      )}
    </section>
  );
}
¿No se pudo copiar? Seleccionar el texto manualmente

useCatalog() devuelve categorías y productos; acepta filtros opcionales search, categoryId y tag. Los hooks usan TanStack Query. Más detalle: SDK Core, React y ejemplos.

  1. 1. El agente consulta

    Lee los datos permitidos. Las consultas no requieren aprobación.

  2. 2. Propone cambios en Avileo

    Con permiso de mutación, prepara una propuesta con el detalle de los cambios.

  3. 3. Una persona autoriza

    Revisa y aprueba en Avileo. El agente aplica exactamente la propuesta autorizada.

La aprobación protege los cambios administrativos en Avileo, no el código de la web.

Control total

Tu agente trabaja con permisos.

Una credencial secreta identifica a tu agente ante tu negocio — nunca entra en la web, el navegador ni el chat. Con los permisos correspondientes, puede leer datos y proponer cambios administrativos que una persona autorizada revisa y aprueba en Avileo. La web usa una Client Key pública, limitada al catálogo público y sus operaciones permitidas: no da acceso administrativo al negocio.

  • Claves separadas: agente (secreta), web (pública), nada compartido.
  • Puedes revocar al agente en cualquier momento desde Avileo.
  • El deploy y el dominio son tuyos; Avileo no hospeda tu web.

Sobre bases reales

Las herramientas para construir.

Skill oficial

Instalable desde el repositorio público de Elena Tech para Claude Code, Codex y hosts compatibles.

CLI verificada

@tarileo/avileo-catalog-cli publicada en npm, con selección de origen y vinculación por aprobación.

Starter público

Un proyecto de partida con catálogo, carrito, envío de pedidos y asistente opcional. Adáptalo a tu negocio.

Empieza por los requisitos, conecta el negocio y prueba el flujo antes de publicar.

Ir a la guíaDocumentación de agentesVer el starter