DenisValeev · Copilot · Apr 3, 2026
diff --git a/ai-docs/README.md b/ai-docs/README.md
@@ -0,0 +1,22 @@
+# AI Docs — Toolbox Reference
+
+This directory contains Markdown documentation written for AI agents and automated tools working on the **denisvaleev.github.io** toolbox. It covers the project's purpose, layout, coding conventions, individual apps, data maintenance workflows, and testing infrastructure.
+
+## Index
+
+| File | Contents |
+| --- | --- |
+| [project-overview.md](project-overview.md) | What the project is, repository layout, and key ideas |
+| [architecture.md](architecture.md) | Landing page, service worker, offline manifest, and data loading |
+| [apps-catalog.md](apps-catalog.md) | Every app: purpose, key files, data dependencies, and test coverage |
+| [data-and-tools.md](data-and-tools.md) | Datasets, Node maintenance scripts, and step-by-step workflows |
+| [testing.md](testing.md) | Playwright specs, npm scripts, and CI automation |
+| [development-conventions.md](development-conventions.md) | Coding style, accessibility rules, and how to add new apps |
+
+## Quick-start for agents
+
+1. Read `project-overview.md` to understand the repository layout.
+2. Read `development-conventions.md` before touching any HTML, CSS, or JS.
+3. After editing datasets, follow the workflow in `data-and-tools.md`.
+4. After any code change, run `npm test` (see `testing.md`).
+5. When adding a new app, consult `apps-catalog.md` for the established pattern and update `index.html`, `offline-manifest.json`, and `docs/docs/apps.md`.
diff --git a/ai-docs/apps-catalog.md b/ai-docs/apps-catalog.md
@@ -0,0 +1,184 @@
+# Apps catalog
+
+Each app lives under `apps/<name>/`. The sections below describe the purpose, key files, data dependencies, and Playwright coverage for every tool.
+
+---
+
+## Dad Jokes (`apps/jokes`)
+
+**Purpose.** Shuffle a curated deck of developer-friendly jokes, reveal punchlines on demand, and browse the full archive in a searchable table.
+
+**Key files.**
+- `index.html` — Deck UI with shuffle, prev, next controls and a punchline toggle.
+- `app.js` — Shuffles the dataset, renders the active joke, wires keyboard shortcuts (`ArrowLeft`, `ArrowRight`, `Space`), and guards for missing DOM nodes.
+- `jokes.js` — Dataset: `window.jokes = [{ joke, punchline, id, sourceId }, ...]`.
+- `all-jokes.html` + `render-all.js` — Archive table with search, filter, and a `data-count` badge.
+- `AGENTS.md` — Dataset validation commands and maintenance notes.
+
+**Data dependencies.** `data/jokes-manifest.json`, `data/jokes-embeddings*.json`, `data/similarity-report-jokes*.json`.
+
+**Test coverage.** `tests/jokes.spec.js`, `tests/jokes-dataset.spec.js`, `tests/jokes-all.spec.js`, `tests/home-navigation.spec.js`.
+
+---
+
+## Quotes (`apps/quotes`)
+
+**Purpose.** Surface themed quote decks, reveal full attribution, and maintain deterministic metadata for deduplication analysis.
+
+**Key files.**
+- `index.html` — Shuffle UI mirroring the jokes experience.
+- `app.js` — Active deck management, keyboard shortcuts, attribution toggle.
+- `quotes-data.js` — Dataset: `window.quotesData = [{ text, author, tags, id }, ...]`.
+- `all-quotes.html` + `render-all.js` — Archive table with filters and count badge.
+- `AGENTS.md` — Validation commands.
+
+**Data dependencies.** `data/quotes-manifest.json`, `data/quotes-embeddings*.json`, `data/similarity-report-quotes*.json`, `data/similarity-overrides.json`.
+
+**Test coverage.** `tests/quotes.spec.js`, `tests/quotes-data.spec.js`, `tests/quotes-all.spec.js`, `tests/home-navigation.spec.js`.
+
+---
+
+## Slang (`apps/slang`)
+
+**Purpose.** Educate visitors on trending internet slang with reveal-on-demand definitions and a searchable archive.
+
+**Key files.**
+- `index.html` + `app.js` — Shuffle UI and reveal toggle targeting `window.slangEntries`.
+- `slang.js` — Dataset: `window.slangEntries = [{ term, definition, id }, ...]`.
+- `all-slang.html` + `render-all.js` — Archive listing with search and count badge.
+- `AGENTS.md` — Threshold settings and validation notes.
+
+**Data dependencies.** `data/slang-manifest.json`, `data/slang-embeddings*.json`, `data/similarity-report-slang*.json`.
+
+**Test coverage.** `tests/slang-app.spec.js`, `tests/slang-dataset.spec.js`, `tests/slang-all.spec.js`, `tests/home-navigation.spec.js`.
+
+---
+
+## Cosine Similarity Lab (`apps/similarity-report`)
+
+**Purpose.** Visualise cosine-similar pairs across jokes, quotes, and slang. Toggle datasets and providers, adjust the minimum score, and inspect per-entry vector statistics.
+
+**Key files.**
+- `index.html` — Standalone HTML+JS document that fetches and renders similarity reports.
+
+**Data dependencies.** `data/similarity-report-*.json`, `data/similarity-overrides.json`.
+
+**Regenerate.** `node tools/review-content-similarity.js` with the appropriate `--dataset` and `--provider` flags.
+
+**Test coverage.** `tests/similarity-report.spec.js`.
+
+---
+
+## Asset Observatory (`apps/asset-observatory`)
+
+**Purpose.** Dashboard for dataset counts, embedding stores, similarity report stats, and upstream sources powering the toolbox.
+
+**Key files.**
+- `index.html` — Layout for cards, provider summaries, cross-deck rollups, and ledger table.
+- `app.js` — Loads `asset-data.js`, renders the dashboard, and wires filter controls.
+- `asset-data.js` — Machine-generated snapshot from `tools/generate-asset-report.js`.
+- `AGENTS.md` — Regeneration command and regression checks.
+
+**Regenerate.** `node tools/generate-asset-report.js` whenever datasets, embeddings, or similarity reports change.
+
+**Test coverage.** `tests/asset-observatory.spec.js`.
+
+---
+
+## Embedding Explorer (`apps/embedding-explorer`)
+
+**Purpose.** Inspect stored embedding vectors, compare records, and visualise high-impact dimensions via histograms and heatmaps.
+
+**Key files.**
+- `index.html` — Dashboard with dataset selector, record filter, neighbor list, and dual canvas plots.
+- `app.js` — Decodes base64 vectors, computes statistics, renders charts, highlights strongest dimensions.
+- `sample-embeddings.js` — Bundled sample definitions: `window.embeddingSources`.
+
+**Data dependencies.** Reads live embedding stores from `data/` when available.
+
+**Test coverage.** `tests/embedding-explorer.spec.js`.
+
+---
+
+## Value Formatter (`apps/value-formatter`)
+
+**Purpose.** Transform newline-separated values into templated output for quick copy/paste in code reviews or data preparation.
+
+**Key files.**
+- `index.html` — Single-page UI with preset transforms, custom script inputs, and persisted textarea state via `localStorage`. All logic lives inline.
+
+**Data dependencies.** None. Persists user input in `localStorage`.
+
+**Test coverage.** `tests/value-formatter.spec.js`.
+
+---
+
+## Wiki (`apps/wiki`)
+
+**Purpose.** Browse a curated collection of articles rendered in the browser.
+
+**Key files.**
+- `index.html` — App shell and navigation.
+- `app.js` — Article loading and rendering logic.
+- `articles/` — Individual article files.
+
+**Test coverage.** Covered by `tests/home-navigation.spec.js`.
+
+---
+
+## Total Recall (`apps/total-recall`)
+
+**Purpose.** Interactive recall or memorisation tool.
+
+**Key files.**
+- `index.html` — Full app with inline styles.
+- `app.js` — Core interaction logic.
+
+**Test coverage.** Covered by `tests/home-navigation.spec.js`.
+
+---
+
+## Enchanted Forest Bunny (`apps/enchanted-bunny`)
+
+**Purpose.** An interactive animated forest-bunny toy with touch/pointer interactivity, designed for mobile home-screen install (PWA-lite via `apple-mobile-web-app-capable`).
+
+**Key files.**
+- `index.html` — Full app (2000+ lines) with inline CSS, canvas animations, and self-contained JS.
+- `apple-touch-icon.png` — Home-screen icon.
+
+**Theming.** Uses `color-scheme: only light` with a deep forest palette.
+
+**Test coverage.** `tests/enchanted-bunny.spec.js`, `tests/home-navigation.spec.js`.
+
+---
+
+## Moonpetal Bunny Choir (`apps/bunny-moon-choir`)
+
+**Purpose.** An atmospheric animated toy featuring bunnies in a moonlit scene.
+
+**Key files.**
+- `index.html` — Self-contained HTML with inline CSS and JS. Uses `color-scheme: only light`.
+
+**Test coverage.** Covered by `tests/home-navigation.spec.js`.
+
+---
+
+## Cloth Lab (`apps/cloth`)
+
+**Purpose.** Real-time physics-based cloth simulator. Users can drag, pin, and slice the cloth.
+
+**Key files.**
+- `index.html` — App shell with semantic markup and control panel.
+- `main.js` — Physics engine and canvas rendering.
+- `styles.css` — External stylesheet (the only app to use a linked CSS file instead of inline styles).
+
+**Test coverage.** Covered by `tests/home-navigation.spec.js`.
+
+---
+
+## Landing page integration rules
+
+- Every app must expose a **Home** link pointing to `../../` so `tests/home-navigation.spec.js` passes.
+- Each app needs a card in `index.html` (`<a class="app-card">` in the `<ul class="apps">` list, or an `<a class="app-button">` in the tools section).
+- New assets must be included in `offline-manifest.json` via `npm run build:offline`.
+- Add or extend Playwright specs under `tests/` for any new interactive surface.
diff --git a/ai-docs/architecture.md b/ai-docs/architecture.md
@@ -0,0 +1,66 @@
+# Architecture
+
+## Landing page (`index.html`)
+
+- **Layout.** Renders the Toolbox banner and two groups: deck-based apps (jokes, quotes, slang) as `.app-row` rows, and utilities/toys as `.tool-list` entries and standalone buttons.
+- **Theming.** CSS custom properties under `:root` define the light palette. A `@media (prefers-color-scheme: dark)` block overrides them. No JavaScript is needed for theme switching.
+- **App cards.** Each card is an `<a class="app-card">` (or `<a class="app-button">`) with an inline SVG chevron icon. The grid auto-wraps via CSS Grid.
+- **Developer shortcuts.** A `.dev-tools` section contains smaller utility links for archive pages and secondary views.
+- **Offline call-to-action.** A card with `data-offline-card` shows bundle metadata and a "Refresh offline bundle" button. A `<progress>` bar pinned to the top communicates download progress through `aria-live` updates.
+- **Bootstrap script.** A script near `</body>` registers `service-worker.js`, fetches `offline-manifest.json`, surfaces bundle stats, and wires the reset button.
+
+## Offline manifest (`offline-manifest.json`)
+
+- **Generated by** `node tools/generate-offline-manifest.js` (`npm run build:offline`).
+- Lists every HTML, JavaScript, and JSON asset shipped with the site.
+- Each entry includes the relative path, byte size, and content hash.
+- A top-level `version` key (ISO 8601 timestamp) doubles as the service worker cache suffix.
+- A top-level `sha256` key is a combined digest for the whole bundle, used to detect staleness.
+- Must be regenerated whenever any file under `apps/`, `data/`, or `index.html` changes.
+
+## Service worker (`service-worker.js`)
+
+- **Cache naming.** `toolbox-offline-v<version>` where `<version>` matches the manifest. The active version is persisted in `toolbox-offline-metadata` so it survives worker restarts.
+- **Install.** Calls `skipWaiting()` so the newest worker activates immediately.
+- **Activate.** Reads the stored manifest, deletes stale cache entries, and calls `clients.claim()`.
+- **Fetch handling.**
+  - Navigation requests fall back to the cached `index.html` when offline.
+  - `offline-manifest.json` requests are intercepted so the worker can serve a stale copy while streaming the latest version in the background.
+  - Static assets are served from cache first; a network fallback backfills the cache entry.
+- **Messages.**
+  - `apply-manifest` — queues a cache refresh from the provided manifest payload.
+  - `reset-offline-cache` — clears all caches and re-runs manifest application from scratch.
+- **Progress reporting.** Posts structured messages (`{ type, cached, total, bytes, totalBytes }`) back to the landing page. The page pipes these into the progress meter and the offline summary card.
+
+## Data loading patterns
+
+### Deck apps (jokes, quotes, slang)
+
+Dataset files (`jokes.js`, `quotes-data.js`, `slang.js`) assign arrays to `window.*` globals:
+
+```js
+window.jokes = [ { joke: "...", punchline: "..." }, ... ];
+```
+
+Each app's HTML loads the dataset via `<script src="jokes.js" defer>` and reads the global synchronously during initialisation after `DOMContentLoaded`.
+
+### Analytics apps (similarity report, asset observatory)
+
+These apps load JSON snapshots from `data/` at runtime using `fetch()`. The snapshots are regenerated by `tools/review-content-similarity.js` and `tools/generate-asset-report.js`.
+
+### Embedding explorer
+
+Bundled sample definitions live in `apps/embedding-explorer/sample-embeddings.js` as `window.embeddingSources`. When live embedding stores are available under `data/`, the app decodes their base64 payloads to compute per-vector statistics.
+
+## Asset pipeline summary
+
+```
+Edit dataset (apps/.../*.js)
+  └─> node tools/update-content-metadata.js   # IDs + manifests under data/
+  └─> node tools/review-content-similarity.js # embeddings + similarity reports
+  └─> node tools/generate-asset-report.js     # apps/asset-observatory/asset-data.js
+  └─> npm run build:offline                   # offline-manifest.json
+  └─> npm test                                # Playwright smoke tests
+```
+
+Each step produces artefacts that the next step (and the deployed site) depends on. Always run the full chain — or the relevant subset — after any dataset change.