@stratawp/cli 2.0.3 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2024 Jon Imms
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+For the full GPL-3.0 license text, see: https://www.gnu.org/licenses/gpl-3.0.txt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stratawp/cli",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "CLI tool for StrataWP - create and manage WordPress themes",
   "author": "Jon Imms",
   "license": "GPL-3.0-or-later",
@@ -37,7 +37,8 @@
     "./generators": {
       "types": "./dist/generators/index.d.ts",
       "import": "./dist/generators/index.js"
-    }
+    },
+    "./dist/create.js": "./dist/create.js"
   },
   "files": [
     "dist",

package/templates/advanced-theme/.ai/ONBOARDING.md

@@ -0,0 +1,44 @@
+# AI Agent Onboarding Guide
+
+This guide gets you up to speed with this StrataWP theme efficiently, without redundant setup work.
+
+## 🚀 The Onboarding Workflow
+
+### Step 1: Check Agent State
+
+Check `.ai/agent-state.md`.
+
+- **If Onboarding Status is "Completed"**: Stop! Do NOT run setup or re-explore. Proceed directly to the user's task.
+- **If Onboarding Status is "Pending"**: Continue below.
+
+### Step 2: Initialize AI Setup (First-Time Only)
+
+If your agent-specific configuration file (e.g. `CLAUDE.md`, `.cursor/rules/`, `GEMINI.md`, `.github/copilot-instructions.md`) does not exist:
+
+1. Explain that you are running the setup command.
+2. Run `pnpm ai:setup` and select your agent (or pass `--agents=<name>`).
+
+### Step 3: Read Developer Directions
+
+Read `.ai/developer-directions.md` — the theme developer's standing rules for design, code style, and priorities. You **MUST** adhere to everything in it.
+
+### Step 4: Map the Theme & Initialize Project Rules
+
+1. Read `theme.json` — design tokens, palettes, typography, spacing.
+2. Read `functions.php` — which StrataWP components are registered.
+3. Read `vite.config.ts` — entry points and build options.
+4. Skim `templates/`, `parts/`, `patterns/`, and `src/blocks/` to see what exists.
+5. Record your findings in the **Discovered Theme Configuration** section of `.ai/PROJECT_RULES.md`.
+
+### Step 5: Update Agent State
+
+Update `.ai/agent-state.md`: set Status to Completed, record your agent name and the date, check off the completed steps, and add an Agent Log entry.
+
+---
+
+## 🛠️ Key Resources
+
+1. **Project Rules** (`.ai/PROJECT_RULES.md`) — running log of conventions and decisions. Check it frequently.
+2. **Skills** (`.ai/skills/`) — recipes for architecture, blocks & patterns, and deployment.
+3. **Scaffolding** — `stratawp block:new`, `stratawp component:new`, `stratawp template:new`, `stratawp part:new`.
+4. **Verification** — `pnpm ai:check` before submitting any work.

package/templates/advanced-theme/.ai/PROJECT_RULES.md

@@ -0,0 +1,58 @@
+# Project Rules & Learned Guidelines
+
+This file is updated over time by the AI agents working on this theme. It is long-term memory: a running log of theme-specific guidelines, discovered patterns, and decisions.
+
+> [!IMPORTANT]
+> **AI Agents:** Read this file on every session. Keep it updated with new architectural decisions and conventions established during your work.
+
+---
+
+## 🏗️ Discovered Theme Configuration
+
+<!--
+Agent: Document this theme's setup as you discover it (registered components, block list, template structure, build options).
+-->
+
+- **Theme Type:** WordPress block theme (FSE), built on the StrataWP framework.
+- **Framework Location:** `vendor/stratawp/core/` (vendored — never hand-edit; replaced on framework updates).
+- **Registered Components:** _(read `functions.php` and list them here)_
+- **Custom Blocks:** _(list `src/blocks/*` here)_
+
+---
+
+## 🎨 Discovered Design System & Tokens
+
+<!--
+Agent: Document the palette, typography, and spacing configured in theme.json.
+-->
+
+- **Color Palette:**
+- **Typography Rules:**
+- **Spacing Scale:**
+
+---
+
+## 💻 Theme-Specific Coding Patterns
+
+<!--
+Agent: Document custom patterns established in this theme (naming standards, APIs to use or avoid, CSS conventions).
+-->
+
+- **PHP Components:** Implement `ComponentInterface` (`get_slug()` + `initialize()`); register in `functions.php` or via the `stratawp_theme_components` filter.
+- **Blocks:** Live in `src/blocks/<name>/` with `block.json`; auto-registered by the build — never edit `inc/blocks-generated.php`.
+- **Patterns:** Native blocks first; `wp:html` only when unavoidable; no bare HTML comments between blocks.
+
+---
+
+## 📝 Running Architectural Decisions & Learnings Log
+
+<!--
+Agent: Keep a chronological log of decisions and gotchas.
+
+Entry format:
+
+### 📅 YYYY-MM-DD - Short Title
+- **Context:** What prompted the decision.
+- **Decision:** What was done and where.
+- **Key Learning:** The reusable insight.
+-->

package/templates/advanced-theme/.ai/SKILLS.md

@@ -0,0 +1,20 @@
+# Skill Directory
+
+Specialized skills for AI agents working on this theme.
+
+## 🛠 Foundational
+
+- [**Theme Architecture**](skills/architecture/SKILL.md): FSE structure, StrataWP components, build pipeline, hard rules.
+- [**Onboarding Guide**](ONBOARDING.md): First-time setup protocol.
+
+## 🧱 Building
+
+- [**Gutenberg Blocks & Patterns**](skills/gutenberg-blocks/SKILL.md): Scaffolding, auto-registration, pattern authoring rules.
+
+## ⚙️ Operations
+
+- [**Deployment**](skills/deployment/SKILL.md): Deploying safely with the StrataWP CLI.
+
+## 📋 Planning
+
+- [**Spec template**](plans/SPEC-TEMPLATE.md): Contract-first feature planning — copy it into `plans/` for any non-trivial feature.

package/templates/advanced-theme/.ai/agent-state.md

@@ -0,0 +1,21 @@
+# Agent State
+
+This file tracks the onboarding status of AI agents in this theme to prevent redundant setup runs.
+
+> [!NOTE]
+> AI Agents: If `Onboarding Status` is **Completed**, do NOT run `pnpm ai:setup` or repeat initial exploration. Proceed directly to the user's task.
+
+## Onboarding Status
+
+- **Status**:
+- **Last Agent**:
+- **Last Updated**:
+
+## Completed Steps
+
+- [ ] Initial environment check
+- [ ] AI Setup (`pnpm ai:setup`)
+- [ ] Theme architectural mapping
+- [ ] Read Developer Directions (`.ai/developer-directions.md`)
+
+## Agent Log

package/templates/advanced-theme/.ai/developer-directions.md

@@ -0,0 +1,41 @@
+# Developer Directions for AI Agents
+
+This file is your dedicated space to define standing rules for all AI agents working on this theme.
+
+> [!TIP]
+> **Theme Developer:** Fill out the sections below once, and every agent will read and follow them automatically during onboarding — no need to repeat instructions in chat.
+
+---
+
+## 🎨 Design & Aesthetic Guidelines
+
+_Define the look and feel agents should maintain._
+
+- **Brand Colors:** _(primary, secondary, backgrounds — prefer pointing at `theme.json` tokens)_
+- **Typography:** _(font families, scale, line-heights)_
+- **Spacing / Grid:** _(gaps, margins, padding system)_
+- **Design Tokens:** Check `theme.json` first before hardcoding colors or spacing.
+
+---
+
+## 💻 Coding Conventions & Overrides
+
+_Rules unique to this theme._
+
+- **PHP Standards:** _(namespace preferences, templating habits)_
+- **CSS Architecture:** _(naming schemes like BEM, utility class usage)_
+- **TypeScript/JS Rules:** _(module conventions, libraries to avoid)_
+
+---
+
+## 🚀 Project Priorities
+
+- **Immediate Focus:**
+- **Planned Enhancements:**
+- **Strict Constraints:** _(e.g., "Do not modify the checkout templates without asking")_
+
+---
+
+## 📝 Custom Guidelines / Miscellaneous
+
+-

package/templates/advanced-theme/.ai/plans/SPEC-TEMPLATE.md

@@ -0,0 +1,37 @@
+# SPEC: {Feature Title}
+
+> Copy this template to `.ai/plans/{YYYY-MM-DD}-{feature-slug}.md`. Do not begin implementation until the user approves the contract.
+
+## Mission Statement
+
+_One or two sentences describing the goal and the problem it solves._
+
+## Architectural Fit
+
+- **Areas touched:** _(e.g., new block in `src/blocks/`, component in `inc/Components/`, template in `templates/`)_
+- **Hooks & filters used:** _(e.g., `stratawp_theme_components`, `stratawp_conditional_css_files`)_
+- **Design tokens:** _(which `theme.json` tokens apply)_
+
+## User Stories
+
+- As a _(site visitor / editor / developer)_, I want _..._ so that _..._
+
+## Success Metrics
+
+_How will this be verified? (e.g., "pnpm ai:check passes", "block renders correctly in editor and front end", "no accessibility regressions")_
+
+## Technical Plan (The Contract)
+
+1. **Scaffolding:** _(commands to run, e.g., `stratawp block:new hero`)_
+2. **Implementation steps:** _(logical order of file creation/modification, with paths)_
+3. **Verification:** _(build, editor check, front-end check)_
+
+## Open Questions
+
+- _(Anything unresolved that blocks >95% implementation confidence.)_
+
+## Approval
+
+- **Status:** Draft / Approved
+- **Approved by:** —
+- **Date:** —

package/templates/advanced-theme/.ai/skills/architecture/SKILL.md

@@ -0,0 +1,43 @@
+---
+description: Theme structure, StrataWP component architecture, and build pipeline constraints.
+globs: src/**/*, inc/**/*, templates/**/*, parts/**/*, patterns/**/*, theme.json, vite.config.ts
+---
+
+# Theme Architecture
+
+## Layout
+
+| Path                       | What it is                                                           |
+| -------------------------- | -------------------------------------------------------------------- |
+| `theme.json`               | Global settings, styles, and design tokens (single source of truth)  |
+| `templates/` / `parts/`    | Block templates and template parts (`.html`, FSE)                    |
+| `patterns/`                | Block patterns (`.php` with header comments)                         |
+| `src/blocks/`              | Custom Gutenberg blocks (auto-registered by the build)               |
+| `src/js/`, `src/scss/`     | Entry points defined in `vite.config.ts` (`src/css/` in some themes) |
+| `inc/Components/`          | Theme-specific PHP components                                        |
+| `vendor/stratawp/core/`    | The vendored StrataWP framework — **never hand-edit**                |
+| `dist/`                    | Build output — **never edit**                                        |
+| `inc/blocks-generated.php` | Generated block registration — **never edit**                        |
+
+## Hard Rules
+
+1. **Source files only.** `dist/` and generated files are artifacts of `pnpm build`.
+2. **The framework is vendored.** `vendor/stratawp/core/` is replaced wholesale on framework updates. Custom behavior belongs in `inc/Components/` and `stratawp_*` filters, never in vendor files.
+3. **pnpm only** for installs and scripts.
+4. **Scaffold with the CLI:** `stratawp block:new`, `component:new`, `template:new`, `part:new`.
+
+## PHP Component Architecture
+
+- Every component implements `ComponentInterface`: `get_slug(): string` + `initialize(): void` (hook registrations go in `initialize()`, constructors stay side-effect free).
+- Components are registered in `functions.php` via the `Theme` class, and the `stratawp_theme_components` filter can add/remove/replace them.
+- Framework extension points are `stratawp_*` filters — e.g. `stratawp_conditional_css_files`, `stratawp_preconnect_hints`, `stratawp_defer_scripts`. Prefer filters over hardcoding.
+
+## Build Pipeline
+
+- Vite compiles entry points and blocks to `dist/`; WordPress enqueues via the generated manifest.
+- `pnpm dev` runs the dev server with HMR (JS/TS, SCSS, and PHP hot reload).
+- `pnpm build` produces production assets and regenerates `inc/blocks-generated.php`.
+
+## Naming
+
+- Block namespace = theme slug. Component slugs kebab-case; PHP classes PascalCase; TS files kebab-case.

package/templates/advanced-theme/.ai/skills/deployment/SKILL.md

@@ -0,0 +1,34 @@
+---
+description: Deploying this theme safely with the StrataWP CLI.
+globs: .stratawp-deploy.json, dist/**/*
+---
+
+# Deployment
+
+This theme deploys with the StrataWP CLI (SFTP/FTP/SSH with pre-deploy snapshots).
+
+> [!WARNING]
+> Deploys mutate a live site. Never run `stratawp deploy`, `sync:db:push`, or any remote-mutating command unless the user explicitly asks for that exact operation in this session. Always prefer `--dry-run` first.
+
+## Commands
+
+```bash
+stratawp deploy:setup                  # one-time interactive configuration
+stratawp deploy:test production        # connection test (safe)
+stratawp deploy production --dry-run   # preview what would change (safe)
+stratawp deploy production             # real deploy (asks for confirmation)
+stratawp sync:templates production --all   # push Site Editor templates (stored in DB, not files)
+stratawp rollback:list                 # snapshots (deploys auto-snapshot first)
+```
+
+## What Ships
+
+Only production files deploy: `dist/`, PHP files, `theme.json`, `style.css`, `vendor/`. Source (`src/`), `node_modules/`, and dev files (including `.ai/` and `AGENTS.md`) never ship.
+
+## Rules
+
+1. **Build before deploy** (`pnpm build`) unless using the CLI's built-in build step.
+2. **Dry-run first, always.** Read the file list; if anything unexpected appears, stop and show the user.
+3. **Site Editor template changes live in the database**, not in `templates/*.html` — file deploys don't move them. Use `stratawp sync:templates` for those.
+4. **Credentials** live in the deploy config / `.env` — never inline them in commands, code, or logs.
+5. If something breaks post-deploy, snapshots exist: `stratawp rollback:list` / `rollback:diff` — but restoring is the user's call, not yours.

package/templates/advanced-theme/.ai/skills/gutenberg-blocks/SKILL.md

@@ -0,0 +1,34 @@
+---
+description: Scaffolding custom Gutenberg blocks and authoring block patterns in this theme.
+globs: src/blocks/**/*, patterns/**/*
+---
+
+# Gutenberg Blocks & Patterns
+
+## Blocks
+
+Scaffold — never hand-roll:
+
+```bash
+stratawp block:new hero
+```
+
+This creates `src/blocks/hero/` with `block.json`, `index.tsx` (editor), `save.tsx` (front end), and styles.
+
+Rules:
+
+- **Auto-registration:** the build scans `src/blocks/**/block.json` and regenerates `inc/blocks-generated.php`. Never edit that file.
+- **apiVersion 3** for all new blocks; namespace = theme slug.
+- **Dynamic output** uses `render.php` + `"render"` in `block.json`; static output lives in `save.tsx`.
+- **Changing a shipped block's attributes or save output requires a `deprecated` entry** — otherwise existing content shows block-recovery errors.
+- Front-end behavior should prefer the Interactivity API (`viewScriptModule`, `data-wp-*` directives) over ad-hoc scripts.
+
+Verify: `pnpm build`, then insert the block in the editor — no console errors, no "attempt block recovery" prompts.
+
+## Patterns (`patterns/*.php`)
+
+- **Default to native blocks** (`wp:paragraph`, `wp:heading`, `wp:group`, …) with `className` hooks — they stay editable and render WYSIWYG in the editor.
+- **Use `wp:html` only when it earns its keep:** inline custom-classed spans the rich-text editor strips, custom data attributes, or embedded SVG. Keep chunks small.
+- **Never put bare `<!-- ... -->` HTML comments between blocks** — use `<?php /* ... */ ?>`. Bare comments make the parser wrap them in empty paragraphs (visible layout gaps) or fall back to the Classic block.
+- **Patterns are templates, not live references.** Once inserted, page content is a copy — editing the pattern file does not update existing pages.
+- Watch `theme.json` `<p>` margins when converting a `<div>`/`<span>` to `wp:paragraph` — add explicit margins to affected styles.

package/templates/advanced-theme/.aiignore

@@ -0,0 +1,42 @@
+# Files and directories AI agents should not read or index.
+
+# Dependencies
+node_modules/
+vendor/
+
+# Build artifacts
+dist/
+.turbo/
+.vite/
+
+# Generated files
+inc/blocks-generated.php
+
+# Temporary files
+*.log
+tmp/
+.DS_Store
+*.zip
+*.tar.gz
+*.bak
+
+# Minified assets
+*.min.css
+*.min.css.map
+*.min.js
+*.min.js.map
+
+# Environment & secrets
+.env
+.env.*
+.stratawp-deploy.json
+.stratawp-snapshots/
+
+# Binary assets
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.webp
+*.woff
+*.woff2

package/templates/advanced-theme/AGENTS.md

@@ -0,0 +1,42 @@
+# AI Agents Guide
+
+Welcome, AI Agent! This is a StrataWP-powered WordPress block theme (FSE). To work here safely and effectively, you **MUST** follow these five core pillars.
+
+---
+
+### 1. ONBOARDING & STATE PROTOCOL
+
+Before starting, check `.ai/agent-state.md` for your status:
+
+- **If Pending:** Follow [**The Onboarding Guide**](.ai/ONBOARDING.md) (run `pnpm ai:setup` once, read [**Developer Directions**](.ai/developer-directions.md), read/initialize [**Project Rules**](.ai/PROJECT_RULES.md), and mark state as Completed).
+- **If Completed:** Read [**Project Rules**](.ai/PROJECT_RULES.md) for learned theme conventions, keep it updated with new decisions, and proceed directly to the user's task. Do NOT re-run setup.
+
+### 2. ARCHITECTURE & BUILD PIPELINE
+
+- **Source files only.** NEVER edit compiled artifacts (`dist/`) or generated files (`inc/blocks-generated.php` — regenerated by the build). Edit sources under `src/`.
+- **Never hand-edit `vendor/stratawp/core/`.** That is the vendored StrataWP framework — it is replaced wholesale on framework updates, so local edits are lost. Theme customization belongs in `inc/Components/` and the `stratawp_*` filters.
+- **pnpm only.** Never use `npm` or `yarn` for installs or scripts.
+- **Scaffold, don't hand-roll.** Use the StrataWP CLI (`stratawp block:new`, `stratawp component:new`, `stratawp template:new`, `stratawp part:new`) rather than manually bootstrapping files.
+
+### 3. CONTRACT-FIRST DEVELOPMENT
+
+- Do not modify source files for a non-trivial feature without an approved plan. Author a spec in `.ai/plans/` (copy `SPEC-TEMPLATE.md`) and ask clarifying questions first until you reach a >95% confidence score.
+- Trivial fixes (typos, single-line bugs) do not require a spec.
+
+### 4. CONFIGURATION FIRST
+
+- Reference `theme.json` (design tokens, settings, styles), `vite.config.ts` (entry points, plugin options), and `functions.php` (registered components) before making build or architectural changes.
+- Never hardcode what a `stratawp_*` filter already provides (resource hints, conditional styles, deferred scripts, component list).
+
+### 5. PRE-FLIGHT QUALITY CHECK
+
+- Run `pnpm ai:check` before submitting to confirm the theme builds cleanly.
+- If your change affects rendered output, verify it in the block editor and on the front end, and check for accessibility regressions (landmarks, focus, contrast, `aria-*`).
+
+---
+
+## Skills & Resources
+
+- [**Skill directory**](.ai/SKILLS.md) — recipes for this theme's architecture, blocks & patterns, and deployment.
+- **Project rules** (`.ai/PROJECT_RULES.md`) — the running log of learned conventions. Read it every session.
+- **StrataWP MCP** — if available, the `@stratawp/mcp` server exposes the framework's generators and component catalog to MCP-capable agents.

package/templates/advanced-theme/package.json

@@ -8,7 +8,9 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "ai:setup": "node scripts/ai-setup.mjs",
+    "ai:check": "pnpm build"
   },
   "dependencies": {
     "@wordpress/block-editor": "^12.19.0",

package/templates/advanced-theme/scripts/ai-setup.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Generates instruction files for AI coding agents so they discover and
+// follow this theme's agent protocol (AGENTS.md + .ai/). Zero dependencies.
+//
+// Usage:
+//   pnpm ai:setup                 # interactive agent selection
+//   pnpm ai:setup --all           # generate for every supported agent
+//   pnpm ai:setup --agents=claude,cursor
+//   pnpm ai:setup --force         # overwrite existing files
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createInterface } from 'node:readline/promises'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+const CORE_INSTRUCTIONS = `# AI Agent Instructions
+
+This WordPress theme is built on the StrataWP framework and uses a structured AI-assisted development workflow.
+
+**Read \`AGENTS.md\` at the theme root and follow its protocol before making any changes.**
+
+Core rules (full detail in AGENTS.md):
+
+1. **Onboarding & state:** Check \`.ai/agent-state.md\`. If onboarding is pending, follow \`.ai/ONBOARDING.md\`. Always read \`.ai/PROJECT_RULES.md\` for learned theme conventions.
+2. **pnpm only.** Never use npm or yarn.
+3. **Source files only.** Never edit \`dist/\`, \`inc/blocks-generated.php\`, or \`vendor/stratawp/core/\` (the vendored framework — replaced wholesale on updates).
+4. **Contract-first.** Non-trivial features require an approved spec in \`.ai/plans/\` (copy \`SPEC-TEMPLATE.md\`).
+5. **Pre-flight check.** Run \`pnpm ai:check\` before submitting work.
+
+Skill recipes live in \`.ai/skills/\` (see \`.ai/SKILLS.md\`).
+`
+
+const AGENTS = {
+  claude: {
+    label: 'Claude Code',
+    file: 'CLAUDE.md',
+    content: CORE_INSTRUCTIONS,
+  },
+  cursor: {
+    label: 'Cursor',
+    file: '.cursor/rules/theme.mdc',
+    content: `---
+description: Theme rules for AI-assisted development
+alwaysApply: true
+---
+
+${CORE_INSTRUCTIONS}`,
+  },
+  copilot: {
+    label: 'GitHub Copilot',
+    file: '.github/copilot-instructions.md',
+    content: CORE_INSTRUCTIONS,
+  },
+  gemini: {
+    label: 'Gemini CLI',
+    file: 'GEMINI.md',
+    content: CORE_INSTRUCTIONS,
+  },
+  windsurf: {
+    label: 'Windsurf',
+    file: '.windsurf/rules/theme.md',
+    content: CORE_INSTRUCTIONS,
+  },
+}
+
+// Agents that read AGENTS.md natively and need no generated file.
+const NATIVE = [{ label: 'Codex / OpenCode / Jules', note: 'read AGENTS.md natively' }]
+
+function parseArgs(argv) {
+  const opts = { all: false, force: false, agents: [] }
+  for (const arg of argv) {
+    if (arg === '--all' || arg === '-a') opts.all = true
+    else if (arg === '--force' || arg === '-f') opts.force = true
+    else if (arg.startsWith('--agents=')) {
+      opts.agents = arg
+        .slice('--agents='.length)
+        .split(',')
+        .map((a) => a.trim().toLowerCase())
+        .filter(Boolean)
+    }
+  }
+  return opts
+}
+
+async function selectInteractive() {
+  const keys = Object.keys(AGENTS)
+  console.log('\nWhich AI coding agents should be configured?\n')
+  keys.forEach((key, i) => {
+    const configured = existsSync(resolve(root, AGENTS[key].file)) ? ' (already configured)' : ''
+    console.log(`  ${i + 1}. ${AGENTS[key].label}${configured}`)
+  })
+  console.log(`  ${keys.length + 1}. All of the above\n`)
+  for (const n of NATIVE) console.log(`  — ${n.label}: ${n.note}, no setup needed`)
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await rl.question('\nEnter numbers separated by commas (or press Enter to cancel): ')
+  rl.close()
+
+  const picks = answer
+    .split(',')
+    .map((s) => Number.parseInt(s.trim(), 10))
+    .filter((n) => Number.isInteger(n) && n >= 1 && n <= keys.length + 1)
+  if (picks.includes(keys.length + 1)) return keys
+  return picks.map((n) => keys[n - 1])
+}
+
+function writeAgentFile(key, force) {
+  const agent = AGENTS[key]
+  const target = resolve(root, agent.file)
+  if (existsSync(target) && !force) {
+    console.log(`  • ${agent.label}: ${agent.file} already exists — skipped (use --force to overwrite)`)
+    return
+  }
+  mkdirSync(dirname(target), { recursive: true })
+  writeFileSync(target, agent.content)
+  console.log(`  ✓ ${agent.label}: wrote ${agent.file}`)
+}
+
+const opts = parseArgs(process.argv.slice(2))
+let selected = []
+if (opts.all) selected = Object.keys(AGENTS)
+else if (opts.agents.length) {
+  selected = opts.agents.filter((a) => {
+    if (!AGENTS[a]) {
+      console.error(`  ! Unknown agent "${a}". Supported: ${Object.keys(AGENTS).join(', ')}`)
+      return false
+    }
+    return true
+  })
+} else {
+  selected = await selectInteractive()
+}
+
+if (!selected.length) {
+  console.log('Nothing selected — no files written.')
+  process.exit(0)
+}
+
+console.log('')
+for (const key of selected) writeAgentFile(key, opts.force)
+console.log('\nDone. Agents should now read AGENTS.md and follow the onboarding protocol in .ai/ONBOARDING.md.')

