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

package/templates/docs/09-whats-included.md

@@ -0,0 +1,279 @@
+# What's Included in This Starter
+
+This document lists all features, patterns, and capabilities included in this Agility CMS Next.js starter project.
+
+## Core Features
+
+### ✅ Agility CMS Integration
+- Full SDK integration with `@agility/nextjs` and `@agility/content-fetch`
+- Environment-based configuration (fetch vs preview API)
+- Type-safe helper functions for all CMS operations
+
+### ✅ Next.js 15 App Router
+- Dynamic routing with `[locale]/[...slug]`
+- Server Components by default
+- Incremental Static Regeneration (ISR)
+- Static generation at build time
+
+### ✅ Multi-Locale Support
+- Configurable locales via environment variables
+- Clean URLs for default locale (no prefix)
+- Prefixed URLs for other locales (/fr/, /es/)
+- Locale-aware sitemap generation
+- Middleware-based locale routing
+
+### ✅ Middleware
+- Preview mode handling
+- Exit preview mode
+- Dynamic page requests (ContentID routing)
+- Locale-based routing and rewriting
+- Search parameter encoding for static optimization
+- Redirect handling
+
+### ✅ Caching
+- Time-based revalidation (configurable)
+- Cache tags for targeted revalidation
+- On-demand revalidation via webhooks (API route ready)
+- Preview mode bypasses cache
+- Per-page revalidation configuration
+
+### ✅ Data Fetching Utilities
+All in `src/lib/cms/`:
+- `getAgilitySDK()` - Initialize SDK
+- `getAgilityPage()` - Fetch complete page data
+- `getAgilityContext()` - Get current context
+- `getContentItem()` - Fetch single content
+- `getContentList()` - Fetch content lists
+- `getSitemapFlat()` - Flat sitemap
+- `getSitemapNested()` - Nested sitemap
+- `getRedirections()` - Fetch redirects
+
+### ✅ TypeScript
+- Full TypeScript support
+- Type-safe environment variables via `lib/env.ts`
+- Interfaces for module props
+- Generic types for CMS functions
+
+### ✅ Component Architecture
+- Component registry in `agility-components/index.ts`
+- Page template registry in `agility-pages/index.ts`
+- ContentZone for zone-based rendering
+- Example RichTextArea module
+
+### ✅ SEO & Metadata
+- Dynamic metadata generation
+- Title and description from Agility CMS
+- Locale-aware URLs
+- Static generation for all pages
+
+## Included Components
+
+### Page Templates
+1. **MainTemplate** - Single zone template with main-content-zone
+
+### Module Components
+1. **RichTextArea** - Rich text content with Tailwind prose styling
+
+## Included Utilities
+
+### CMS Helpers (`lib/cms/`)
+- ✅ SDK initialization
+- ✅ Page fetching
+- ✅ Content item fetching
+- ✅ Content list fetching
+- ✅ Sitemap fetching (flat and nested)
+- ✅ Redirections fetching
+- ✅ Context management
+
+### i18n Helpers (`lib/i18n/`)
+- ✅ Locale configuration
+- ✅ Locale validation
+- ✅ Path manipulation (get/remove locale)
+
+### Environment (`lib/env.ts`)
+- ✅ Type-safe environment variable access
+- ✅ Runtime validation
+- ✅ Required vs optional vars
+
+## Routing Features
+
+### ✅ Dynamic Routing
+- All pages route through `[locale]/[...slug]`
+- Static params generation at build time
+- 404 handling with not-found.tsx
+- Error handling with error.tsx
+
+### ✅ Special Routes
+- Preview mode: `?agilitypreviewkey=xxx`
+- Exit preview: `?AgilityPreview=0`
+- ContentID routing: `?ContentID=123`
+- Locale switching: `?lang=fr`
+
+### ✅ URL Patterns
+- Homepage: `/`
+- Pages: `/about`, `/contact`
+- Nested: `/blog/category/post`
+- Localized: `/fr/about`, `/es/contacto`
+
+## Configuration
+
+### ✅ Environment Variables
+```env
+AGILITY_GUID                    # Required
+AGILITY_API_FETCH_KEY          # Required
+AGILITY_API_PREVIEW_KEY        # Required
+AGILITY_SECURITY_KEY           # Optional (webhooks)
+AGILITY_LOCALES               # Required (e.g., "en-us,fr,es")
+AGILITY_SITEMAP               # Required (e.g., "website")
+AGILITY_FETCH_CACHE_DURATION  # Optional (default: 60)
+AGILITY_PATH_REVALIDATE_DURATION # Optional (default: 60)
+```
+
+### ✅ Config Files
+- `lib/i18n/config.ts` - Locale configuration
+- `lib/env.ts` - Environment validation
+- `proxy.ts` - Routing proxy (Next.js 16+)
+- `tsconfig.json` - TypeScript config
+
+## What's NOT Included (Yet)
+
+These are features from the demo site that could be added:
+
+### Components
+- ❌ Hero components (BackgroundHero, PersonalizedHero)
+- ❌ BentoSection with nested cards
+- ❌ LogoStrip
+- ❌ PostListing with pagination
+- ❌ PostDetails
+- ❌ Testimonials carousel
+- ❌ TeamListing
+- ❌ CompanyStats with animations
+- ❌ ContactUs form
+- ❌ Carousel
+- ❌ PricingCards/PricingTable
+- ❌ FAQ accordion
+- ❌ ABTestHero
+
+### Features
+- ❌ Header/Footer components
+- ❌ Navigation component
+- ❌ Breadcrumbs
+- ❌ Search functionality
+- ❌ Pagination helpers
+- ❌ Image optimization component (AgilityPic)
+- ❌ Personalization (audience/region)
+- ❌ A/B testing
+- ❌ Analytics integration
+- ❌ AI search integration
+- ❌ View transitions
+- ❌ Bloom filter redirects
+
+### API Routes
+- ❌ `/api/preview` - Preview mode handler
+- ❌ `/api/preview/exit` - Exit preview
+- ❌ `/api/revalidate` - Webhook handler
+- ❌ `/api/dynamic-redirect` - ContentID redirect
+
+### Build Tools
+- ❌ `prebuild` script for redirect cache
+- ❌ Sitemap generation
+- ❌ Robots.txt generation
+
+## Extensibility
+
+### Easy to Add
+Using the documentation, you can easily add:
+- ✅ New component components (follow pattern in 03-creating-components.md)
+- ✅ New page templates (follow pattern in templates)
+- ✅ Content lists (follow pattern in 05-containers-and-lists.md)
+- ✅ Interactive components (follow hybrid pattern)
+- ✅ API routes (standard Next.js)
+
+### Documentation Provided
+All patterns documented in `.claude/docs/`:
+- ✅ AI assistant guide
+- ✅ CMS overview
+- ✅ Page routing
+- ✅ Creating modules
+- ✅ Data fetching
+- ✅ Containers and lists
+- ✅ Localization
+- ✅ Caching strategies
+- ✅ Common components
+
+## Recommended Next Steps
+
+After creating your project, consider adding:
+
+1. **Header & Footer**
+   - Create Header component fetching from sitemap
+   - Create Footer component with CMS content
+   - Add to layout.tsx
+
+2. **More Modules**
+   - Hero section
+   - Blog listing with pagination
+   - Testimonials
+   - Contact form
+   - FAQ accordion
+
+3. **API Routes**
+   - `/api/preview` for preview mode
+   - `/api/revalidate` for webhooks
+   - `/api/contact` for form submissions
+
+4. **Optimization**
+   - Add next/image for image optimization
+   - Set up webhooks for revalidation
+   - Configure analytics
+
+5. **Advanced Features**
+   - Search functionality
+   - Personalization
+   - A/B testing
+
+## Getting Started with Extensions
+
+### To Add a New Module:
+1. Read [03-creating-components.md](./03-creating-components.md)
+2. Create component file in `agility-components/`
+3. Register in `agility-components/index.ts`
+4. Create module in Agility CMS
+5. Add to pages in CMS
+
+### To Add a Content List:
+1. Read [05-containers-and-lists.md](./05-containers-and-lists.md)
+2. Create content definition in Agility CMS
+3. Create container in CMS
+4. Create module to display list
+5. Use `getContentList()` to fetch
+
+### To Add Multi-Language:
+1. Read [06-localization.md](./06-localization.md)
+2. Update `AGILITY_LOCALES` env var
+3. Update `lib/i18n/config.ts`
+4. Add locale content in CMS
+
+## Summary
+
+This starter provides:
+- ✅ **Solid Foundation**: All core Agility CMS patterns
+- ✅ **Type Safety**: Full TypeScript support
+- ✅ **Performance**: Caching and ISR built-in
+- ✅ **Scalability**: Multi-locale support
+- ✅ **Extensibility**: Easy to add features
+- ✅ **Documentation**: Comprehensive AI-friendly docs
+
+Perfect for:
+- Starting new Agility CMS projects
+- Learning Agility CMS with Next.js
+- Building with AI coding assistants
+- Creating production websites
+
+## Version Information
+
+- Next.js: 15.x
+- React: 19.x
+- Agility CMS: Latest SDK
+- TypeScript: 5.x
+- Node.js: >= 18.0.0

