# AGENTS.md: HTML Tool Development Standards

You are a specialist in building **"HTML Tools"**: single-file, serverless, highly portable web applications. Follow these constraints strictly to ensure maximum compatibility and zero-build overhead.

## 1. Core Architecture
- **Single File Only:** All HTML, CSS (in `<style>`), and JavaScript (in `<script>`) must reside in a single `.html` file.
- **No React / No Build Steps:** Do not use React, Vue, Svelte, or any framework requiring JSX, Babel, or a bundler.
- **Vanilla JS & Modern Web APIs:** Favor standard DOM APIs. If a library is essential, use it via a CDN (see below).
- **Small Footprint:** Aim for a few hundred lines of code. If the complexity grows, favor modular Vanilla JS over heavy dependencies.

## 2. Dependencies & Hosting
- **CDN Loading:** Load all external libraries (e.g., PDF.js, Tesseract.js, D3.js) from trusted CDNs like `cdnjs` or `jsdelivr`. Use versioned URLs (e.g., `https://cdn.example.com/lib@1.2.3/dist/min.js`).
- **Static Compatibility:** The code must run when served via `file://` or hosted as a static file on GitHub Pages without any server-side logic.

## 3. Data & State Management
- **URL Persistence:** Use `URLSearchParams` or `location.hash` to store sharable application state (e.g., a configuration or a small amount of input text).
- **Local Storage for Secrets:** Store API keys, user tokens, or large persistent data in `localStorage`.
    - *Security Note:* Never hardcode API keys. Use `prompt()` or a settings UI to ask the user for keys and save them to `localStorage`.
- **CORS APIs:** Use client-side `fetch()` to interact with CORS-enabled APIs (GitHub, PyPI, iNaturalist, etc.).

## 4. User Experience (UX) Patterns
- **Clipboard-First:**
    - Provide "Copy to Clipboard" buttons for all output.
    - Implement `paste` event listeners to handle rich text, images, or files directly from the clipboard.
- **File Handling:** Use `<input type="file">` and `FileReader` to process local files (PDFs, images, CSVs) entirely in the browser.
- **Downloadables:** Generate and trigger downloads using Blob URLs (e.g., for exporting JPEGs from SVGs or generating `.ics` files).

## 5. Advanced Capabilities
- **Wasm & Python:** If complex logic is needed, use WebAssembly (Wasm) ports of existing tools or **Pyodide** to run Python code directly in the browser.
- **Direct LLM Calls:** When requested, implement direct calls to OpenAI, Anthropic, or Gemini APIs from the browser using the user's stored API key via CORS.

## 6. Development Workflow
- **Debugging Tools:** Include basic logging or visual debug states (e.g., showing hidden clipboard formats) to help the user understand how the tool is processing data.
- **Remixing:** If the user provides a previous tool as context, reuse its patterns for CDN loading and state management to maintain consistency.

---

## 7. File & Folder Conventions (this repo)

Every HTML tool lives as a **single `.html` file** inside the `tools/` directory, paired with a **same-named `.md` documentation file**:

```
tools/
  my-tool-name.html
  my-tool-name.md
  another-tool.html
  another-tool.md
```

- **Naming:** use `kebab-case` for file names (e.g., `csv-viewer.html`, `json-formatter.html`).
- **No subdirectories** inside `tools/` — each tool is exactly two files (`.html` + `.md`).
- **Update `index.html`:** After adding a new tool, add a card for it in the `<main>` section of the root `index.html`.

### Doc file (`<tool-name>.md`)

Every tool **must** ship a companion Markdown file with the same base name. It should cover:

```markdown
# Tool Name

One-sentence description.

## Usage

Step-by-step instructions for a new user.

## Inputs & Outputs

What the tool accepts and what it produces.

## Notes

Any caveats, browser requirements, API keys needed, etc.
```

### How to use this file with your Agent
- **For Claude/ChatGPT:** Paste the contents of `AGENTS.md` into the chat and say, "Follow these standards for all subsequent code generation."
- **For Cursor/Windsurf:** This file in the project root is picked up automatically as `.cursorrules`-style guidance.
- **For Claude Code:** Reference this file by name when starting a task: `claude "Build a new tool based on the standards in AGENTS.md"`