Hazlo tuyo

Vas a seguir mergeando versiones nuevas de Weblabor Base a tu proyecto mientras éste viva. Cada archivo que editan los dos es un conflicto que resuelves otra vez en cada merge, así que la base se queda con lo compartido y te da carpetas propias para lo tuyo. Esta guía dice cuáles son esas carpetas, qué va en cada una y cómo traer la siguiente versión de la base sin perder una línea de tu producto.

La regla detrás de todo: lo que es de tu producto vive en una carpeta con el nombre de tu producto. Un archivo que la base trae es un archivo que la base va a cambiar.

Nombra tu proyecto una vez

config/app.php tiene una clave project:

'project' => 'weblabor-base',

Cámbiala a un slug corto de tu producto, tu-proyecto en el resto de esta guía. Es un literal committeado, no una variable de entorno, a propósito: se define una vez, cuando arranca tu proyecto, y config/ es tuyo, así que sobrevive cada merge.

La aplicación lee tres lugares a partir de ese nombre:

Nada de esas carpetas se hereda. Tu proyecto muestra las páginas y guías que escribiste, o ninguna. Las carpetas propias de la base, landing/weblabor-base/ y docs/weblabor-base/, se quedan en el repositorio intactas y sin usarse, así que un merge que las cambie no cambia nada de lo que publicas.

Tu página de inicio

La página de inicio en / renderiza resources/views/landing/tu-proyecto/home.blade.php dentro del layout público. Mientras ese archivo no exista, la página de inicio responde con un error que nombra el archivo que hay que crear, en lugar de una pantalla vacía. La página de inicio de la base está en resources/views/landing/weblabor-base/home.blade.php; cópiala como punto de partida y luego reescríbela.

El menú público muestra dos enlaces fijos, Características y Ayuda, y después lo que imprima resources/views/landing/tu-proyecto/nav-links.blade.php. El archivo es opcional. Pon ahí las anclas y páginas que tu landing sí tiene, para que el menú nunca apunte a una sección que no existe:

<a class="text-default-500 hover:text-default-900 transition-colors" href="#about">
    {{ __('About') }}
</a>

Las imágenes de la landing van en public/images/landing/tu-proyecto/. El layout, el encabezado y el pie vienen de resources/views/layouts/web.blade.php, que es un archivo compartido: cámbialo y espera resolverlo otra vez en el siguiente merge.

Tus páginas de características

/features lista lo que vende tu producto, una página por característica. La lista es resources/views/landing/tu-proyecto/features.php, un arreglo de entradas:

return [
    [
        'slug' => 'your-account',
        'title' => 'Your account',
        'summary' => 'Keep your details and your preferences the way you want them.',
        'icon' => 'user-circle',
        'order' => 20,
    ],
];

Cada entrada es una declaración: su página es la vista Blade con el nombre de su slug, resources/views/landing/tu-proyecto/features/your-account.blade.php, y una entrada cuya vista nunca se escribió queda fuera del listado. Las páginas se construyen con tres componentes, <x-landing.hero>, <x-landing.block> y <x-landing.cta>, y sus capturas viven en public/images/landing/tu-proyecto/features/{slug}/.

Escríbelas como páginas de venta, no como documentación: empieza por lo que la persona obtiene, una o dos frases cada una, en segunda persona y en presente. Las claves del manifiesto, los componentes y sus atributos están en Escribe guías y el changelog.

Tus guías y tu changelog

El centro de ayuda en /help lee Markdown de tu propia carpeta:

docs/tu-proyecto/help/
├── guides/
│   ├── get-it-running.md
│   └── es/
│       └── get-it-running.md
└── changelog/
    ├── 2026-09.md
    └── es/
        └── 2026-09.md

Una guía es un archivo por slug, en inglés, con un front matter de title, summary, category y order. Su traducción es el mismo nombre de archivo dentro de una carpeta con el nombre del idioma, una carpeta por cada idioma de config/app.php que no sea inglés. Una guía sin traducción se muestra en inglés con un aviso que lo dice. El changelog es un archivo por mes.

Las categorías que una guía puede declarar están en config/help.php, con sus etiquetas en inglés. Una categoría que ninguna guía usa se oculta, así que reemplaza la lista con las categorías que tu lector necesita y nada se muestra vacío.

Las traducciones llevan una huella del inglés con el que se escribieron, para poder nombrar una guía cuyo inglés siguió adelante. Dos comandos la mantienen:

php artisan help:stamp --check   # lista traducciones faltantes, desactualizadas y huérfanas
php artisan help:stamp           # reescribe la huella en cada traducción

composer install apunta Git a scripts/git-hooks, cuyo hook pre-push corre la revisión y detiene un push que publicaría un documento de ayuda desactualizado. Sáltalo una vez con git push --no-verify. Los formatos de archivo, las entradas del changelog y cómo se renderizan las páginas están en Escribe guías y el changelog.

Tu brief

docs/tu-proyecto/landing/product.md dice qué es tu producto, qué promete, a quién le habla, el tono y qué nunca afirma. No se renderiza en ningún lado: es lo que mantiene consistentes el copy de la landing, las páginas de características y las guías cuando las escriben varias personas. Escríbelo antes del copy, no después. El brief de la base está en docs/weblabor-base/landing/product.md y es una buena plantilla.

Qué más es tuyo

config/ pertenece al proyecto derivado. Ahí defines los superadministradores, el logotipo y el icono, los idiomas, las banderas, las categorías de ayuda y el manifiesto de la PWA, y un merge de la base nunca necesita sobrescribirlos. Cuando la base agrega una clave nueva a un archivo de configuración la verás como un conflicto en ese archivo: conserva tus valores y toma la clave nueva.

Los archivos detrás de la marca, public/images/logo.svg, public/images/icon.svg y la carpeta generada public/images/icons/, son tuyos para reemplazarlos. .env nunca se committea. Tus migraciones, modelos, componentes Livewire y vistas son archivos nuevos que se mergean limpio mientras agregues en lugar de editar.

Dos cosas son compartidas y vale la pena saberlo. lang/en.json y lang/es.json guardan juntas todas las cadenas en pantalla de la base y de tu producto, así que los dos lados agregan líneas en cada merge; cuando entren en conflicto, conserva ambos lados. Y los layouts en resources/views/layouts/ son de la base: el layout público, por ejemplo, imprime un bloque "Desarrollado por Weblabor" arriba del pie. Editarlos está permitido, pero cada edición es un conflicto que vas a volver a encontrar.

Sigue mergeando la base

Tu repositorio empieza como una copia de Weblabor Base. Agrega la base como segundo remoto y mergea su rama principal cada vez que salga una versión que quieras:

git remote add upstream https://gitlab.weblabor.mx/weblabormx/proyectos-internos/sistemas-base/weblabor-base.git
git fetch upstream
git merge upstream/master

Después del merge, actualiza lo que una versión cambia:

composer install
npm ci && npm run build
php artisan migrate
php artisan db:seed

Los seeders son seguros de volver a correr: crean lo que falta y vuelven a sincronizar el rol de administrador con todos los permisos, y nunca sobrescriben una contraseña.

Conflictos que debes esperar, y cómo cerrarlos:

Todo lo que está en resources/views/landing/tu-proyecto/, docs/tu-proyecto/ y config/ nunca entra en conflicto, porque la base no lo toca. Mientras más de tu producto viva ahí, más corto es cada merge.