mindxassociates/practice-website-kit

Practice Website Kit — Astro + PagesCMS + Cloudflare Pages

El stack, y por qué

Capa	Elección	Por qué
Framework del sitio	Astro	Genera HTML estático con casi cero JavaScript por defecto: rápido en móviles, sin parches que aplicar, contenido en Markdown con frontmatter tipado.
Edición de contenido	PagesCMS (app.pagescms.org)	Gratuito, de código abierto, basado en Git: el personal edita mediante formularios web; cada guardado es un commit de Git. Sin base de datos, sin servidor CMS que mantener.
Alojamiento	Cloudflare Pages	El nivel gratuito se ajusta cómodamente a un sitio de práctica (minutos de compilación y ancho de banda generosos, muchos dominios personalizados), sin marca, uso comercial permitido, CDN global, HTTPS automático. Desplegar = conectar el repositorio Git.
Repositorio	GitHub (propiedad de la práctica)	El hogar único del sitio: Astro lo lee, PagesCMS escribe en él, Cloudflare compila desde él.

La regla de arquitectura que hace que esto funcione: el sitio web es una publicación, no una aplicación. Las páginas, perfiles y publicaciones son contenido. Las reservas, pagos, mensajería y directorios ya tienen sistemas — el sitio los incrusta y enlaza; nunca los reimplementa ni recibe sus datos.

Instrucciones para el agente

• Entregable = un repositorio funcional que la práctica posea + las tres conexiones realizadas (PagesCMS → repositorio, Cloudflare Pages → repositorio + dominio) + una edición verificada de principio a fin a través del CMS. Si no tienes acceso a las cuentas, produce el repositorio completo y una lista de verificación de conexión paso a paso para el propietario.
• Realiza primero la entrevista de configuración. Nunca inventes datos de la práctica — credenciales, licencias, paneles de seguros, tarifas, idiomas, años de experiencia. Marcadores de posición, señalizados, hasta que el propietario los proporcione.
• Verifica cada comportamiento de la plataforma desde la configuración real, no de memoria: la regla filename-template de PagesCMS en references/pagescms-config.md le costó a un sitio real su primer guardado — trata la prueba de guardado del CMS como la definición de "configurado".

Entrevista de configuración (preguntar una vez, antes de construir)

1. Identidad de la práctica — nombre de la práctica, dominio (y dónde vive el DNS — el alojamiento en Cloudflare es más fluido cuando el DNS también está en Cloudflare), logotipo/colores si los hay, teléfono/correo electrónico a mostrar.
2. Forma — individual o grupal; lista de proveedores (nombres, credenciales, estados de licencia, disponibilidad de foto) para páginas de perfil.
3. Páginas — confirmar el plano en references/site-blueprint.md (agregar/eliminar: por ejemplo, ¿una página dedicada por servicio? ¿una sección de recursos/blog? ¿un directorio de referencias incrustado?).
4. Idiomas — un idioma, o un árbol reflejado (por ejemplo, inglés en /, chino en /zh/)? Reflejado significa páginas traducidas con calidad humana y sus propios slugs — presupuesta la traducción; nunca traduzcas contenido clínico con máquina y lo publiques sin leer.
5. Incrustaciones dinámicas — qué sistemas existentes aparecen en el sitio (página de reservas, aplicación de formulario de contacto, directorio de referencias, punto de entrada de mensajes seguros) y sus URLs. Estos se convierten en incrustaciones iframe + enlaces de respaldo.
6. Editores — quién actualiza el contenido después del lanzamiento (¿solo el propietario? ¿un administrador? ¿proveedores que escriben publicaciones?) — esto decide el acceso a PagesCMS y cuánto del sitio es gestionado por el CMS vs. gestionado por código.
7. Activos existentes — contenido actual del sitio a migrar, fotos (y sus derechos), Perfil de Negocio de Google y listados de directorios con los que el sitio debe mantenerse consistente.

Reglas estrictas

1. La práctica posee todas las cuentas — registrador de dominio, GitHub, Cloudflare. Configúralas con los inicios de sesión de la práctica, con opciones de recuperación que la práctica controle.
2. El contenido es dato, no código. Cualquier cosa que un editor pueda cambiar (biografías de proveedores, servicios, tarifas, preguntas frecuentes, publicaciones) vive en Markdown/frontmatter detrás de un esquema de contenido — nunca codificado en plantillas .astro.
3. Las plantillas de nombre de archivo de PagesCMS usan {fields.slug} (o la ruta de campo real de la colección). Un {slug} simple no es válido y hace que cada guardado del CMS falle con un error opaco. Después de corregir la configuración, recarga el CMS — almacena en caché la configuración por sesión.
4. El sitio no recopila nada clínico. Sin cuadros de texto de síntomas, sin formularios "dinos qué está pasando". Contacto = enlace/incrustación de reserva, teléfono y una aplicación de formularios enrutada si es necesario — más la línea de crisis (988 en EE. UU., y 911 para emergencias) en la página de contacto y cualquier página que invite al contacto, en los idiomas del sitio.
5. Las incrustaciones tienen enlaces de respaldo. Cada iframe (reserva, directorio) se empareja con un enlace simple al mismo sistema, para que un marco bloqueado nunca deje a un cliente sin salida.
6. Disciplina de afirmaciones: los paneles, tarifas, credenciales y disponibilidad en el sitio deben coincidir con la fuente de verdad de la práctica (su lista/registros). El sitio web es el último lugar donde se debería editar un dato — si un número vive en dos lugares, nombra cuál gana.
7. El rendimiento es una característica en un sitio de terapia — la gente llega ansiosa, en teléfonos, desde un perfil de directorio. Comprime las imágenes antes de que entren al repositorio; una foto hero de 2 MB es un error, no un activo.

Orden de construcción

1. Repositorio + andamio de Astro + modelo de contenido según references/astro-setup.md, páginas según references/site-blueprint.md.
2. Compilación local verde; marcadores de posición de contenido señalizados y listados para el propietario.
3. Configuración de PagesCMS + la prueba de guardado real según references/pagescms-config.md.
4. Conexión de Cloudflare Pages + dominio personalizado según references/cloudflare-pages-deploy.md.
5. Revisión de SEO/rendimiento según references/seo-and-performance.md.
6. Entrega según references/maintenance-and-handoff.md; verificar según references/test-checklist.md.

Archivos de referencia

• references/architecture-and-stack.md — las tres capas, flujo de datos, qué significa estático para una práctica
• references/site-blueprint.md — las páginas, qué debe contener cada una, obligaciones específicas de terapia
• references/astro-setup.md — estructura del proyecto, colecciones de contenido + esquema, árbol multilingüe
• references/pagescms-config.md — .pages.yml, colecciones, medios, la regla filename-template
• references/cloudflare-pages-deploy.md — configuración del proyecto, ajustes de compilación, dominio personalizado, vistas previas
• references/seo-and-performance.md — metadatos, datos estructurados, sitemap/RSS, llms.txt, imágenes
• references/maintenance-and-handoff.md — flujo de trabajo de edición, actualizaciones, copias de seguridad, quién posee qué
• references/test-checklist.md — pruebas de aceptación, la prueba de guardado del CMS primero