CLAUDE.md

Project instructions for Claude Code.

Project context

Markdown sync framework. Write markdown in content/, run sync commands, content appears instantly via Convex real-time database. Built for developers and AI agents.

Quick start

npm install                    # Install dependencies
npx convex dev                 # Start Convex (creates .env.local)
npm run dev                    # Dev server at localhost:5173
npm run sync                   # Sync markdown to Convex

Commands

Default and legacy modes

• Default auth mode: convex-auth
• Default hosting mode: convex-self-hosted
• Legacy compatibility mode: workos auth + netlify hosting

Workflows

Adding a blog post

1. Create content/blog/my-post.md with frontmatter (see .claude/skills/frontmatter.md)
2. Run npm run sync
3. Content appears at localhost:5173/my-post

Adding a page

1. Create content/pages/my-page.md with frontmatter
2. Run npm run sync
3. Page appears at localhost:5173/my-page

Modifying Convex functions

1. Edit files in convex/
2. npx convex dev watches and deploys automatically
3. Always add validators for args and returns (see .claude/skills/convex.md)

Deploying to production

npm run sync:all:prod          # Sync content + wiki + discovery to prod
npx convex deploy              # Deploy Convex functions
npm run deploy                 # Deploy static assets via Convex self-hosting

Netlify build command: npm ci --include=dev && npx convex deploy --cmd 'npm run build'

AI assistance

• Always use Context7 MCP for library/API documentation, code generation, setup or configuration steps
• Proactively look up documentation without explicit requests when working with libraries
• Use Context7 for up-to-date API references and best practices

Code conventions

• TypeScript strict mode
• Convex validators on all functions (args + returns)
• Use indexes, never .filter() on queries
• Make mutations idempotent with early returns
• Patch directly without reading first when possible
• Use event records for counters, not increments
• No emoji in code or docs
• No em dashes between words
• Sentence case for headings
• CSS variables for theming (no hardcoded colors)

Do not

• Use .filter() in Convex queries (use .withIndex())
• Increment counters directly (use event records)
• Read before patching unless necessary
• Leave console.log in production
• Break existing functionality
• Over-engineer solutions
• Add features not requested
• Use browser default modals/alerts

Configuration alignment

Important: src/config/siteConfig.ts and the Dashboard Config section (src/pages/Dashboard.tsx ConfigSection) must stay in sync.

When adding or modifying a configuration option:

1. Add the option to siteConfig.ts with proper TypeScript types
2. Add corresponding state, generated code, and UI in Dashboard.tsx ConfigSection
3. Keep option names consistent (e.g., socialFooter.showInHeader in siteConfig maps to socialFooterShowInHeader in Dashboard state)

The Dashboard Config generates downloadable siteConfig.ts code. Users can configure via either file editing or the dashboard UI. Both paths should produce equivalent results.

Key files

Project structure

content/
  blog/           # Markdown blog posts
  pages/          # Static pages
convex/           # Convex functions and schema
netlify/
  edge-functions/ # RSS, sitemap, API proxies
public/
  images/         # Static images
  raw/            # Generated raw markdown files
scripts/          # Sync and utility scripts
src/
  components/     # React components
  config/         # Site configuration
  context/        # React context (theme, sidebar)
  hooks/          # Custom hooks
  pages/          # Route components
  styles/         # Global CSS

Skills reference

Detailed documentation in .claude/skills/:

• frontmatter.md - Frontmatter syntax for posts and pages
• convex.md - Convex patterns specific to this app
• sync.md - How sync commands work

Resources

• Convex Best Practices
• Convex TypeScript
• Convex Write Conflicts
• Project README
• AGENTS.md

This project uses Convex as its backend.

When working on Convex code, always read convex/_generated/ai/guidelines.md first for important guidelines on how to correctly use Convex APIs and patterns. The file contains rules that override what you may have learned about Convex from training data.

Convex agent skills for common tasks can be installed by running npx convex ai-files install.