# How Do You Convert - Agents Documentation

This document explicitly defines the schema, architecture, and standard operating procedure for creating new calculators on `howdoyouconvert.com`.

## 1. WordPress Environment Structure
The calculators are managed using the custom post type `calculator`. The REST API endpoint allows full CRUD operations:
- **Base Endpoint**: `/wp-json/wp/v2/calculator`
- Authentication is handled via Application Passwords `base64(username:password)` utilizing Basic Auth via HTTP Headers. 
- *Crucial Node*: API requests to this endpoint must emulate browser requests via the `User-Agent` string (e.g., `Mozilla/5.0...`) or they will be blocked by Cloudflare (error 1010).

## 2. Calculator Data Payload (HTML)
Calculators should use Kadence Block layout components to match the pre-existing grid on the site. Each calculator contains 2 main columns for bidirectional conversion. 
All calculators *MUST* include the classes `calc-input` and `calc-field` on their `<input type="number">` tags, and unique IDs across the form (e.g. `input-1`, `input-2`). The UI should contain explicit labels. 

**Example JSON Payload Configuration:**
```json
{
  "title": "Unit A to Unit B",
  "status": "publish",
  "slug": "unita-to-unitb",
  "content": "<!-- Standard Kadence 2-Column Row Block -> Column 1 (Label + Input) -> Column 2 (Label + Input) -> SEO Text Block -->"
}
```

### 2.2. Slug Mismatch & Duplicate Prevention
**CRITICAL**: Do not create a new post if the calculator already exists. WordPress will automatically append `-2` to the slug (e.g., `inches-to-millimeters-2`).
- **Detection**: Always perform a GET request for the intended slug before POSTing.
- **Resolution**: If a duplicate is found, capture the existing `id` and use `PUT` to update the content rather than creating a new entry.
- **Registry**: Ensure the `Id` in `calculators_list.md` matches the post serving the "clean" slug (no `-2`).

### 2.1. SEO Copy Guidelines
The SEO block appended at the end of the calculator `content` must strictly adhere to the following style:
- **Length**: Expand the text to 2-3 detailed paragraphs providing educational information on the units involved, their history, uses, and the conversion methodologies.
- **Tone**: The text must be strictly informative and **non-self-referential**. Do not refer to the calculator widget itself. Sentences like "This handy calculator automatically converts values as you type" or "Enter your value below" are explicitly prohibited.

## 3. JavaScript Event Injection
The JavaScript that performs the actual mathematical conversion is *detached* from the calculator post itself. It is managed via the **Kadence Elements** system (`kadence_element` custom post type).

### Creating the Logic Hook
Whenever a new calculator is created:
1. Capture the returned `id` of the published calculator.
2. Formulate the JS math conversion script wrapping events to the unique input IDs.
        init();
    })();
    </script>
    ```

### 3.1. 3-Variable Solver Pattern (e.g., Ohm's Law)
For calculators with 3 inputs (A, B, C where A * B = C), use the "solve" function pattern to ensure reactivity:
```javascript
function solve(lastId) {
    let av = parseFloat(a.value), vv = parseFloat(v.value), wv = parseFloat(w.value);
    if (lastId === '1' || lastId === '2') {
        if (!isNaN(av) && !isNaN(vv)) w.value = parseFloat((av * vv).toFixed(3));
    } else if (lastId === '3') {
        if (!isNaN(wv)) {
            if (!isNaN(av) && av !== 0) v.value = parseFloat((wv / av).toFixed(2));
            else if (!isNaN(vv) && vv !== 0) a.value = parseFloat((wv / vv).toFixed(2));
        }
    }
}
a.oninput = () => solve('1'); v.oninput = () => solve('2'); w.oninput = () => solve('3');
```
4. **URL Parameter Support:** Ensure the script parses `window.location.search` for `?v1=` (Input 1) and `?v2=` (Input 2).
5. Submit a new `kadence_element` POST request injecting the `<script>...</script>`.
6. Apply these required metadata values:
    - `_kad_element_hook`: `kadence_after_header`
    - `_kad_element_show_conditionals`: `'[{"rule":"singular|calculator","select":"ids","ids":[<CALCULATOR_POST_ID>],"mustMatch":false}]'`

## 4. Required Mathematical Verification
After the Kadence Element is injected and the calculator is live, **you must verify the math works in both directions** using the live WordPress post.
1. Determine a known "Unit A to Unit B" conversion (e.g., 1 inch = 2.54 cm).
2. Execute an HTTP/URL request simulating the Unit A input (e.g., `?v1=1`) and verify the output accurately reflects Unit B.
3. Reverse the test: simulate the Unit B input (e.g., `?v2=2.54`) and verify the output accurately reflects Unit A.
4. If either math direction fails or produces precision floating-point inaccuracies, you must correct the Kadence Element JavaScript block.
5. **Live Logic Audit**: View the page source and search for `<!-- [element-ID] -->`. Ensure the ID matches the one in the registry and contains the robust `init` pattern.

## 4. Calculator Registry
To avoid unnecessary scraping of the REST API, immediately update the `calculators_list.md` file located in the workspace directory with the details (Title, Post ID, Kadence Element ID) upon successful deployment.

*By adhering to these steps, all calculators will natively match the design and function gracefully without requiring direct plugin access.*