Un proyecto Velk es una carpeta. Saber qué vive dónde te dice qué está cambiando la IA cuando le pides algo, y qué partes nadie debería tocar. La versión corta: la estructura es un archivo, el contenido es la base de datos, el aspecto es PHP.
Qué hay en la carpeta
| Carpeta o archivo | Qué guarda |
|---|---|
theme/ | Tu sitio: site.json (la estructura), templates/ (el HTML de cada tipo de página, en PHP), partials/ (piezas que se reutilizan, como la cabecera y el pie), functions.php (el código propio del tema, como un webhook o el texto de los mensajes) y el CSS. |
core/ | El motor. Se reemplaza entero en cada actualización. |
bin/, config/, index.php | También son el motor: la herramienta de comandos bin/velk, el código que lee el .env y la puerta de entrada por la que pasa cada visita. |
storage/ | Medios subidos, archivos enviados por formularios, caché y registros. |
.env | Contraseñas y claves de esta copia: base de datos, correo, pagos. Tu computadora y el servidor tienen cada uno el suyo. |
migrations/ | Los cambios de base de datos que trae cada versión. Se ejecutan una vez y se eliminan; no te extrañe si la carpeta desaparece. |
.htaccess, robots.txt | Las copias del proyecto de los ejemplos del motor. Son tuyas para ajustar; las actualizaciones no las tocan. |
.velk-version | Qué versión del motor está instalada. |
.deploy/ | Se crea al publicar por primera vez o al conectar un sitio: cómo llegar al servidor. Se queda en tu computadora. |
AGENTS.md, README.md, CHANGELOG.md, docs/ | La documentación del motor, incluida la referencia que leen los agentes de IA. |
Estructura, contenido y aspecto
- La estructura es un archivo.
theme/site.jsondeclara lo que el sitio puede guardar: qué páginas, qué tipos de contenido, qué campos tiene cada uno. El panel nace de él: cambias el archivo y cambia el panel. - El contenido es la base de datos. Textos, entradas, imágenes registradas, envíos de formularios y usuarios viven en MySQL. Es lo que edita el cliente, y por eso copiar
theme/a otro proyecto se lleva la estructura y el aspecto, pero nada del contenido. - El aspecto es PHP. Las plantillas son archivos PHP con HTML, más el CSS del tema. Sin lenguaje de plantillas, sin constructor visual.
La regla de oro: nunca edites el motor
El motor es todo lo que entrega Velk: core/, config/, bin/, migrations/, index.php, los archivos .example y los documentos del motor. Una actualización reemplaza esas rutas enteras. Una edición ahí desaparece en la siguiente actualización, sin aviso, y mientras tanto tu copia queda distinta de la del servidor sin que nadie lo note.
Todo lo que un sitio necesita va en theme/. Cuando al motor le falta algo, es un pedido para Velk, no un parche local. La skill sigue esta regla y, antes del primer despliegue, compara el motor con la versión oficial y se niega a publicar uno editado.
Pídele a la IA
Explícame las carpetas de este proyecto con palabras simples: qué guarda cada una, qué cambio pidiéndotelo a ti y qué no debería editar nadie.
Un buen primer pedido en un proyecto que no construiste, o en uno al que vuelves después de un tiempo.
Pídele a la IA
Revisa si el motor de este proyecto es igual a la versión oficial de Velk, archivo por archivo.
La IA ejecuta la revisión del motor de la skill. Responde que el motor está intacto o lista cada archivo modificado, añadido o que falta.
Lo que cambias pidiendo
| Pides | Qué cambia |
|---|---|
| Un campo, página, tipo de contenido o formulario | theme/site.json y luego la plantilla que lo muestra. El panel se actualiza solo. |
| Un aspecto distinto | Las plantillas y el CSS del tema. |
| Una entrada, un texto nuevo, una foto | Ningún archivo: eso es contenido, se hace en el panel, o lo hace la IA en un sitio publicado. |
| Un ajuste de esta copia, como el idioma del panel | El .env. |
| Una versión nueva de Velk | Las rutas del motor, con el flujo de actualización. Nunca a mano. |
Opcional: historial con Git
Git guarda el historial de un proyecto: cada hito que grabas registra el estado completo de los archivos, así puedes ver qué cambió entre dos días y volver atrás cuando algo se rompe. En Velk vale la pena porque la estructura es un archivo de texto: el campo que alguien añadió el martes aparece en el historial y se puede deshacer.
El motor se instala desde una versión publicada, no desde Git, y la instalación elimina el .gitignore del propio motor (la lista de lo que Git ignora). La lista del proyecto la escribes tú, y es en ella donde los secretos y los archivos subidos quedan fuera del historial.
Pídele a la IA
Empieza a versionar este proyecto con Git. Deja fuera el .env, la carpeta .deploy y storage, y graba un primer hito llamado “estructura del sitio”.
Desde entonces, una frase graba cada hito: “Graba un hito: añadí el formulario de contacto.”