package/templates/basic-theme/.ai/ONBOARDING.md

@@ -0,0 +1,44 @@
+# AI Agent Onboarding Guide
+
+This guide gets you up to speed with this StrataWP theme efficiently, without redundant setup work.
+
+## 🚀 The Onboarding Workflow
+
+### Step 1: Check Agent State
+
+Check `.ai/agent-state.md`.
+
+- **If Onboarding Status is "Completed"**: Stop! Do NOT run setup or re-explore. Proceed directly to the user's task.
+- **If Onboarding Status is "Pending"**: Continue below.
+
+### Step 2: Initialize AI Setup (First-Time Only)
+
+If your agent-specific configuration file (e.g. `CLAUDE.md`, `.cursor/rules/`, `GEMINI.md`, `.github/copilot-instructions.md`) does not exist:
+
+1. Explain that you are running the setup command.
+2. Run `pnpm ai:setup` and select your agent (or pass `--agents=<name>`).
+
+### Step 3: Read Developer Directions
+
+Read `.ai/developer-directions.md` — the theme developer's standing rules for design, code style, and priorities. You **MUST** adhere to everything in it.
+
+### Step 4: Map the Theme & Initialize Project Rules
+
+1. Read `theme.json` — design tokens, palettes, typography, spacing.
+2. Read `functions.php` — which StrataWP components are registered.
+3. Read `vite.config.ts` — entry points and build options.
+4. Skim `templates/`, `parts/`, `patterns/`, and `src/blocks/` to see what exists.
+5. Record your findings in the **Discovered Theme Configuration** section of `.ai/PROJECT_RULES.md`.
+
+### Step 5: Update Agent State
+
+Update `.ai/agent-state.md`: set Status to Completed, record your agent name and the date, check off the completed steps, and add an Agent Log entry.
+
+---
+
+## 🛠️ Key Resources
+
+1. **Project Rules** (`.ai/PROJECT_RULES.md`) — running log of conventions and decisions. Check it frequently.
+2. **Skills** (`.ai/skills/`) — recipes for architecture, blocks & patterns, and deployment.
+3. **Scaffolding** — `stratawp block:new`, `stratawp component:new`, `stratawp template:new`, `stratawp part:new`.
+4. **Verification** — `pnpm ai:check` before submitting any work.