HowDoYouConvert/agents/readme.md

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:

{
  "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.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.
3. CRITICAL: URL Parameter Support: Ensure the script listens to the DOM DOMContentLoaded event and parses the window.location.search URL query parameters for ?v1= (Input 1) and ?v2= (Input 2). If present, the corresponding input must be automatically populated and the calculation function triggered.
4. Submit a new kadence_element POST request injecting the <script>...</script>.
5. Apply these required metadata values so it correctly loads on your specific calculator:
   • _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.

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.