<!-- Provided as-is by Apollo Lens Solutions LLC under the Download Terms at https://apollolens.io/downloads -->

# Claude.md — Single-File HTML Application

## Project Overview

This is a **standalone, single-file HTML application** (internal tool / dashboard). Everything — HTML structure, CSS styles, and JavaScript logic — lives in **one `.html` file** with no external dependencies, no build step, and no backend.

The developer (John) is the domain expert and product visionary. Claude Code is the technical lead. **Always explain technical decisions in plain language alongside the code.**

---

## Hard Rules

1. **One file only.** All markup, styles, and scripts go in `index.html`. No separate `.css` or `.js` files. No imports, no npm, no bundlers.
2. **Zero external dependencies.** No CDN links, no framework scripts, no Google Fonts links. Everything is self-contained so it works offline and without a network.
3. **Vanilla only.** Plain HTML, CSS, and JavaScript. No React, no jQuery, no Tailwind, no libraries.
4. **No backend calls.** No `fetch()` to remote APIs, no Supabase, no authentication. Data lives in the browser (variables, `localStorage`, or user-supplied file input).
5. **Single responsibility per prompt.** When asked to add a feature, implement *only* that feature. Do not refactor unrelated code, rename existing functions, or "improve" things that weren't requested.

---

## Code Architecture

### File Structure (inside the single file)

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>APP_NAME</title>
  <style>
    /* ===== CSS RESET ===== */
    /* ===== CSS CUSTOM PROPERTIES (VARIABLES) ===== */
    /* ===== LAYOUT ===== */
    /* ===== COMPONENTS ===== */
    /* ===== UTILITIES ===== */
    /* ===== DARK MODE (if applicable) ===== */
  </style>
</head>
<body>

  <!-- ===== MARKUP ===== -->

  <script>
    // ===== STATE =====
    // ===== DOM REFERENCES =====
    // ===== HELPER FUNCTIONS =====
    // ===== CORE LOGIC =====
    // ===== EVENT LISTENERS =====
    // ===== INITIALIZATION =====
  </script>
</body>
</html>
```

### Conventions

- **CSS variables** for all colors, spacing, and font sizes — defined in `:root`. This makes theming and future dark-mode trivial.
- **Semantic HTML** (`<header>`, `<main>`, `<section>`, `<nav>`, `<table>`, `<form>`) — not `<div>` soup.
- **`data-*` attributes** for JS hooks instead of coupling to CSS class names.
- **Functions stay small.** Each function does one thing. Name it clearly: `calculateTolerance()`, `renderTable()`, `handleFileUpload()`.
- **Comments mark every section.** Use the `// ===== SECTION =====` pattern so John can navigate the file quickly.
- **No magic numbers.** Put thresholds, limits, and config values in a `CONFIG` object at the top of the `<script>` block.

```js
const CONFIG = {
  MAX_ROWS: 500,
  TOLERANCE_DEFAULT: 0.02,
  APP_VERSION: '0.1.0',
};
```

---

## Styling Defaults

- **Font stack:** `system-ui, -apple-system, sans-serif` (no external fonts).
- **Monospace for data:** `'Courier New', monospace` for numeric values, code, and IDs.
- **Accessible contrast:** Minimum 4.5:1 ratio for text on background.
- **Responsive:** Use CSS Grid or Flexbox. The dashboard should be usable at 1024px and above; gracefully stack at smaller widths.
- **No horizontal scrolling** on the page body.

---

## JavaScript Guidelines

- Use `const` and `let` — never `var`.
- Use modern syntax: arrow functions, template literals, destructuring, optional chaining (`?.`), nullish coalescing (`??`).
- **No `document.write()`**. Build DOM with `createElement` + `appendChild`, or set `innerHTML` on a container (acceptable for templates in a single-file app).
- **Event delegation** where practical — attach one listener to a parent rather than one per row/button.
- Always wrap initialization in `DOMContentLoaded`:

```js
document.addEventListener('DOMContentLoaded', () => {
  init();
});
```

---

## Data Handling

- **In-memory first.** Store working data in plain JS objects/arrays.
- **`localStorage`** for persistence across page reloads (if requested). Always JSON-serialize and wrap in try/catch.
- **File I/O via `<input type="file">`** for CSV/JSON import. Provide a **download/export** button that creates a Blob and triggers a download link.
- Never assume data shape — validate and surface clear error messages if input is malformed.

---

## Change Management

- **Before editing**, briefly state *what* you're changing and *why* in plain English.
- **After editing**, summarize what changed and call out anything John should test.
- If a requested change would break an existing feature, say so and propose an alternative — don't silently overwrite.
- When the file grows large (500+ lines), proactively suggest which sections could be collapsed behind `<details>` in the UI or reorganized with clearer section headers.

---

## Explanations

When writing or modifying code, include a short **"What this does"** comment block above non-obvious sections. Target two audiences:

```js
// --- What this does ---
// Layman: Reads the uploaded CSV, checks each row for missing values, 
//         and highlights bad rows in red.
// Technical: Parses CSV via split(), validates against required-field 
//            schema, applies .error class to <tr> elements that fail.
```

This dual-comment pattern is **required** for any block of logic more complex than simple assignment or a single DOM manipulation.

---

## Testing & Validation

- After every change, confirm the file is **valid HTML** (no unclosed tags, no orphaned scripts).
- If the app has user input, handle edge cases: empty input, extremely long strings, special characters, and duplicate entries.
- If the app does math, confirm with at least one hand-verified example in a code comment.

---

## Out of Scope (do NOT introduce unless explicitly asked)

- Frameworks or libraries (React, Vue, Alpine, htmx, jQuery, D3, Chart.js, etc.)
- Build tools (Vite, Webpack, esbuild, etc.)
- TypeScript
- CSS preprocessors (Sass, Less)
- Backend calls or authentication
- Service workers or PWA manifest
- Web components / Shadow DOM
