@agility/create-next-app 1.0.0-beta.2

package/templates/BLANK-INSTANCE-SETUP.md

@@ -0,0 +1,375 @@
+# Setting Up a Blank Agility CMS Instance
+
+This guide walks you through setting up a brand new Agility CMS instance from scratch to work with this Next.js starter.
+
+## ⚠️ Getting a Blank Instance
+
+**Most Agility CMS instances come with starter content.** If you need a completely blank instance to build from scratch, contact **support@agilitycms.com** to request one.
+
+> **Note**: If you already have an Agility CMS instance with existing content, you don't need this guide! Just build components for your existing content models.
+
+## 🎯 Overview
+
+When you have a blank Agility CMS instance, it's completely empty. You need to create:
+1. **Content Models** (define your content types)
+2. **Page Templates** (define page layouts)
+3. **Page Modules** (components editors can add to pages)
+4. **Sample Content** (test data to build against)
+5. **Pages** (actual pages in your sitemap)
+
+This guide assumes you're working with AI assistance. The AI can't create things in Agility CMS for you, but it can tell you exactly what to create!
+
+## ✅ Step 1: Get Your Credentials
+
+Before starting, make sure your `.env.local` has:
+
+```env
+AGILITY_GUID=your-instance-guid
+AGILITY_API_FETCH_KEY=your-fetch-api-key
+AGILITY_API_PREVIEW_KEY=your-preview-api-key
+AGILITY_SECURITY_KEY=your-security-key
+AGILITY_LOCALES=en-us
+AGILITY_SITEMAP=website
+```
+
+Get these from: Agility CMS > Settings > API Keys
+
+## 🎨 Step 2: Plan Your Content Structure
+
+### Ask AI to Help You Plan
+
+Use this prompt with your AI assistant:
+
+```
+"I have a blank Agility CMS instance. Help me plan the content structure for a [describe your website type and purpose].
+
+The site should have:
+- [List main pages: e.g., Home, About, Services, Blog, Contact]
+- [List content types: e.g., Blog posts, team members, testimonials]
+- [List special features: e.g., multi-language, filtering, search]
+
+Please provide:
+1. Complete list of content models to create with all fields
+2. List of page modules (components) needed
+3. Page templates needed
+4. Suggested sample content to add
+5. Build order (what to create first)"
+```
+
+The AI will give you a comprehensive plan. **Save this plan** - you'll reference it throughout setup!
+
+## 🏗️ Step 3: Create Content Models
+
+Content Models define your content types (Blog Post, Team Member, Product, etc.)
+
+### In Agility CMS:
+1. Go to **Settings > Content Definitions > Content Models**
+2. Click **"+ New"** to create a model
+3. For each model in your AI's plan, create it with these steps:
+
+#### Example: Creating a "Blog Post" Model
+
+1. **Name**: Blog Post
+2. **Reference Name**: blogPost (camelCase, no spaces)
+3. **Description**: Blog post content
+4. Click **"Add Fields"**:
+   - Title (Short Text) - required
+   - Slug (Short Text) - required, unique
+   - Excerpt (Long Text)
+   - Content (HTML)
+   - FeaturedImage (Image)
+   - Date (Date/Time)
+   - Author (Content Link - if you have authors model)
+   - Categories (Content List - if you have categories model)
+
+5. Click **Save**
+
+**Repeat for each content model in your plan.**
+
+### 📋 Common Content Models Checklist
+
+For most websites, you'll want:
+
+- [ ] **Page** (for basic pages: About, Services, etc.)
+  - Title, Slug, SEO fields (title, description), Content (HTML)
+
+- [ ] **Blog Post** (if you have a blog)
+  - Title, Slug, Excerpt, Content, FeaturedImage, Date, Author, Categories
+
+- [ ] **Category** (for blog categories)
+  - Title, Slug, Description
+
+- [ ] **Author** (for blog authors)
+  - Name, Bio, Photo, Email, Social Links
+
+- [ ] **Team Member** (if you have team section)
+  - Name, Title, Bio, Photo, Email, Social Links, Order
+
+- [ ] **Testimonial** (for social proof)
+  - Quote, Author, Company, Title, Photo, Rating
+
+- [ ] **Service/Product** (if applicable)
+  - Name, Description, Features, Image, Price, Category
+
+## 🎭 Step 4: Create Page Modules (Components)
+
+Page Modules are components that editors can add to page zones.
+
+### In Agility CMS:
+1. Go to **Settings > Content Definitions > Page Modules**
+2. Click **"+ New"** to create a module
+
+#### Example: Creating a "Hero" Module
+
+1. **Name**: Hero
+2. **Reference Name**: Hero (PascalCase)
+3. **Description**: Hero section with heading, text, and CTA
+4. **Add Fields**:
+   - heading (Short Text) - required
+   - subheading (Short Text)
+   - backgroundImage (Image)
+   - primaryCTA (Link)
+   - secondaryCTA (Link)
+
+5. Click **Save**
+
+**Create all modules from your AI's plan.**
+
+### 📋 Common Page Modules Checklist
+
+Essential modules for most sites:
+
+- [ ] **Hero** - Hero section with heading, image, CTA
+- [ ] **RichTextArea** - Flexible content area (already included in starter)
+- [ ] **ContentListDisplay** - Shows items from a content list
+- [ ] **TextBlock** - Heading and text content
+- [ ] **ImageTextBlock** - Image with text (side by side)
+- [ ] **CallToAction** - CTA button/banner
+- [ ] **Testimonials** - Testimonial cards/carousel
+- [ ] **Form** - Contact/newsletter form
+- [ ] **BlogListing** - Blog posts grid
+- [ ] **FeaturedContent** - Highlighted content items
+
+## 📄 Step 5: Create Page Templates
+
+Page Templates define the layout of your pages (zones where modules go).
+
+### Default Template (Already Included)
+The starter includes **MainTemplate** with a single "main" zone. This works for most pages!
+
+### Creating Additional Templates (Optional)
+
+Only create new templates if you need different layouts:
+
+1. Go to **Settings > Content Definitions > Page Templates**
+2. Click **"+ New"**
+3. Example: "Two Column Template"
+   - Add Zone: "left-zone"
+   - Add Zone: "right-zone"
+4. Save
+
+Then ask AI:
+```
+"Create a TwoColumn page template component that displays left-zone and right-zone in a 2-column grid"
+```
+
+## 📝 Step 6: Add Sample Content
+
+Before building components, add sample content so you have data to test with.
+
+### In Agility CMS:
+1. Go to **Content > [Your Content List]**
+2. Click **"+ New"** and fill in fields
+3. Add at least 2-3 items per content list
+
+#### Example: Adding Blog Posts
+1. Go to **Content > Blog Posts**
+2. Add 3-5 sample posts with:
+   - Real-ish titles and content
+   - Featured images
+   - Different dates
+   - Various categories
+
+**Why**: You need real content to test filtering, pagination, layouts, etc.
+
+## 🗺️ Step 7: Create Pages in Sitemap
+
+Now create actual pages in your site structure.
+
+### In Agility CMS:
+1. Go to **Pages**
+2. Click **"+ Add Page"**
+3. For each page:
+   - **Name**: Home, About, Blog, etc.
+   - **Template**: MainTemplate (or your custom template)
+   - **Visible in Menu**: Yes/No
+   - Save
+
+4. Add modules to page zones:
+   - Click **"Add Module"** in a zone
+   - Select your module (Hero, TextBlock, etc.)
+   - Fill in the content
+   - Save
+
+### 📋 Essential Pages Checklist
+
+- [ ] **Home** (path: `/`)
+  - Add Hero module
+  - Add featured content sections
+  - Add CTA
+
+- [ ] **About** (path: `/about`)
+  - Add TextBlock with company info
+  - Add Team Members display (if applicable)
+
+- [ ] **Blog** (path: `/blog`)
+  - Add BlogListing module
+
+- [ ] **Contact** (path: `/contact`)
+  - Add Form module
+  - Add contact info TextBlock
+
+- [ ] **Sample Blog Post** (path: `/blog/sample-post`)
+  - This will be created automatically from your blog content
+
+## 💻 Step 8: Build Components with AI
+
+Now you're ready to build! The AI can now create components that work with your CMS structure.
+
+### For Each Module You Created:
+
+```
+"Create the [ModuleName] component with these requirements:
+
+**Fields from Agility CMS:**
+- [field1]: [type]
+- [field2]: [type]
+[copy exact field names and types from your module definition]
+
+**Layout:**
+- [Describe layout: full-width, grid, flex, etc.]
+- [Responsive behavior]
+
+**Styling:**
+- [Colors, spacing, typography]
+- [Any special effects]
+
+**Reference Name**: [exact name from CMS]"
+```
+
+The AI will create the component code AND tell you to register it in `index.ts`.
+
+### Build Order:
+1. ✅ Simple modules first (TextBlock, RichTextArea)
+2. ✅ Hero/featured sections
+3. ✅ Content list displays (Blog, Team, etc.)
+4. ✅ Interactive components (Forms, carousels)
+5. ✅ Navigation and footer
+6. ✅ Detail pages (single blog post, etc.)
+
+## 🧪 Step 9: Test Everything
+
+### Test Checklist:
+- [ ] Run `npm run dev` successfully
+- [ ] Home page loads and displays all modules
+- [ ] Navigate to each page via menu
+- [ ] Content lists display correctly
+- [ ] Images load (using AgilityPic)
+- [ ] Links work
+- [ ] Forms submit (if applicable)
+- [ ] Preview mode works
+- [ ] Build succeeds: `npm run build`
+
+## 🚀 Step 10: Configure Webhooks (Optional)
+
+Set up automatic cache revalidation when content changes:
+
+1. Go to **Agility CMS > Settings > Webhooks**
+2. Click **"+ New Webhook"**
+3. Configure:
+   - **Name**: Next.js Revalidation
+   - **URL**: `https://yourdomain.com/api/revalidate`
+   - **Events**: Content Published, Page Published
+   - **Active**: Yes
+4. Save
+
+> Note: This only works when deployed. For local development, changes appear after refresh.
+
+## 🎓 Quick Reference: Agility CMS Terminology
+
+| Term | What It Is | Example |
+|------|-----------|---------|
+| **Content Model** | Definition of a content type | Blog Post, Team Member |
+| **Page Module** | Component editors add to pages | Hero, TextBlock |
+| **Page Template** | Layout with zones | MainTemplate (main zone) |
+| **Content Instance** | Actual content item | "My First Blog Post" |
+| **Zone** | Area on a template where modules go | "main", "sidebar" |
+| **Reference Name** | Code identifier (must match exactly!) | "Hero", "blogPost" |
+| **Content Link** | Single linked item | Post → Author |
+| **Content List** | Multiple linked items | Post → Categories |
+
+## 🆘 Common Setup Issues
+
+### "Module not rendering"
+- ✅ Check reference name matches exactly (case-sensitive!)
+- ✅ Verify module is registered in `index.ts`
+- ✅ Confirm module exists in Agility CMS
+- ✅ Make sure you added the module to the page zone
+
+### "Content not showing"
+- ✅ Verify referenceName in code matches CMS exactly
+- ✅ Check content is published (not draft)
+- ✅ Confirm content exists for the locale (en-us)
+- ✅ Check API keys are correct in `.env.local`
+
+### "Images broken"
+- ✅ Ensure using `<AgilityPic>` not `<Image>` or `<img>`
+- ✅ Check image field is type `ImageField`
+- ✅ Verify images are uploaded in Agility CMS
+
+### "Build fails"
+- ✅ Check all components are registered
+- ✅ Verify TypeScript types match CMS fields
+- ✅ Make sure `.env.local` is complete
+- ✅ Check for syntax errors in components
+
+## 💡 Pro Tips
+
+1. **Name Things Clearly**: Use descriptive names in both CMS and code
+2. **Stay Consistent**: Pick a naming convention (camelCase vs PascalCase) and stick to it
+3. **Start Simple**: Get basic pages working before adding complex features
+4. **Test Incrementally**: Build one component, test it, then move on
+5. **Use Sample Content**: Don't try to build with empty lists
+6. **Document Reference Names**: Keep a list of exact reference names from CMS
+7. **Ask AI for Help**: When stuck, describe the exact error you're seeing
+
+## 📚 Next Steps
+
+After setup is complete:
+
+1. **Read**: [PROMPTS.md](./PROMPTS.md) - Learn how to write effective prompts
+2. **Build**: Start creating components with AI assistance
+3. **Refine**: Iterate on designs and functionality
+4. **Deploy**: Push to production (Vercel, Netlify, etc.)
+5. **Optimize**: Add caching, SEO, performance improvements
+
+## 🎯 Quick Start Checklist
+
+Use this checklist for your setup:
+
+- [ ] Environment variables configured
+- [ ] Content models created in Agility CMS
+- [ ] Page modules created in Agility CMS
+- [ ] Page template configured (use MainTemplate or create custom)
+- [ ] Sample content added (2-3 items per list)
+- [ ] Pages created in sitemap
+- [ ] Modules added to page zones
+- [ ] Components built with AI (registered in index.ts)
+- [ ] Site running locally (`npm run dev`)
+- [ ] All pages accessible
+- [ ] Content displaying correctly
+- [ ] Build successful (`npm run build`)
+
+---
+
+**Ready to build?** Follow this guide, use the prompts in [PROMPTS.md](./PROMPTS.md), and let AI help you create an amazing website! 🎨✨

