# Getting Started Guide

This guide is designed to help you quickly set up the development environment for the **WP Scratch** theme. Whether you are starting fresh or returning to the project after a break, follow these steps to get back to a working state.

## Prerequisites

Before you begin, ensure you have the following installed:

1.  **Local WordPress Environment:** We recommend [LocalWP](https://localwp.com/).
2.  **Node.js & NPM:** Required for Tailwind CSS and build tools. Download from [nodejs.org](https://nodejs.org/).
3.  **Visual Studio Code:** Recommended IDE.
4.  **PowerShell:** Required for running the utility scripts (standard on Windows).

---

## Step-by-Step Setup

### 1. Clone & Install

1.  **Clone the Repository:**
    Clone this theme repository into your local WordPress site's themes directory (e.g., `.../app/public/wp-content/themes/wp-scratch`).

2.  **Open in VS Code:**
    Open the `wp-scratch` folder in Visual Studio Code.

3.  **Scaffold Configuration:**
    If this is a fresh clone, you might be missing local configuration files (like `.env`, `tailwind.config.js`, etc.). We have a utility script to generate these for you.
    
    Run the following command in your terminal:
    ```bash
    npm run scaffold
    ```
    *This will generate a `/generated` folder containing all necessary config files. You can then copy the ones you need into the root directory.*

4.  **Install Dependencies:**
    Now that your `package.json` is ready (or generated), install the Node.js dependencies:
    ```bash
    npm install
    ```
    *This downloads Tailwind CSS, PostCSS, and other build tools into `node_modules`.*

### 2. Configure Environment

1.  **Setup `.env`:**
    If you haven't already, create a `.env` file in the theme root (or copy from `/generated/.env`).
    *   **`SITE_URL`:** Update this to match your LocalWP site URL (e.g., `http://wp-scratch.local`). This is critical for the "Critical CSS" generation.
    *   **FTP Credentials:** If you plan to use the deployment script, add your FTP details here.

2.  **Tailwind Configuration:**
    Ensure `tailwind.config.js` exists in the root. This file controls your design system.
    *   *Tip:* If you need to reset to the default configuration, you can grab the boilerplate from `/generated/tailwind.config.js` after running the scaffold script.

### 3. Start Development

1.  **Start the Watcher:**
    Run the development server to watch for changes in your files and automatically rebuild the CSS:
    ```bash
    npm run dev
    ```
    *You should see a message indicating that Tailwind is watching for changes.*

2.  **Verify Sync:**
    *   Open `src/input.css` and add a test style or modify a class in a template file.
    *   Check `style.css` to ensure it updated.
    *   Refresh your local WordPress site to see the changes.

### 4. Theme Configuration (`theme.json`)

The `theme.json` file is the source of truth for your WordPress editor styles (colors, fonts, layout).
*   **Syncing:** We manually sync `theme.json` settings with `tailwind.config.js` to ensure the editor and front-end match.
*   **Colors:** Defined in `settings.color.palette`.
*   **Typography:** Defined in `settings.typography`.

---

## Common Tasks

*   **Create a New Block:**
    ```powershell
    .\scripts\newblock.ps1 -Name "my-new-block"
    ```

*   **Build for Production:**
    ```bash
    npm run build
    ```
    *This minifies CSS and generates Critical CSS.*

*   **Bundle & Deploy:**
    ```bash
    npm run bundle -- -Upload
    ```
    *Zips the theme and uploads it to the FTP server defined in `.env`.*