Sage Lando

---
name: superpowers-sage:sage-lando
description: >
  Sage theme with Acorn (Laravel IoC for WordPress) and Lando — lando start,
  lando info, lando acorn, Service Providers, View Composers, Blade components,
  ACF Composer blocks and fields, Poet CPT config/poet.php, AppServiceProvider,
  ViewServiceProvider, resources/views/, resources/css/app.css @theme Tailwind v4,
  resources/js/app.js, content/themes/{theme}/, lando yarn dev, lando yarn build,
  Blade @extends @section @include @component, Bedrock directory structure,
  lando wp, composer require, lando composer
user-invocable: false
---

# Roots Sage + Acorn + Lando

## When to use

- Setting up or modifying a Lando-based WordPress development environment
- Creating ACF blocks, field groups, partials, or options pages
- Building Blade components, view composers, or layouts
- Configuring Vite, Tailwind v4, or frontend assets
- Registering custom post types, taxonomies, or service providers
- Running Acorn or ACF Composer generators
- Troubleshooting Sage/Acorn/Lando issues

## Inputs required

- The project root path (contains `.lando.yml` and root `composer.json`)
- The theme directory path (contains theme `composer.json` and `app/` directory)
- The specific domain: blocks, fields, components, providers, frontend, or environment setup
- For generators: the name (and optional subdirectory) for the class being created

## Procedure

### 0) Triage

Determine the task domain:

1. **Environment setup / Lando** — read `references/lando-setup.md`, then go to step 1
2. **ACF blocks, fields, partials, options** — read `references/acf-composer.md`, then go to step 2
3. **Blade templates, components, composers** — read `references/blade-templates.md`, then go to step 3
4. **Frontend (Vite, Tailwind, CSS/JS)** — read `references/frontend-stack.md`, then go to step 4
5. **Service providers, services, bindings** — read `references/service-providers.md`, then go to step 5
6. **CPTs, taxonomies, navigation** — read `references/routing-and-cpts.md`, then go to step 6
7. **Testing** — read `references/testing.md`, then go to step 7
8. **Debugging** — read `references/troubleshooting.md`, then go to step 8
9. **WordPress plugin installation via Composer** — read `references/wordpress-composer.md`, then go to step 9

### 1) Understand the project structure

Confirm the project follows this layout:

```
project-root/
├── .lando.yml                    # Lando config — recipe: wordpress
├── .env                          # WP_HOME, DB credentials
├── composer.json                 # Root: roots/wordpress, WP core + plugins
├── wp/                           # WordPress core (managed by Composer)
├── content/
│   ├── plugins/                  # WordPress plugins
│   └── themes/
│       └── {theme}/
│           ├── composer.json     # Theme: roots/acorn, log1x/* packages
│           ├── package.json      # Theme: vite, tailwind, etc.
│           ├── vite.config.js
│           ├── app/
│           │   ├── Providers/
│           │   │   └── ThemeServiceProvider.php
│           │   ├── Services/       # Business logic classes
│           │   ├── View/
│           │   │   ├── Composers/  # View composers (auto-discovered)
│           │   │   └── Components/ # Blade components
│           │   ├── Blocks/         # ACF Gutenberg blocks
│           │   ├── Fields/         # ACF field groups
│           │   │   └── Partials/   # Reusable field partials
│           │   ├── Options/        # ACF options pages
│           │   ├── Console/
│           │   │   └── Commands/   # Custom Acorn CLI commands
│           │   ├── setup.php       # Theme support, nav menus, sidebars
│           │   ├── actions.php     # Global add_action calls
│           │   ├── filters.php     # Global add_filter calls
│           │   └── helpers.php     # Global helper functions
│           ├── config/
│           │   └── poet.php        # CPTs, taxonomies, block categories
│           ├── stubs/              # Custom generator stubs (auto-detected)
│           └── resources/
│               ├── views/          # Blade templates (.blade.php)
│               │   ├── layouts/    # Layout templates (app.blade.php)
│               │   ├── partials/   # Shared partials
│               │   ├── sections/   # Page sections
│               │   ├── components/ # Component views
│               │   └── blocks/     # ACF block views
│               ├── css/
│               ├── js/
│               └── fonts/
```

**Critical:** Two separate `composer.json` files exist. Root manages WordPress core and plugins; theme manages PHP dependencies (Acorn, ACF Composer, etc.). Always use `lando theme-composer` for theme packages.

### 2) Decide what to create using the decision guides

#### Composer vs Component vs Block