package/templates/docs/10-mcp-server-setup.md

@@ -0,0 +1,153 @@
+# Agility CMS MCP Server Setup
+
+The Agility CMS Model Context Protocol (MCP) server provides AI assistants like Claude with direct access to your Agility CMS content and configuration. This allows AI tools to help you build, configure, and manage your Agility CMS projects more effectively.
+
+## What is MCP?
+
+The Model Context Protocol (MCP) is a standard that allows AI assistants to connect to external data sources and tools. The Agility CMS MCP server exposes your content models, components, and instance data to compatible AI tools.
+
+## Prerequisites
+
+- Active Agility CMS account with API access
+- Valid Agility CMS instance with content models
+- MCP-compatible AI tool (Claude Code, GitHub Copilot, Cursor, Windsurf, ChatGPT Pro, etc.)
+- Internet connection for OAuth authentication
+
+## Automatic Setup (Recommended)
+
+This project includes a pre-configured MCP server setup in `.claude/settings.json`. If you're using Claude Code CLI, the MCP server should be automatically detected when you open this project.
+
+## Manual Setup by Platform
+
+### Claude Code (CLI)
+
+If the MCP server is not automatically detected, you can add it manually:
+
+```bash
+claude mcp add --transport http "Agility-CMS" https://mcp.agilitycms.com/api/mcp
+```
+
+### GitHub Copilot for VS Code
+
+1. Install the latest GitHub Copilot extension
+2. Open Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`)
+3. Search for "Copilot: Configure MCP Servers"
+4. Add the server URL: `https://mcp.agilitycms.com/api/mcp`
+5. Select "OAuth" as the authentication method
+6. Follow the OAuth flow to connect your Agility CMS account
+
+### Cursor
+
+1. Open Cursor settings
+2. Navigate to the MCP servers section
+3. Add a new server entry:
+   - Name: `Agility-CMS`
+   - URL: `https://mcp.agilitycms.com/api/mcp`
+   - Auth: OAuth
+4. Complete the OAuth authentication flow
+
+### Windsurf
+
+1. Access Windsurf settings/extensions
+2. Find the MCP servers configuration
+3. Add the Agility CMS server:
+   - Endpoint: `https://mcp.agilitycms.com/api/mcp`
+   - Authentication: OAuth
+4. Authenticate with your Agility CMS credentials
+
+### ChatGPT (Pro/Enterprise)
+
+**Note:** Custom MCP connectors are only available for ChatGPT Pro users and Business/Enterprise/Education workspaces, and are currently only usable in Deep Research mode.
+
+1. Open your ChatGPT profile settings
+2. Navigate to "Custom Connectors" or "MCP Servers"
+3. Create a new custom connector:
+   - Name: `Agility CMS`
+   - URL: `https://mcp.agilitycms.com/api/mcp`
+4. Complete OAuth authentication
+5. Use the connector in Deep Research mode
+
+## Authentication
+
+All platforms use OAuth authentication:
+
+1. When prompted, you'll be redirected to the Agility CMS login page
+2. Sign in with your Agility CMS credentials
+3. Grant the MCP server access to your instances
+4. You'll be redirected back to your AI tool
+
+The authentication is persistent and you won't need to re-authenticate unless you explicitly disconnect.
+
+## Available MCP Tools
+
+Once connected, the AI assistant will have access to these tools:
+
+### Content Management
+- View and search content models
+- Access content items
+- Browse content containers
+- Query content lists
+
+### Component Management
+- List component models
+- Access component instances
+- View field types and configurations
+
+### Instance Information
+- Get instance details
+- Access API keys and configurations
+- View available locales
+
+## Using the MCP Server
+
+Once configured, you can ask your AI assistant questions like:
+
+- "What content models are available in my Agility instance?"
+- "Show me the fields for the BlogPost content model"
+- "List all the components in this project"
+- "What are the available locales in my instance?"
+- "Help me create a new component that matches the Article content model"
+
+The AI assistant will use the MCP server to fetch real-time data from your Agility CMS instance and provide accurate, context-aware responses.
+
+## Troubleshooting
+
+### MCP Server Not Detected
+
+If the MCP server is not automatically detected:
+
+1. Ensure the `.claude/settings.json` file exists in your project root
+2. Check that your AI tool supports MCP servers
+3. Try manually adding the server using the platform-specific instructions above
+4. Restart your AI tool
+
+### Authentication Failures
+
+If authentication fails:
+
+1. Verify you have an active Agility CMS account
+2. Check your internet connection
+3. Try clearing your OAuth tokens and re-authenticating
+4. Ensure your Agility CMS account has API access enabled
+
+### MCP Tools Not Working
+
+If the MCP tools are not responding:
+
+1. Verify you've completed OAuth authentication
+2. Check that your Agility instance is active
+3. Ensure you have proper permissions in your Agility CMS account
+4. Try disconnecting and reconnecting the MCP server
+
+## More Information
+
+- [Agility CMS MCP Server Documentation](https://mcp.agilitycms.com/instructions)
+- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
+- [Agility CMS Documentation](https://help.agilitycms.com/)
+
+## Security Notes
+
+- The MCP server uses OAuth 2.0 for secure authentication
+- Your API keys and credentials are never stored by the MCP server
+- All communication is over HTTPS
+- You can revoke MCP server access at any time from your Agility CMS account settings