Gremlin — Course Platform

Gremlin is the next-gen course platform built on Convex, with a provider/adapter pattern supporting multiple frameworks. Namespace: @gremlincms.

When to Use

Triggers: gremlin, gremlincms, wizardshit, course platform, badass-courses, work on gremlin, gremlin repo, or any task involving the gremlin monorepo.

Key Paths

What	Path
Repo root	/Users/joel/Code/badass-courses/gremlin
AGENTS.md	/Users/joel/Code/badass-courses/gremlin/AGENTS.md
ADRs	/Users/joel/Code/badass-courses/gremlin/docs/adr/
ADR index	/Users/joel/Code/badass-courses/gremlin/docs/adr/README.md
GitHub	github.com/badass-courses/gremlin

Apps

App	Path	Framework	Domain
wizardshit-ai	apps/wizardshit-ai	Next.js 16	wizardshit.ai
gremlin-cms	apps/gremlin-cms	TanStack Start	gremlincms.com

Packages

Package	Path	Purpose
@gremlincms/core	packages/core	Router, schemas, types
@gremlincms/db	packages/db	ContentResourceAdapter interface

Planned packages (from ADRs, not yet created)

• @gremlincms/convex-adapter → packages/convex-adapter/
• @gremlincms/drizzle-adapter → packages/drizzle-adapter/
• @gremlincms/next → packages/next/
• @gremlincms/tanstack → packages/tanstack/

Architecture Decisions

Read these before making structural changes:

• ADR-010: Convex-first provider/adapter pattern — Convex is primary DB, adapters are separate packages
• ADR-011: Multi-framework frontend support — Next.js + TanStack Start priority, framework-agnostic core
• ADR-012: Reference site architecture — wizardshit-ai (Next.js 16) + gremlin-cms (TanStack Start)

Legacy ADRs (001–009) cover auth, router, content model, tooling, monorepo structure, testing, CI/CD.

Vercel Deploys

Both sites deploy via git push to main on badass-courses/gremlin. No CLI deploys needed.

• Vercel org: skillrecordings (team team_QwoK7Pe6T0HIuFjig2Pm4qH8)
• wizardshit-ai: root dir apps/wizardshit-ai
• gremlin-cms: root dir apps/gremlin-cms

Related Skills

Load these when working on specific areas:

• tanstack-start: TanStack Start patterns, server functions, deployment quirks
• next-best-practices: Next.js App Router conventions
• nextjs-static-shells: Static-first rendering with dynamic slots
• next-cache-components: 'use cache', cacheLife, cacheTag
• convex: Convex development patterns (umbrella)
• convex-schema-validator: Schema design with Convex
• favicon: Emoji favicon generation with emojico
• frontend-design: UI/design quality standards

SEO Standards

All gremlin sites follow these SEO practices:

• Static-first content — no client-side data fetching for content
• Full JSON-LD — WebSite schema at minimum, Course/Organization per page type
• Dynamic OG images — /og (Next.js) or /og-image (TanStack Start) endpoints
• Canonical URLs, robots directives, Twitter cards, Open Graph tags
• Semantic HTML — proper heading hierarchy, lang attribute, structured content

Rules

1. Always read AGENTS.md at /Users/joel/Code/badass-courses/gremlin/AGENTS.md before making changes — it has project-specific constraints.
2. Use pnpm — never edit package.json by hand for deps. Use pnpm add.
3. Namespace is @gremlincms — not @badass (legacy packages still use @badass, rename deferred).
4. Adapter packages are separate — never co-locate Convex and Drizzle adapters.
5. Check ADRs before structural changes — if there's no ADR, write one first.
6. No CLI deploys — push to git, let Vercel auto-deploy.
7. TanStack Start needs nitro() plugin — without it, Vercel deploys 404. Already configured in vite.config.ts.

Quick Start

cd /Users/joel/Code/badass-courses/gremlin

# Install deps
pnpm install

# Dev (both apps)
pnpm dev

# Dev (single app)
pnpm --filter @wizardshit/web dev
pnpm --filter @gremlin/gremlin-cms dev

# Test
pnpm test

# Build
pnpm build