| Criteria                           | View Composer                                 | Blade Component                        | ACF Block                              |
| ---------------------------------- | --------------------------------------------- | -------------------------------------- | -------------------------------------- |
| **Purpose**                        | Inject data into existing WP templates        | Reusable UI piece with props/slots     | Editor-managed content block           |
| **Who controls content?**          | Developer (code)                              | Developer (props in templates)         | Content editor (Gutenberg UI)          |
| **Tied to WP template hierarchy?** | Yes (`front-page`, `single-post`)             | No — used anywhere via `<x-name>`      | No — placed in editor                  |
| **Has its own view file?**         | No — attaches to existing views               | Yes — `resources/views/components/`    | Yes — `resources/views/blocks/`        |
| **Has ACF fields?**                | No                                            | No                                     | Yes — defines editor UI                |
| **When to use**                    | Page-specific data (hero content on homepage) | Repeated UI (cards, buttons, sections) | Content editors need to add/arrange it |

#### Where to put logic

| Type of logic                                | Where it goes                        | Why                                      |
| -------------------------------------------- | ------------------------------------ | ---------------------------------------- |
| Theme support, menus, sidebars               | `setup.php`                          | WordPress bootstrap, runs once           |
| Simple `add_action` / `add_filter`           | `actions.php` / `filters.php`        | Global hooks, no dependencies            |
| Business logic (API calls, data processing)  | `Services/` class, bound in provider | Testable, injectable, reusable           |
| Hooks that depend on services                | `ThemeServiceProvider::boot()`       | Container is ready, dependencies resolve |
| Data for a specific template                 | View Composer                        | Auto-discovered, clean separation        |
| CPTs, taxonomies                             | `config/poet.php`                    | Declarative, no boilerplate              |
| Complex CPT registration (REST fields, meta) | Service Provider                     | When Poet's config isn't enough          |

#### `setup.php` vs `actions.php` vs `filters.php` vs ServiceProvider

- **`setup.php`** — `after_setup_theme` hook only: `add_theme_support()`, `register_nav_menus()`, image sizes, content width. No business logic.
- **`actions.php`** — Simple, self-contained `add_action()` calls that don't need injected services. If a hook needs a service, move it to a provider.
- **`filters.php`** — Same as above but for `add_filter()`. Query modifications, excerpt length, etc.
- **ServiceProvider `boot()`** — Any hook that depends on container-bound services, or complex logic that benefits from dependency injection.

### 3) Use generators — never create files manually

**Never create class files or view files manually.** Acorn and ACF Composer provide generators that scaffold the correct stub with proper namespace, base class, and paired view.

#### Acorn generators (`make:*`)

- `lando acorn make:component {Name}` — class + view in `app/View/Components/` + `resources/views/components/`
- `lando acorn make:composer {Name}` — view composer in `app/View/Composers/`
- `lando acorn make:provider {Name}` — service provider in `app/Providers/`
- `lando acorn make:command {Name}` — console command in `app/Console/Commands/`

Pass `Category/Name` for nested directories. Use `--inline`, `--view`, `--path` on `make:component`.

#### ACF Composer generators (`acf:*`)

- `lando acorn acf:block {Name}` — block class + view (interactive prompts)
- `lando acorn acf:field {Name}` — field group class
- `lando acorn acf:partial {Name}` — reusable field partial
- `lando acorn acf:options {Name}` — options page class
- `lando acorn acf:widget {Name}` — widget class + view

All accept `--force`. `acf:block --localize` for i18n stub. Bootstrap stubs: `lando acorn acf:stubs`.

For full generator details and custom stubs, see [`references/acf-composer.md`](references/acf-composer.md).

### 4) Run common Lando commands as needed

| Command                                   | Purpose                               |
| ----------------------------------------- | ------------------------------------- |
| `lando start`                             | Start environment                     |
| `lando acorn view:clear`                  | Clear compiled Blade cache            |
| `lando acorn optimize`                    | Cache config/routes                   |
| `lando acorn optimize:clear`              | Clear all caches                      |
| `lando acorn route:list`                  | List registered routes                |
| `lando acorn acf:sync`                    | Sync ACF field groups from code to DB |
| `lando theme-composer require vendor/pkg` | Add theme PHP package                 |
| `lando theme-yarn add pkg`                | Add theme JS package                  |
| `lando vite`                              | Start HMR dev server                  |
| `lando vite-build`                        | Build production assets               |
| `lando pint`                              | Fix PHP code style                    |

### 5) Read reference files before generating code

Read the relevant reference file **before generating code** in that domain:

| File                                                                   | When to read                                                                               |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [`references/lando-setup.md`](references/lando-setup.md)               | Setting up or modifying the Lando environment, `.env`, server configs                      |
| [`references/frontend-stack.md`](references/frontend-stack.md)         | Vite configuration, Tailwind v4, HMR, asset compilation, CSS/JS structure                  |
| [`references/acf-composer.md`](references/acf-composer.md)             | Creating blocks, field groups, partials, options pages, Builder API                        |
| [`references/service-providers.md`](references/service-providers.md)   | Container bindings, services, facades, dependency injection                                |
| [`references/blade-templates.md`](references/blade-templates.md)       | Composers, components, Sage directives, template hierarchy, layouts                        |
| [`references/routing-and-cpts.md`](references/routing-and-cpts.md)     | Custom post types, taxonomies (Poet), navigation menus (Navi)                              |
| [`references/testing.md`](references/testing.md)                       | Setting up Pest, writing tests, mocking WordPress functions                                |
| [`references/troubleshooting.md`](references/troubleshooting.md)       | Debugging common issues with Blade, ACF, Vite, Lando, autoloading                          |
| [`references/wordpress-composer.md`](references/wordpress-composer.md) | Installing WordPress plugins via Composer from `wp-packages.org` and local `.zip` packages |

## Verification

- Generator was used instead of manually creating files
- Class extends the correct base class (e.g., `SageServiceProvider`, not `ServiceProvider`)
- Hooks are in `boot()`, not `register()`
- Theme packages installed via `lando theme-composer`, not `lando composer`
- The relevant reference file was read before generating domain-specific code
- `lando acorn view:clear` run after Blade template changes if views appear stale
- `lando pint` run to fix code style

## Failure modes

### Problem: Extending `ServiceProvider` directly

- Cause: Using Laravel's base `ServiceProvider` instead of the Sage-aware one
- Fix: Extend `SageServiceProvider` in all theme service providers

### Problem: Hooks placed in `register()` instead of `boot()`

- Cause: Misunderstanding the container lifecycle
- Fix: Move all `add_action` / `add_filter` calls to `boot()`. The container is not ready during `register()`.

### Problem: Wrong Composer context

- Cause: Running `lando composer require` at project root for a theme dependency, or vice versa
- Fix: Root `composer.json` manages WP core + plugins. Theme `composer.json` manages Acorn, ACF Composer, etc. Use `lando theme-composer` for theme packages.

### Problem: `wp acorn` fails inside Lando

- Cause: Missing `--path=/app/wp` flag
- Fix: Always specify the WordPress path when running `wp acorn` in Lando

### Problem: Using raw ACF API instead of ACF Composer

- Cause: Calling `acf_add_local_field_group()` directly
- Fix: Use `Log1x\AcfComposer\Builder` via ACF Composer classes generated with `acf:block`, `acf:field`, etc.

### Problem: Blade components created in wrong directory

- Cause: Putting component classes in `Composers/` or vice versa
- Fix: Components go in `View/Components/`, composers go in `View/Composers/`

### Problem: Business logic in global PHP files

- Cause: Writing logic directly in `actions.php`, `filters.php`, or `setup.php`
- Fix: Create a `Services/` class, bind it in a provider, and call it from hooks in `boot()`

### Problem: Raw `register_post_type()` or `register_taxonomy()`

- Cause: Not using the declarative approach
- Fix: Use `log1x/poet` via `config/poet.php`. Only use a Service Provider for complex registrations that exceed Poet's capabilities.

### Problem: Manually creating component/block/field files

- Cause: Writing class and view files by hand
- Fix: Always use generators (`make:component`, `acf:block`, `acf:field`). They scaffold both class and view with correct namespace and base class.

### Problem: Tailwind configured via `tailwind.config.js`

- Cause: Using Tailwind v3 patterns
- Fix: Tailwind v4 is CSS-first. Configure via `@theme` directive in CSS files, not a JS config.

### Problem: Mixing root and theme Composer dependencies

- Cause: Installing a theme package at root or a root package in the theme
- Fix: Each `composer.json` is independent. Never cross-install.

## Escalation

- Stop and ask if the project structure does not match the expected layout above
- Stop and ask if the generator fails or produces unexpected output
- Stop and ask if unsure whether logic belongs in a Service Provider vs `actions.php`/`filters.php`
- Stop and ask if the task requires a pattern not covered by any reference file

---

## Canonical Lando Command Reference

See [references/lando-command-reference.md](references/lando-command-reference.md).