mindxassociates/practice-website-kit

Practice Website Kit — Astro + PagesCMS + Cloudflare Pages

The stack, and why

Layer	Choice	Why
Site framework	Astro	Ships static HTML with near-zero JavaScript by default — fast on phones, nothing to patch, content in Markdown with typed frontmatter.
Content editing	PagesCMS (app.pagescms.org)	Free, open-source, Git-based: staff edit in web forms; every save is a Git commit. No database, no CMS server to maintain.
Hosting	Cloudflare Pages	Free tier fits a practice site comfortably (generous build minutes and bandwidth, many custom domains), no branding, commercial use allowed, global CDN, automatic HTTPS. Deploy = connect the Git repo.
Repo	GitHub (practice-owned)	The single home of the site: Astro reads it, PagesCMS writes to it, Cloudflare builds from it.

The architecture rule that makes this work: the website is a publication, not an application. Pages, profiles, and posts are content. Bookings, payments, messaging, and directories already have systems — the site embeds and links them; it never reimplements them and never receives their data.

Instructions for the agent

• Deliverable = a working repo the practice owns + the three connections made (PagesCMS → repo, Cloudflare Pages → repo + domain) + one verified end-to-end edit through the CMS. If you lack account access, produce the complete repo and a click-by-click connection checklist for the owner.
• Run the setup interview first. Never invent practice facts — credentials, licenses, insurance panels, fees, languages, years in practice. Placeholders, flagged, until the owner supplies them.
• Verify every platform behavior from the live config, not from memory: the PagesCMS filename-template rule in references/pagescms-config.md cost a real site its first save — treat the CMS save test as the definition of "configured."

Setup interview (ask once, before building)

1. Practice identity — practice name, domain (and where DNS lives — Cloudflare hosting is smoothest when DNS is at Cloudflare too), logo/colors if any, phone/email to display.
2. Shape — solo or group; provider list (names, credentials, license states, photo availability) for profile pages.
3. Pages — confirm the blueprint in references/site-blueprint.md (add/remove: e.g. a dedicated page per service? a resources/blog section? a referral directory embed?).
4. Languages — one language, or a mirrored tree (e.g. English at /, Chinese at /zh/)? Mirrored means human-quality translated pages with their own slugs — budget the translation; never machine-translate clinical-adjacent content and ship it unread.
5. Dynamic embeds — which existing systems appear on the site (booking page, contact form app, referral directory, secure-messages entry point) and their URLs. These become iframe embeds + fallback links.
6. Editors — who updates content after launch (owner only? an admin? providers writing posts?) — this decides PagesCMS access and how much of the site is CMS-managed vs. code-managed.
7. Existing assets — current site content to migrate, photos (and their rights), Google Business Profile and directory listings the site must stay consistent with.

Hard rules

1. The practice owns every account — domain registrar, GitHub, Cloudflare. Set up under the practice's logins, with recovery options the practice controls.
2. Content is data, not code. Anything an editor might change (provider bios, services, fees, FAQs, posts) lives in Markdown/frontmatter behind a content schema — never hard-coded into .astro templates.
3. PagesCMS filename templates use {fields.slug} (or the collection's real field path). A bare {slug} is invalid and makes every CMS save fail with an opaque error. After fixing config, reload the CMS — it caches config per session.
4. The site collects nothing clinical. No symptom text boxes, no "tell us what's going on" forms. Contact = booking link/embed, phone, and a routed form app if needed — plus the crisis line (988 in the US, and 911 for emergencies) on the contact page and any page that invites contact, in the site's languages.
5. Embeds get fallback links. Every iframe (booking, directory) is paired with a plain link to the same system, so a blocked frame never dead-ends a client.
6. Claims discipline: panels, fees, credentials, and availability on the site must match the practice's source of truth (its roster/records). The website is the last place a fact should be edited — if a number lives in two places, name which one wins.
7. Performance is a feature on a therapy site — people arrive anxious, on phones, from a directory profile. Compress images before they enter the repo; a 2 MB hero photo is a bug, not an asset.

Build order

1. Repo + Astro scaffold + content model per references/astro-setup.md, pages per references/site-blueprint.md.
2. Local build green; content placeholders flagged and listed for the owner.
3. PagesCMS config + the real save test per references/pagescms-config.md.
4. Cloudflare Pages connection + custom domain per references/cloudflare-pages-deploy.md.
5. SEO/performance pass per references/seo-and-performance.md.
6. Handoff per references/maintenance-and-handoff.md; verify per references/test-checklist.md.

Reference files

• references/architecture-and-stack.md — the three layers, data flow, what static means for a practice
• references/site-blueprint.md — the pages, what each must contain, therapy-specific musts
• references/astro-setup.md — project layout, content collections + schema, multilingual tree
• references/pagescms-config.md — .pages.yml, collections, media, the filename-template rule
• references/cloudflare-pages-deploy.md — project setup, build settings, custom domain, previews
• references/seo-and-performance.md — metadata, structured data, sitemap/RSS, llms.txt, images
• references/maintenance-and-handoff.md — editing workflow, updates, backups, who owns what
• references/test-checklist.md — acceptance tests, the CMS save test first