vibecheck: Instructions file for Claude Code

VibeCheck — repo guide

VibeCheck is "the CMS you talk to": a git-backed, schema-safe headless CMS you edit by chatting with an AI agent. A page is typed data, not markup, so machine-generated content can't break the build. This file orients both Claude and human contributors working in the repo.

Requirements

• Node 22+ and npm (uses workspaces)
• git
• Optional, only to run the MCP server: a GitHub token and (for the container) Docker

Layout (npm-workspaces monorepo)

packages/schema   @vibecheck/schema — the content contract (zod). Single source of truth.
apps/site         the Astro site — renderer + content. Deploys as static HTML.
apps/mcp          @vibecheck/mcp — the MCP server (lets an agent edit from anywhere).

site and mcp both import @vibecheck/schema — never define a schema in two places.

Setup & commands

npm install
npm run build          # build:schema -> build:site (validates content) -> typecheck:mcp
npm run dev -w site    # local preview at http://localhost:4321

Editing content (the main task)

Pages are YAML in apps/site/src/content/pages/**/*.yaml. A page is a title plus a list of typed sections: hero | features | pricing | cta | richtext | faq | testimonials | embed | heading | image | gallery | divider | spacer | iconlist | form. Only richtext carries raw HTML.

• Add/edit a page → edit the YAML directly. home.yaml is the front page.
• A nested file a/b.yaml becomes /a/b/ and gets an automatic breadcrumb.
• Always run npm run build before committing — it validates every page against the schema. A green build means the content is valid (this is exactly what CI runs).

Reach for a typed section before richtext

richtext is the escape hatch, not the default — raw HTML is the one thing that can break the build, so prefer a typed section whenever one fits:

• FAQ → use the faq section (faq.yaml is the worked example). It emits FAQPage JSON-LD for SEO; faking one with features or richtext does not.
• Testimonials/reviews → use the testimonials section (home.yaml is the worked example). It emits Review JSON-LD; set subject so each review names what it's reviewing. Don't fake quotes with features or richtext.
• Feature/service grid, team → features (title + body, optional image/href). Don't hand-write card markup in richtext.
• Video (YouTube/Vimeo) → use the embed section (about.yaml is the worked example). It builds the iframe from an allowlisted provider + bare id, so a raw <iframe> in richtext is never needed (and is the kind of HTML that can break the build).
• Plans/tiers → pricing. Lead-in + button → hero or cta.
• A single image → use the image section (required alt, optional caption/link), not an <img> in richtext. Several images → gallery (grid or carousel). components.yaml is the worked example for both.
• A section heading on its own → heading (h2/h3). A checklist / feature ticks → iconlist (allowlisted icon names, never raw SVG). A rule / vertical gap → divider / spacer. All shown in components.yaml.