HowDoYouConvert/agents/readme.md

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.