# Oh My IDEtch > Complete guide to the Oh My IDEtch LocalWP Devkit workflow. This file contains all documentation content in a single document following the llmstxt.org standard. ## LocalWP Devkit The Oh My IDEtch LocalWP Devkit is a reusable workspace for building code-owned Etch sites against LocalWP. Local owns WordPress, PHP, MySQL, routing, SSL, Mailpit, and Site Shell. The devkit owns project source, agent instructions, verification commands, sync, WP-CLI wrappers, and deployable plugin ZIPs. Start by downloading the LocalWP devkit ZIP from your [OhMyEtch account](https://ohmyetch.com/my-account/): ```text oh-my-idetch-localwp-devkit-.zip ``` Extract it once, keep it as a long-lived workspace, and create one project folder per LocalWP site. ## Mental Model The devkit has two surfaces: | Surface | Purpose | | --- | --- | | Devkit root | Shared commands, generated agent instructions, project templates, and package scripts. Open this folder in your agent. | | `projects/` | The source of truth for one website: PHP site builders, CMS JSON, project notes, tests, reports, and project ZIP output. | The Local site receives only a synced runtime plugin copy at: ```text wp-content/plugins/oh-my-idetch ``` Do not edit that synced plugin copy as your source. Edit the project under `projects/`, check it, sync it, then verify in LocalWP. ## What Is Not Bundled The devkit does not include premium or user-owned runtime files. Install these in your own Local site when your project needs them: | Dependency | Ownership | | --- | --- | | Etch | User-owned runtime plugin. | | Etch Theme | User-owned theme/runtime dependency. | | OhMyEtch | User-owned component plugin. | | AutomaticCSS | User-owned styling system. | | ACF Pro or other CMS field plugins | User-owned CMS dependency. | | Local Blueprints | Private user-created Local artifacts, not Oh My IDEtch release artifacts. | Use `bun run localwp:doctor -- --project ` and `bun run localwp:capabilities -- --project ` before assuming those runtime capabilities are available. ## The Core Loop Every project change follows the same order: ```sh bun run project:check -- --project bun run localwp:sync -- --project ``` After sync, verify against the bound LocalWP site with the browser, WordPress admin, or WP-CLI: ```sh bun run localwp:wp -- --project -- plugin list ``` The check must run before sync. This keeps the Local site from receiving unchecked project source. ## Start Here 1. [Install and Prepare](/oh-my-idetch/localwp-devkit/install-and-prepare) explains what to install before opening the devkit in an agent. 2. [First Project](/oh-my-idetch/localwp-devkit/first-project) walks through `/new-project` and manual setup commands. 3. [Daily Workflow](/oh-my-idetch/localwp-devkit/daily-workflow) covers the build, check, sync, and verify loop. 4. [Command Reference](/oh-my-idetch/localwp-devkit/command-reference) lists every devkit command. 5. [Troubleshooting](/oh-my-idetch/localwp-devkit/troubleshooting) covers the common blockers. 6. [Ship a Plugin ZIP](/oh-my-idetch/localwp-devkit/ship-plugin-zip) explains the production ZIP path. --- ## Install and Prepare The LocalWP Devkit expects you to bring a working Local site and the runtime plugins you own. It is not a Local site import, a Local Blueprint, or a bundle of premium plugin files. ## Prerequisites Install these on your machine before creating a project: | Requirement | Notes | | --- | --- | | LocalWP | Creates and runs the WordPress site. | | Node.js 20 or newer | Required by the devkit package engine and related JavaScript tooling. | | Bun | Runs devkit package scripts. Use the version declared by the devkit `packageManager` field when possible. | | Composer | Used when a project needs PHP dependencies for checks such as PHPStan. If `project:check` reports missing dependencies, run the exact `composer install --working-dir=...` command it prints. | | Git | Recommended for tracking the long-lived devkit workspace and each project under `projects/`. | | The devkit ZIP | Download `oh-my-idetch-localwp-devkit-.zip` from your [OhMyEtch account](https://ohmyetch.com/my-account/). | | User-owned runtime plugins | Etch, Etch Theme, OhMyEtch, AutomaticCSS, ACF Pro, WooCommerce, or other project dependencies as needed. | LocalWP provides the WordPress runtime, PHP, MySQL, WP-CLI Site Shell, SSL, Mailpit, and the bound local domain. The devkit does not replace those services; it runs checks and syncs project source into the Local site. The devkit can continue without optional browser automation. When available, browser automation lets agents open the bound LocalWP domain, inspect pages, and capture screenshots after sync. ## Extract the Devkit Extract the ZIP into a durable working directory: ```text oh-my-idetch-localwp-devkit/ ``` Then install dependencies: ```sh bun install ``` Initialize your own Git history for the devkit workspace: ```sh git init git add . git commit -m "Initial LocalWP devkit" ``` The devkit ships with a `.gitignore`, but it does not ship with your repository history. ## Prepare a Local Site Create or reuse a LocalWP site. Install and activate the runtime dependencies this project needs in that Local site. At minimum, an Etch site normally needs Etch and Etch Theme. If the project uses OhMyEtch components, AutomaticCSS, ACF Pro, WooCommerce, or other plugins, install and license them in Local before expecting the devkit to use those capabilities. You can save a private Local Blueprint after the site is configured: 1. Create a clean Local site. 2. Install and license your user-owned runtime plugins. 3. Confirm the site is ready with `localwp:doctor` after binding a project. 4. In Local, save the site as a Blueprint for your own future work. That Blueprint remains private to you. It is not part of the Oh My IDEtch devkit. ## Open the Right Folder Open the devkit root in your agent: ```text oh-my-idetch-localwp-devkit/ ``` Do not open the synced plugin directory inside the Local site as your working source: ```text ~/Local Sites//app/public/wp-content/plugins/oh-my-idetch ``` That directory is output from `localwp:sync`. Your editable project source lives under `projects/`. --- ## First Project Start a LocalWP-backed project from the devkit root. The easiest path is to let your agent run the built-in onboarding workflow. ## Recommended Agent Flow Open the devkit root in your agent and send: ```text /new-project ``` The agent should ask for only the missing setup details: | Input | How it is used | | --- | --- | | Local site name | The agent matches it against LocalWP sites. | | Build brief | The agent records what the site should become. | | Project slug | Usually inferred from the Local site name. The agent asks only if the inferred slug is invalid, already exists, ambiguous, or you want a custom one. | | Browser automation choice | Optional. Used for page previews and screenshots after sync when not already installed. | If the Local site does not exist, create it in Local first. The devkit does not create Local sites, ship premium plugins, provide licenses, or generate Local Blueprints for you. ## What `/new-project` Does The workflow creates and binds a project, then checks the initial runtime surface before the first sync: ```sh bun run localwp:list bun run project:create -- bun run localwp:bind -- --project --site "" bun run project:check -- --project bun run localwp:sync -- --project bun run localwp:doctor -- --project bun run localwp:capabilities -- --project ``` It may also try to activate the synced plugin: ```sh bun run localwp:wp -- --project -- plugin activate oh-my-idetch ``` If WP-CLI is unavailable because Local has not generated a Site Shell entry, open Local, choose the site, select **Open Site Shell**, and rerun the command or activate the plugin in WordPress admin. ## Manual Setup Use the manual commands when you do not want the agent onboarding flow: ```sh bun run localwp:list ``` Create the project: ```sh bun run project:create -- my-site ``` Bind it to a Local site: ```sh bun run localwp:bind -- --project my-site --site "My Site" ``` Run the first check and sync: ```sh bun run project:check -- --project my-site bun run localwp:sync -- --project my-site ``` Inspect readiness and installed capabilities: ```sh bun run localwp:doctor -- --project my-site bun run localwp:capabilities -- --project my-site ``` ## Project Files After setup, use the project directory as the site source: ```text projects/my-site/ project.json AGENTS.project.md oh-my-idetch.php src/ cms/ tests/ tools/ var/ ``` Keep project-specific brief notes, constraints, runtime expectations, and Local binding notes in `projects/my-site/AGENTS.project.md` so future agent sessions start with the right context. --- ## Daily Workflow The LocalWP Devkit is file-first. Build in the project folder, check the project, sync the runtime plugin copy into LocalWP, then verify against the bound Local site. ## Edit Project Source Work under: ```text projects/ ``` Common project source paths are: | Path | Purpose | | --- | --- | | `src/Site/**` | Etch presentation builders and site composition. | | `cms/acf-json/**` | Field group JSON that can be synced through WordPress. | | `tests/**` | Project-local test support. | | `AGENTS.project.md` | Project brief, Local binding notes, and user-owned runtime expectations. | Do not use the synced Local plugin copy as the source of truth. It is replaced by sync. ## Check Before Sync Run the project verification gate: ```sh bun run project:check -- --project ``` This validates the runtime surface, rejects unsafe links, lints PHP files, and runs PHPStan with a default `1G` memory limit when the project has PHPStan configuration. If the check reports missing PHPStan dependencies, run the exact `composer install --working-dir=...` command it prints, then rerun `project:check`. ## Sync to LocalWP Only sync after the check passes: ```sh bun run localwp:sync -- --project ``` Sync writes the project runtime plugin surface into the bound Local site: ```text wp-content/plugins/oh-my-idetch ``` It does not sync project notes, tests, tools, package metadata, agent files, local environment files, or user-owned premium plugins. ## Verify Runtime Behavior Use the bound LocalWP domain shown by Local or recorded in `project.json`. Do not assume a fixed localhost port. Use WP-CLI through the devkit wrapper: ```sh bun run localwp:wp -- --project -- plugin list bun run localwp:wp -- --project -- option get home ``` Check site readiness: ```sh bun run localwp:doctor -- --project ``` Inspect runtime capabilities: ```sh bun run localwp:capabilities -- --project ``` For visual or interactive work, verify in the browser after sync. OhMyEtch CSS, JavaScript, dropdowns, drawers, facets, Woo Store API behavior, checkout gateways, and fixed runtime styles need the active LocalWP site; project checks alone do not prove those runtime behaviors. ## Safe Agent Handoff When handing a project to an agent, include: - the devkit root path; - the project slug; - the exact Local site name; - the current build brief; - user-owned dependencies that should be active; - whether browser automation is available; - the last `project:check`, `localwp:sync`, `localwp:doctor`, and `localwp:capabilities` result. The agent should start in the devkit root and treat `projects/` as the editable source. --- ## Command Reference Run these commands from the devkit root unless noted otherwise. ## Project Setup ### `/new-project` Starts the agent-guided onboarding flow. Use it when creating or binding a LocalWP-backed project. ```text /new-project ``` The flow matches a Local site, infers a project slug, creates `projects/` when needed, binds it, checks it, syncs it, runs readiness checks, and records project notes. ### `localwp:list` Lists LocalWP sites visible on the machine. ```sh bun run localwp:list ``` Use this before binding when you need the exact Local site name, domain, or path. ### `project:create` Creates a project from the devkit project template. ```sh bun run project:create -- my-site ``` The slug must use lowercase letters, numbers, and dashes. The command fails if the project already exists. ### `localwp:bind` Binds a project to one Local site. ```sh bun run localwp:bind -- --project my-site --site "My Site" ``` You can also bind by site ID or web root when needed: ```sh bun run localwp:bind -- --project my-site --site-id bun run localwp:bind -- --project my-site --web-root "/Users/me/Local Sites/my-site/app/public" ``` Binding writes the Local web root and target plugin path into `projects/my-site/project.json`. ## Build and Sync ### `project:check` Checks the project runtime source before sync or packaging. ```sh bun run project:check -- --project my-site ``` Run this before every sync after changing `src/**` or `cms/**`. ### `localwp:sync` Copies checked runtime plugin files into the bound Local site. ```sh bun run localwp:sync -- --project my-site ``` Sync output goes to the Local site plugin path: ```text wp-content/plugins/oh-my-idetch ``` ## LocalWP and WordPress Inspection ### `localwp:wp` Runs WP-CLI through Local's Site Shell environment when available. ```sh bun run localwp:wp -- --project my-site -- plugin list bun run localwp:wp -- --project my-site -- plugin is-active oh-my-idetch bun run localwp:wp -- --project my-site -- option get home ``` If Local has not generated the shell entry, open Local, select the site, choose **Open Site Shell**, and run the printed fallback command manually. ### `localwp:doctor` Reports project and Local site readiness. ```sh bun run localwp:doctor -- --project my-site ``` It checks binding, web root availability, WP-CLI availability, WordPress environment type, synced plugin state, plugin activation, and runtime plugin status when WP-CLI works. ### `localwp:capabilities` Prints JSON describing active runtime capabilities. ```sh bun run localwp:capabilities -- --project my-site ``` Use it before assuming Etch, OhMyEtch, AutomaticCSS, CMS fields, or WooCommerce support exists in the bound Local site. ## Packaging ### `build:zip -- --project` Checks and packages one project as a production plugin ZIP. ```sh bun run build:zip -- --project my-site ``` The ZIP is written under: ```text projects/my-site/dist/oh-my-idetch-.zip ``` Use this ZIP as the deployable project plugin artifact. --- ## Troubleshooting Most LocalWP Devkit issues fall into four groups: the wrong folder is open, the project is not bound, Local has not exposed WP-CLI automation yet, or required runtime plugins are not installed in the Local site. ## The Agent Is Editing the Wrong Folder Use the devkit root as the agent workspace: ```text oh-my-idetch-localwp-devkit/ ``` Project source lives here: ```text projects/ ``` The synced Local plugin copy is not source: ```text ~/Local Sites//app/public/wp-content/plugins/oh-my-idetch ``` If changes were made directly in the synced plugin copy, move the intended source changes back into `projects/`, then run: ```sh bun run project:check -- --project bun run localwp:sync -- --project ``` ## Project Is Not Bound If `localwp:sync`, `localwp:wp`, or `localwp:doctor` says the project is unbound, bind it to a Local site: ```sh bun run localwp:list bun run localwp:bind -- --project --site "" ``` Use the exact Local site name shown by `localwp:list` or the Local app. ## WP-CLI Is Unavailable `localwp:wp` depends on Local's generated Site Shell entry. If the command prints a fallback, open Local, select the site, choose **Open Site Shell**, then rerun the devkit command. You can still continue with WordPress admin checks when WP-CLI is unavailable. Report the WP-CLI blocker clearly so the next session knows what happened. ## Runtime Plugin Is Missing or Inactive If `localwp:doctor` warns that the plugin root is missing, sync first: ```sh bun run project:check -- --project bun run localwp:sync -- --project ``` Then activate the plugin: ```sh bun run localwp:wp -- --project -- plugin activate oh-my-idetch ``` If WP-CLI is unavailable, activate `oh-my-idetch` in WordPress admin. ## Premium Dependencies Are Missing The devkit does not bundle Etch, Etch Theme, OhMyEtch, AutomaticCSS, ACF Pro, WooCommerce, or other premium/user-owned plugins. Install and license those in the Local site. Check the current runtime state: ```sh bun run localwp:doctor -- --project bun run localwp:capabilities -- --project ``` Missing optional plugins can be warnings when the project does not need them. They are blockers when the build depends on that runtime capability. ## PHPStan Dependencies Are Missing If `project:check` reports a missing PHPStan binary, run the exact Composer command from the error. It will look like: ```sh composer install --working-dir=projects/ ``` Then rerun: ```sh bun run project:check -- --project ``` ## Browser Verification Does Not Work Browser automation is optional. If it was not installed or failed to install, the project can still be created, checked, synced, and verified through LocalWP and WordPress admin. Use the bound LocalWP domain from Local or `project.json`; do not assume a fixed localhost port. ## The Local Site Shows Old Output Confirm that the source changed under `projects/`, not only in the synced plugin copy. Then run the required loop: ```sh bun run project:check -- --project bun run localwp:sync -- --project ``` If the page still shows old output, verify the `oh-my-idetch` plugin is active and the browser is loading the bound LocalWP domain. --- ## Ship a Plugin ZIP When a LocalWP Devkit project is ready to deliver, build a project plugin ZIP from the devkit root: ```sh bun run build:zip -- --project ``` The command runs the project check before packaging. If the check fails, fix the project and rerun the command. ## Output The ZIP is written inside the project: ```text projects//dist/oh-my-idetch-.zip ``` The ZIP root is: ```text oh-my-idetch/ ``` This is the runtime plugin artifact for that project. ## What Goes Into the ZIP The project ZIP contains the runtime plugin surface: | Included | Purpose | | --- | --- | | `oh-my-idetch.php` | WordPress plugin entry file. | | `src/**` | Project runtime PHP source. | | `cms/acf-json/**` | Project CMS field JSON when present. | | `flags.json` | Production mode marker with `MODE=PROD`. | The ZIP does not include devkit tooling, project notes, tests, generated agent skills, local environment files, Local site backups, Local Blueprints, or premium plugin files. ## Before You Ship Run the normal LocalWP verification loop first: ```sh bun run project:check -- --project bun run localwp:sync -- --project bun run localwp:doctor -- --project bun run localwp:capabilities -- --project ``` Then verify the site in LocalWP using the bound Local domain. For WooCommerce, facets, dropdowns, drawers, checkout gateways, or other interactive OhMyEtch behavior, browser/runtime verification is required; the project ZIP command only proves the package can be built from checked source. ## Keep the Devkit Do not duplicate the whole devkit for every site. Keep the devkit as the long-lived workspace and create a new `projects/` folder for each site. Each project can build its own deployable plugin ZIP.