mindxassociates/practice-website-kit

Practice Website Kit — Astro + PagesCMS + Cloudflare Pages

A stack, e por quê

Camada	Escolha	Por quê
Framework do site	Astro	Entrega HTML estático com quase zero JavaScript por padrão — rápido em celulares, nada para corrigir, conteúdo em Markdown com frontmatter tipado.
Edição de conteúdo	PagesCMS (app.pagescms.org)	Gratuito, código aberto, baseado em Git: a equipe edita em formulários web; cada salvamento é um commit Git. Sem banco de dados, sem servidor CMS para manter.
Hospedagem	Cloudflare Pages	O nível gratuito atende confortavelmente um site de consultório (minutos de build e largura de banda generosos, muitos domínios personalizados), sem marca d'água, uso comercial permitido, CDN global, HTTPS automático. Implantar = conectar o repositório Git.
Repositório	GitHub (de propriedade do consultório)	A única casa do site: Astro o lê, PagesCMS escreve nele, Cloudflare compila a partir dele.

A regra arquitetural que faz isso funcionar: o site é uma publicação, não uma aplicação. Páginas, perfis e posts são conteúdo. Agendamentos, pagamentos, mensagens e diretórios já têm seus sistemas — o site os incorpora e linka; nunca os reimplementa e nunca recebe seus dados.

Instruções para o agente

• Entregável = um repositório funcional de propriedade do consultório + as três conexões feitas (PagesCMS → repositório, Cloudflare Pages → repositório + domínio) + uma edição ponta a ponta verificada através do CMS. Se você não tiver acesso às contas, produza o repositório completo e uma lista de verificação passo a passo para o proprietário.
• Execute a entrevista de configuração primeiro. Nunca invente fatos do consultório — credenciais, licenças, convênios, honorários, idiomas, anos de prática. Placeholders, sinalizados, até o proprietário fornecê-los.
• Verifique cada comportamento da plataforma a partir da configuração real, não da memória: a regra de template de nome de arquivo do PagesCMS em references/pagescms-config.md custou o primeiro salvamento de um site real — trate o teste de salvamento do CMS como a definição de "configurado".

Entrevista de configuração (pergunte uma vez, antes de construir)

1. Identidade do consultório — nome do consultório, domínio (e onde o DNS reside — a hospedagem Cloudflare é mais suave quando o DNS também está na Cloudflare), logotipo/cores se houver, telefone/e-mail para exibir.
2. Formato — solo ou grupo; lista de profissionais (nomes, credenciais, estados de licença, disponibilidade de foto) para páginas de perfil.
3. Páginas — confirme o blueprint em references/site-blueprint.md (adicione/remova: por exemplo, uma página dedicada por serviço? uma seção de recursos/blog? um diretório de encaminhamento incorporado?).
4. Idiomas — um idioma, ou uma árvore espelhada (por exemplo, Inglês em /, Chinês em /zh/)? Espelhada significa páginas traduzidas com qualidade humana e seus próprios slugs — orçamento para a tradução; nunca traduza mecanicamente conteúdo clínico e o publique sem revisão.
5. Incorporações dinâmicas — quais sistemas existentes aparecem no site (página de agendamento, aplicativo de formulário de contato, diretório de encaminhamento, ponto de entrada de mensagens seguras) e suas URLs. Eles se tornam iframes incorporados + links de fallback.
6. Editores — quem atualiza o conteúdo após o lançamento (apenas o proprietário? um administrador? profissionais escrevendo posts?) — isso decide o acesso ao PagesCMS e quanto do site é gerenciado pelo CMS vs. gerenciado por código.
7. Ativos existentes — conteúdo do site atual a migrar, fotos (e seus direitos), Perfil Empresarial do Google e listagens de diretórios com os quais o site deve manter consistência.

Regras rígidas

1. O consultório possui todas as contas — registrador de domínio, GitHub, Cloudflare. Configure sob os logins do consultório, com opções de recuperação que o consultório controla.
2. Conteúdo é dado, não código. Qualquer coisa que um editor possa alterar (biografias de profissionais, serviços, honorários, FAQs, posts) vive em Markdown/frontmatter por trás de um esquema de conteúdo — nunca codificado nos templates .astro.
3. Templates de nome de arquivo do PagesCMS usam {fields.slug} (ou o caminho real do campo da coleção). Um {slug} simples é inválido e faz todo salvamento do CMS falhar com um erro opaco. Após corrigir a configuração, recarregue o CMS — ele armazena a configuração em cache por sessão.
4. O site não coleta nada clínico. Sem caixas de texto de sintomas, sem formulários "conte-nos o que está acontecendo". Contato = link/incorporação de agendamento, telefone e um aplicativo de formulário roteado, se necessário — mais a linha de crise (188 no Brasil, e 190 para emergências) na página de contato e em qualquer página que convide ao contato, nos idiomas do site.
5. Incorporações têm links de fallback. Cada iframe (agendamento, diretório) é acompanhado por um link simples para o mesmo sistema, para que um frame bloqueado nunca deixe um cliente sem saída.
6. Disciplina de informações: convênios, honorários, credenciais e disponibilidade no site devem corresponder à fonte de verdade do consultório (seus registros). O site é o último lugar onde um fato deve ser editado — se um número existe em dois lugares, nomeie qual deles vence.
7. Desempenho é um recurso em um site de terapia — as pessoas chegam ansiosas, em celulares, a partir de um perfil de diretório. Comprima imagens antes de entrarem no repositório; uma foto herói de 2 MB é um bug, não um ativo.

Ordem de construção

1. Repositório + scaffold do Astro + modelo de conteúdo conforme references/astro-setup.md, páginas conforme references/site-blueprint.md.
2. Build local verde; placeholders de conteúdo sinalizados e listados para o proprietário.
3. Configuração do PagesCMS + o teste de salvamento real conforme references/pagescms-config.md.
4. Conexão do Cloudflare Pages + domínio personalizado conforme references/cloudflare-pages-deploy.md.
5. Passagem de SEO/desempenho conforme references/seo-and-performance.md.
6. Transferência conforme references/maintenance-and-handoff.md; verifique conforme references/test-checklist.md.

Arquivos de referência

• references/architecture-and-stack.md — as três camadas, fluxo de dados, o que estático significa para um consultório
• references/site-blueprint.md — as páginas, o que cada uma deve conter, itens obrigatórios específicos para terapia
• references/astro-setup.md — layout do projeto, coleções de conteúdo + esquema, árvore multilíngue
• references/pagescms-config.md — .pages.yml, coleções, mídia, a regra do template de nome de arquivo
• references/cloudflare-pages-deploy.md — configuração do projeto, configurações de build, domínio personalizado, visualizações
• references/seo-and-performance.md — metadados, dados estruturados, sitemap/RSS, llms.txt, imagens
• references/maintenance-and-handoff.md — fluxo de edição, atualizações, backups, quem possui o quê
• references/test-checklist.md — testes de aceitação, o teste de salvamento do CMS primeiro