# How Do You Convert – AI Agent SOP

This repo now ships a **SvelteKit** experience that renders every conversion locally. All calculator logic lives inside `hdyc-svelte`, and the markdown registry plus a generator script drive the data. There are no external CMS posts, Kadence elements, or REST creates involved in the current deployment flow.

## 1. Architecture overview
- `hdyc-svelte` is a SvelteKit + Node app that renders the homepage, category lists, and every `/[slug]` calculator page via server-side rendering.
- `src/lib/data/calculators.ts` contains every calculator definition (slug, labels, factor, description, visibility, etc.), along with helper functions for lookups, search, and category metadata.
- `unitDefinitions.ts` derives glossary text from the calculator labels so the site can surface contextual descriptions without additional API calls.

## 2. The canonical registry (`calculators_list.md`)
- The **Active Calculators** table at the top is the single source of truth for every published conversion. Only entries listed here will appear in the generated data. Update this table before making any frontend changes.
- Column guidance:
  - **Calculator Name**: keep the existing “Name – descriptive teaser” format. The human-friendly phrase after the dash becomes the page subtitle.
  - **Page Post ID / Kadence JS Element ID**: vestigial metadata from the previous architecture. Preserve the existing values if known, but the Svelte pipeline ignores them; you can leave them blank if you do not know them.
  - **Slug**: lowercase, dash-separated, and unique. `migrate.py` uses this as the canonical identifier, so avoid spaces or special characters.
  - **Conversion Factor**: this column is the only information `migrate.py` uses to infer the math. Simple multiplicative conversions should use the numeric multiplier that transforms the first unit into the second. Use `Linear Offset (m x + b)` when a fixed offset exists (e.g., `Linear Offset (1.8x + 32)` for Celsius → Fahrenheit), `1/x` for reciprocal conversions, `Multi-Variable` for compound calculators (amps, watts, lux, etc.), and tokens like `10_to_2`, `16_to_10`, `N/A (Text)`, or `Base` for number-system helpers. The script has heuristics built in for the most common patterns; if your calculator is unusual, see section 3 before rerunning.
- After the active table ends, keep the **Backlog** checklist intact. Move a row from the backlog into the table when it is ready for publication, then rerun the generator so the new slug actually ships.

## 3. Generating the calculator data
- Every edit to the registry must be followed by `python migrate.py` executed from the repository root. The script reads `calculators_list.md`, applies heuristics to determine category/type/labels, and produces the updated `hdyc-svelte/src/lib/data/calculators.ts` file.
- `calculators.ts` is fully generated; **do not edit it by hand**. If a converter needs a special factor, offset, extra label, base conversion, or text description, adjust the registry row (or the generator logic) so the next run emits the correct values.
- The script automatically adds `hidden` flags for duplicate reverse conversions, infers decimal vs. binary data scales, and embeds any available descriptive paragraphs, so confirm the generated `descriptionHTML` block if you expect custom SEO copy.

## 4. Development & verification
- Install dependencies inside `hdyc-svelte`: `cd hdyc-svelte && npm install` (or use your preferred package manager).
- Run `npm run dev` for a local server, then open `/` and `/[slug]` in your browser to confirm the new conversion behaves bidirectionally.
- Before committing, run `npm run check` from `hdyc-svelte` to ensure TypeScript and Svelte checks pass. A production build uses `npm run build`; preview it with `npm run preview` if you want to inspect the output bundle.
- When verifying a new calculator, test both directions, check the formula in the UI, and confirm the glossary/description text reads correctly. If the description needs editing, update the generator source (see section 3) instead of touching the compiled file.

## 5. What's next
- Every change involves at least these files: `calculators_list.md` (registry), `migrate.py` output (`hdyc-svelte/src/lib/data/calculators.ts`), and any touched component or route within `hdyc-svelte/src/routes`.
- Document any unusual heuristics you add to `migrate.py` so future contributors understand why certain entries require manual adjustments.
- Keep the backlog alive: it is the easiest way to hand off upcoming conversions without cluttering the active registry.