# WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

## Project Overview

This is a Statamic 5 project - a flat-file CMS built on Laravel 12. Statamic uses a "flat-first" approach where content is stored in files (YAML, Markdown) rather than a database by default, with optional database support via Eloquent drivers.

**Tech Stack:**
- PHP 8.2+
- Laravel 12
- Statamic 5.69+
- Vite 7 with Tailwind CSS 4
- SQLite (default database)

## Key Architecture

### Content Management
- **Content location**: `/content/` directory contains all flat-file content
  - Collections: `/content/collections/` - organized content (pages, blog posts, etc.)
  - Assets: `/content/assets/` - uploaded files and images
  - Globals: `/content/globals/` - site-wide settings
  - Navigation: `/content/navigation/` - menu structures
  - Taxonomies: `/content/taxonomies/` - categorization systems
  - Trees: `/content/trees/` - hierarchical structures
- Each entry is a YAML file with frontmatter and optional Markdown content
- Collections are defined by YAML files (e.g., `pages.yaml`) that configure routing and behavior

### View System
- **Antlers templating**: Statamic uses Antlers (`.antlers.html` files) as the primary template engine
- Templates are in `/resources/views/`
- Antlers syntax: `{{ variable }}`, `{{ tag:parameter }}`, control structures with paired tags
- Layout system: templates extend from `layout.antlers.html`

### Static Assets & Frontend
- CSS: `/resources/css/` compiled by Vite
- JS: `/resources/js/` compiled by Vite  
- Tailwind CSS 4 with Typography plugin configured
- Build outputs to `/public/build/`

### Configuration
- Laravel config: `/config/`
- Statamic-specific config: `/config/statamic/` with 20+ configuration files
  - Key configs: `system.php`, `cp.php`, `assets.php`, `routes.php`, `stache.php`
  - Features controlled via config: GraphQL, Git integration, API, Static caching, Revisions

### Users & Permissions
- Users stored as YAML files in `/users/` directory
- User structure: email-based filenames with YAML content

### Statamic Control Panel
- Admin interface accessible at `/cp` (configurable)
- Manage content, assets, users, and configuration via web UI

## Common Commands

### Development Server
```bash
# Start all development services (recommended)
composer dev
# This runs: server (port 8000), queue worker, logs (pail), and vite dev server

# Or start services individually:
php artisan serve              # Laravel dev server
npm run dev                    # Vite dev server with hot reload
php artisan queue:listen       # Queue worker
php artisan pail              # Real-time log viewer
```

### Statamic CLI (`please` command)
Statamic provides a `./please` CLI tool for Statamic-specific commands:

```bash
# Content & Cache Management
./please stache:clear          # Clear Statamic's file-based cache
./please stache:refresh        # Rebuild the cache from content files
./please stache:warm           # Pre-warm the cache
./please static:clear          # Clear static page cache
./please glide:clear           # Clear image cache
./please assets:clear-cache    # Clear asset metadata cache

# User Management  
./please make:user            # Create a new user interactively

# Development
./please make:addon           # Create a new addon
./please make:fieldtype       # Create a custom field type
./please make:modifier        # Create a custom modifier
./please make:tag             # Create a custom tag
./please make:widget          # Create a CP widget
./please support:details      # Output system info for support

# List all available commands
./please list
```

### Build & Deploy
```bash
# Initial setup
composer setup                # Installs deps, generates key, runs migrations, builds assets

# Frontend builds
npm run build                 # Production build
npm run dev                   # Development build with watch
npm run watch                 # Alias for dev

# Testing
composer test                 # Run PHPUnit tests
php artisan test              # Alternative test command
./vendor/bin/phpunit          # Direct PHPUnit invocation

# Code Quality
./vendor/bin/pint             # Laravel Pint code formatter (available)
```

### Database
```bash
php artisan migrate           # Run migrations
php artisan migrate:fresh     # Drop all tables and re-run migrations
```

## Development Patterns

### Creating Content
1. Content entries are Markdown files with YAML frontmatter in `/content/collections/`
2. Define collections in `/content/collections/{collection}.yaml`
3. Access in templates via Antlers tags: `{{ collection:pages }}`

### Custom Functionality
- **Modifiers**: Text transformation filters for Antlers (e.g., `{{ title | uppercase }}`)
- **Tags**: Custom Antlers tags for complex logic (e.g., `{{ my_tag }}`)
- **Fieldtypes**: Custom CP fields for content editing
- **Actions**: Bulk actions in the Control Panel
- **Widgets**: Dashboard widgets for the CP
- **Scopes**: Query filters for collections

### The Stache
The "Stache" is Statamic's file-based caching layer that indexes flat files for performance:
- Auto-refreshes in local environments (configurable via `STATAMIC_STACHE_WATCHER`)
- Run `./please stache:refresh` after bulk file changes
- Run `./please stache:doctor` to diagnose cache issues

### Adding Blueprints & Fields
- Blueprints define content structure (like schemas)
- Managed via Control Panel or YAML files in `/resources/blueprints/`
- Field types: text, textarea, markdown, assets, entries, terms, etc.

## Testing

- PHPUnit configured for Feature and Unit tests
- Test files in `/tests/Feature/` and `/tests/Unit/`
- Test database uses in-memory SQLite
- Run via `composer test` or `php artisan test`

## Environment Configuration

Key `.env` variables for Statamic:
```bash
STATAMIC_LICENSE_KEY=         # Required for Pro features
STATAMIC_PRO_ENABLED=false    # Enable Pro features
STATAMIC_STACHE_WATCHER=auto  # Cache watcher: auto/true/false
STATAMIC_GIT_ENABLED=false    # Auto-commit content changes
STATAMIC_API_ENABLED=false    # Enable REST API
STATAMIC_GRAPHQL_ENABLED=false # Enable GraphQL
STATAMIC_REVISIONS_ENABLED=false # Enable content revisions
STATAMIC_STATIC_CACHING_STRATEGY=null # Static caching strategy
```

## Important Notes

- **Don't edit files in `/public/vendor/statamic/`** - these are generated
- **Content in Git**: Flat files make content version-controllable
- **Antlers vs Blade**: Prefer Antlers for Statamic templates, Blade for Laravel-specific views
- **Asset Pipeline**: Images served through Glide for on-the-fly manipulation
- **Control Panel customization**: Use `/config/statamic/cp.php` for CP settings
- **Addons**: Install Statamic addons via Composer (most are in `statamic/` namespace)