# Playground — experiment repo

This folder holds **experiment results**, not an app. Each experiment is a self-contained folder: its raw outputs (logs, data, scripts, screenshots) plus an `index.html` that documents it. There is no build step, no package manager, no server. Pages are plain static HTML opened directly in a browser (`file://`).

## Layout

```
playground/
├── AGENTS.md            # this file (CLAUDE.md points here)
├── render.yaml          # Render static-site config (deploys on push)
├── index.html           # list of all experiments (cards with live preview)
├── style/               # optional shared visual system: reference, not a rule
│   ├── style.css
│   ├── STYLE_GUIDE.md
│   ├── index.html       # live component reference
│   └── example.html     # one possible experiment page
└── <experiment-slug>/
    ├── index.html       # the experiment write-up
    └── ...              # anything: *.log, *.csv, *.json, scripts, images
```

## Rules (repo mechanics only)

These are the only hard rules. They keep the repo navigable; none of them constrain what an experiment page looks like.

1. **One folder per experiment.** Name it `YYYY-MM-<kebab-slug>` (e.g. `2026-11-prompt-caching-latency`) so folders sort by date.
2. **Every experiment folder has an `index.html`.**
3. **Raw outputs stay as files** in the folder, and are never edited or "cleaned up" after the run. They are the evidence.
4. **Register the experiment in the root `index.html`**: copy the template `<article>` card from the HTML comment inside `#exp-grid` to the top of the grid (newest first). Replace `SLUG` with the folder name in the iframe `src` and link `href`, set `data-status` to `done` / `progress` / `failed` / `idea` with the matching badge from the comment. Counts, empty state, search and filter update automatically.
5. **Links must work over `file://`**: link to `folder/index.html`, never to a bare `folder/`, which won't open the page without a server.
6. Don't modify `style/` unless the task is about the style system itself.

## Experiment `index.html`: full creative freedom

There is **no required format, structure, layout, section list, or visual style** for an experiment page. Design each page around what that experiment needs to communicate. A benchmark might be one big chart; a debugging session might read like a field report; a UI prototype might be the prototype itself; a failed idea might be three paragraphs. All are fine.

You decide:

- **UI and visual design**: any layout, colors, fonts, typography, animation, dark or light, minimal or rich.
- **Content**: what to include, what to leave out, how much detail.
- **Structure**: sections, order, single page or tabs, narrative or dashboard.
- **Format**: prose, tables, charts, transcripts, interactive widgets, embedded media, anything a browser can render.
- **Tooling**: plain CSS, inline SVG, canvas, or a library from a CDN if the page genuinely benefits from it.

### `style/` is a reference, not a requirement

`style/` exists to save time when it helps, never to constrain. Use it fully, use parts of it, override it, or ignore it entirely and write your own CSS.

If you want to use it:

- Link `../style/style.css` (pages live one level down) plus the Google Fonts link from `style/STYLE_GUIDE.md`.
- `style/index.html` has a live demo + HTML snippet of every component: metrics, CSS-only charts, tables, hypothesis/verdict cards, timelines, LLM transcripts, log viewer, diff, cards/buttons/alerts in 8 tones, 13 color scales, type scale, 145 icons (click to copy SVG).
- `style/example.html` and `2026-11-galaxy-watch4-debloat/index.html` are two examples of finished pages. They show one way to do it, not the way.

### Worth considering (suggestions, not requirements)

A reader landing on the page usually wants to know what was tested, what happened, and where the raw files are. How (or whether) you answer that is up to you. Linking to the raw files in the folder is almost always useful. A failed experiment is still a result; documenting it is welcome.