package/templates/DEVELOPMENT.md

@@ -0,0 +1,160 @@
+# Development Guide
+
+This project includes comprehensive documentation for building with Agility CMS and AI coding assistants.
+
+## 🚀 Getting Started
+
+Choose your path:
+
+### Have an Existing Agility Instance? (Most Users)
+You're ready to build! Start creating components for your existing content models.
+- **[PROMPTS.md](./PROMPTS.md)** - Learn to write effective prompts for AI assistants
+- **[EXAMPLE-PROMPTS.md](./EXAMPLE-PROMPTS.md)** - Ready-to-use prompt library
+- **[.claude/QUICK-START.md](./.claude/QUICK-START.md)** - 5-minute quickstart
+
+### Need a Blank Instance?
+Contact **support@agilitycms.com** to request a blank Agility CMS instance, then:
+- **[BLANK-INSTANCE-SETUP.md](./BLANK-INSTANCE-SETUP.md)** - Complete guide for blank instances
+
+### Building with AI?
+- **[PROMPTS.md](./PROMPTS.md)** - Learn to write effective prompts
+- **[EXAMPLE-PROMPTS.md](./EXAMPLE-PROMPTS.md)** - Ready-to-use prompt library
+
+## 📚 Documentation
+
+All documentation is located in the `.claude/` directory:
+
+### For Developers
+- **[Quick Start](./.claude/QUICK-START.md)** - Get up and running in 5 minutes
+- **[Agility CMS Overview](./.claude/docs/01-agility-cms-overview.md)** - How Agility CMS works
+- **[Creating Components](./.claude/docs/03-creating-components.md)** - Build new features
+- **[Common Components](./.claude/docs/08-common-components.md)** - Ready-to-use examples
+
+### For AI Coding Assistants
+- **[AI Assistant Guide](./.claude/docs/00-ai-assistant-guide.md)** - Guide for AI tools
+- **[Full Documentation Index](./.claude/README.md)** - Complete documentation
+
+## 🤖 Using with AI Tools
+
+### Claude Code
+Documentation is automatically discovered. Just ask:
+```
+"Add a blog with pagination"
+"Create a hero section"
+```
+
+### Cursor
+Reference docs explicitly:
+```
+"Following the pattern in .claude/docs/03-creating-components.md,
+create a testimonials carousel"
+```
+
+Or use the AI sidebar with:
+```
+@.claude/docs/03-creating-components.md
+```
+
+### GitHub Copilot
+Use workspace context:
+```
+@workspace /new Using the Agility CMS patterns in .claude/docs/,
+create a team members grid component
+```
+
+### Google AI Studio / Gemini
+Share the documentation files and reference them:
+```
+"Based on the patterns in .claude/docs/03-creating-components.md..."
+```
+
+## 📖 Common Tasks
+
+### Add a New Component
+1. Read [.claude/docs/03-creating-components.md](./.claude/docs/03-creating-components.md)
+2. Create file in `src/components/agility-components/YourComponent.tsx`
+3. Register in `src/components/agility-components/index.ts`
+4. Create component model in Agility CMS
+5. Add to pages in CMS
+
+### Fetch Content Lists
+1. Read [.claude/docs/05-containers-and-lists.md](./.claude/docs/05-containers-and-lists.md)
+2. Use `getContentList()` helper
+3. Always pass `locale` parameter
+
+### Add Multi-Language Support
+1. Read [.claude/docs/06-localization.md](./.claude/docs/06-localization.md)
+2. Update `AGILITY_LOCALES` in `.env.local`
+3. Update `lib/i18n/config.ts`
+
+## 🎯 AI Prompt Examples
+
+Try these prompts with any AI assistant:
+
+```
+"Add a blog listing component with pagination following the Agility CMS patterns"
+
+"Create a contact form component using the hybrid server/client pattern from the docs"
+
+"Implement a testimonials carousel like the example in .claude/docs/08-common-components.md"
+
+"Add a FAQ accordion component with the patterns from .claude/docs/"
+```
+
+## 📂 Project Structure
+
+```
+src/
+├── app/
+│   ├── api/                         # API routes
+│   │   ├── preview/                 # Preview mode endpoints
+│   │   ├── revalidate/              # Webhook for cache revalidation
+│   │   └── dynamic-redirect/        # Dynamic page redirects
+│   └── [locale]/[...slug]/page.tsx  # All pages route here
+├── components/
+│   ├── agility-components/          # CMS components (add here)
+│   └── agility-pages/               # Page templates
+└── lib/cms/                         # CMS helper functions
+```
+
+## 🔗 API Routes
+
+This project includes API routes for Agility CMS integration:
+
+### Preview Mode
+- **`/api/preview`** - Enables preview/draft mode for viewing unpublished content
+- **`/api/preview/exit`** - Exits preview mode and returns to published content
+
+### Cache Revalidation
+- **`/api/revalidate`** - Webhook endpoint for on-demand cache revalidation when content changes in Agility CMS
+
+### Dynamic Redirects
+- **`/api/dynamic-redirect`** - Redirects to the correct URL for a dynamic page based on ContentID
+
+**Configure webhooks in Agility CMS:** Settings > Webhooks > Add Webhook → Point to `https://yourdomain.com/api/revalidate`
+
+## 🔧 Development Commands
+
+```bash
+npm run dev     # Start development server
+npm run build   # Build for production
+npm run start   # Start production server
+```
+
+## 📞 Getting Help
+
+- **Documentation**: See [.claude/README.md](./.claude/README.md)
+- **Agility CMS Docs**: https://agilitycms.com/docs
+- **Next.js Docs**: https://nextjs.org/docs
+
+## 🌟 Key Features
+
+- ✅ Agility CMS integration with type-safe helpers
+- ✅ Multi-locale support out of the box
+- ✅ Server Components with ISR caching
+- ✅ AI-friendly documentation
+- ✅ Production-ready patterns
+
+---
+
+**Ready to build?** Check out [.claude/QUICK-START.md](./.claude/QUICK-START.md) and start creating! 🚀