diff --git a/ai-docs/README.md b/ai-docs/README.md
new file mode 100644
index 0000000..6e8bf74
--- /dev/null
+++ 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
new file mode 100644
index 0000000..cd942c3
--- /dev/null
+++ 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
new file mode 100644
index 0000000..a91ad6c
--- /dev/null
+++ 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.
diff --git a/ai-docs/data-and-tools.md b/ai-docs/data-and-tools.md
new file mode 100644
index 0000000..e317f21
--- /dev/null
+++ b/ai-docs/data-and-tools.md
@@ -0,0 +1,181 @@
+# Data and tools
+
+## Data directory (`data/`)
+
+| File(s) | Description |
+| --- | --- |
+| `jokes-manifest.json` | Deterministic manifest for the jokes deck: record hashes, IDs, total count, embedding metadata. |
+| `quotes-manifest.json` | Same for quotes. |
+| `slang-manifest.json` | Same for slang. |
+| `jokes-embeddings.json` | Synthetic/deterministic embedding store keyed by record ID. |
+| `jokes-embeddings-openai.json` | OpenAI embedding store. |
+| `jokes-embeddings-cohere.json` | Cohere embedding store. |
+| `quotes-embeddings*.json` | Equivalent stores for the quotes deck. |
+| `slang-embeddings.json` | Synthetic store for slang. |
+| `slang-embeddings-hfspace.json` | Hugging Face Space embeddings (`sentence-transformers/all-MiniLM-L6-v2`). |
+| `slang-embeddings-synthetic128.json` | 128-dimension deterministic store for slang. |
+| `similarity-report-*.json` | Cosine similarity sweeps per dataset and provider. Cross-deck variants have a `cross-deck` infix. |
+| `similarity-overrides.json` | Intentionally kept near-duplicates; the similarity lab highlights these pairs as "protected" instead of flagging them for removal. |
+| `test-runs/` | Playwright trace archives and console logs captured by `tools/record-playwright-log.js`. |
+
+## Maintenance scripts (`tools/`)
+
+### `update-content-metadata.js`
+
+Regenerates deterministic IDs and manifest files for one or all content decks.
+
+```bash
+# Update all three decks
+node tools/update-content-metadata.js
+
+# Update only one deck
+node tools/update-content-metadata.js --dataset=slang
+```
+
+Rewrites `apps/jokes/jokes.js`, `apps/quotes/quotes-data.js`, and `apps/slang/slang.js` in the house style. Emits `data/*-manifest.json` files with normalised hashes and embedding metadata placeholders.
+
+---
+
+### `review-content-similarity.js`
+
+Fetches or computes embeddings and produces cosine similarity reports.
+
+```bash
+# Synthetic provider (no API key required)
+node tools/review-content-similarity.js \
+  --dataset=jokes --provider=synthetic \
+  --write --update-manifest \
+  --report=data/similarity-report-jokes.json
+
+# Hugging Face Space (free, no key required; keep batch-size ≤ 8)
+node tools/review-content-similarity.js \
+  --dataset=slang \
+  --provider=hfspace \
+  --model=bienkieu/sentence-embedding \
+  --batch-size=8 \
+  --write --update-manifest \
+  --report=data/similarity-report-slang.json
+
+# OpenAI or Cohere (API key required)
+node tools/review-content-similarity.js \
+  --dataset=quotes --provider=openai \
+  --write --update-manifest
+```
+
+Key flags:
+- `--write` — persist embeddings to disk.
+- `--update-manifest` — sync embedding metadata back into the manifest files.
+- `--report=<path>` — write the similarity report JSON.
+- `--threshold-<dataset>=<value>` — dataset-specific cosine threshold (e.g. `--threshold-slang=0.8`).
+- `--candidates=<type>:<path>` — embed prospective entries from a file and compare against the existing deck.
+
+**Duplicate thresholds.** Cosine scores ≥ 0.8 are treated as duplicates for quotes and slang. New jokes should also be screened at 0.8.
+
+---
+
+### `generate-asset-report.js`
+
+Inspects datasets, manifests, embedding stores, and similarity reports to produce `apps/asset-observatory/asset-data.js`.
+
+```bash
+node tools/generate-asset-report.js
+```
+
+Run this after any dataset or embedding change. Commit the refreshed `asset-data.js` alongside the underlying changes.
+
+---
+
+### `generate-offline-manifest.js`
+
+Walks every HTML, JSON, and JS asset, computes SHA-256 digests and byte sizes, and writes `offline-manifest.json`. Called by `npm run build:offline`.
+
+```bash
+npm run build:offline
+```
+
+Run this after any change to files under `apps/`, `data/`, or `index.html`. The resulting manifest file must be committed together with the asset changes.
+
+---
+
+### `onboard-external-jokes.js`
+
+Screens a batch of candidate jokes against the curated deck using cosine similarity, rejects near-duplicates, and emits summary reports.
+
+```bash
+node tools/onboard-external-jokes.js \
+  --input=data/new-jokes.json \
+  --output=reports/summary.json \
+  --accepted-output=reports/accepted.json
+```
+
+Candidate JSON format:
+```json
+[
+  { "id": "joke-001", "joke": "Why did the build fail?", "punchline": "Missing semicolon." }
+]
+```
+
+After acceptance: manually fold `reports/accepted.json` entries into `apps/jokes/jokes.js`, then run the standard dataset maintenance chain.
+
+---
+
+### `prune-duplicate-records.js`
+
+Applies curated duplicate removals to datasets, manifests, and embedding stores.
+
+```bash
+# Preview without writing
+node tools/prune-duplicate-records.js --dry-run
+
+# Apply changes
+node tools/prune-duplicate-records.js
+```
+
+---
+
+### `update-content-metadata.js` (also handles slang-only)
+
+```bash
+node tools/update-content-metadata.js --dataset=slang
+```
+
+Pass `--dataset=<name>` to update only one collection.
+
+---
+
+### `record-playwright-log.js`
+
+Captures Playwright traces, videos, and console output for each spec. Output goes to `data/test-runs/` with timestamps.
+
+```bash
+npm run test:record
+```
+
+Use the resulting bundles to reproduce failures or attach diagnostics to pull requests.
+
+---
+
+## Full dataset refresh workflow
+
+Run this sequence after any deck-level content change:
+
+```bash
+# 1. Regenerate IDs and manifests
+node tools/update-content-metadata.js
+
+# 2. Refresh embeddings and similarity reports
+node tools/review-content-similarity.js --dataset=jokes --provider=synthetic --write --update-manifest --report=data/similarity-report-jokes.json
+node tools/review-content-similarity.js --dataset=quotes --provider=synthetic --write --update-manifest --report=data/similarity-report-quotes.json
+node tools/review-content-similarity.js --dataset=slang --provider=synthetic --write --update-manifest --report=data/similarity-report-slang.json
+
+# 3. Refresh the asset observatory snapshot
+node tools/generate-asset-report.js
+
+# 4. Rebuild the offline manifest
+npm run build:offline
+
+# 5. Smoke-test
+npm test
+```
+
+Commit every generated file together with the source changes so the deployed site and the test suite stay consistent.
diff --git a/ai-docs/development-conventions.md b/ai-docs/development-conventions.md
new file mode 100644
index 0000000..d629a8b
--- /dev/null
+++ b/ai-docs/development-conventions.md
@@ -0,0 +1,83 @@
+# Development conventions
+
+## HTML and CSS
+
+- **Indentation.** Two spaces per level in all modernised files. Legacy files (e.g. `value-formatter`) may use wider indentation—match the surrounding style rather than reformatting the whole file.
+- **Inline styles.** Every app defines its styles in a `<style>` block inside `<head>`. Do not add external stylesheets unless the app already uses one (only `apps/cloth` links `styles.css`).
+- **CSS custom properties.** Define the full palette under `:root` and override it in `@media (prefers-color-scheme: dark)`. Use the same variable names already established in that app so light and dark themes stay in sync. Toys that have a fixed visual identity use `color-scheme: only light`.
+- **Semantic structure.** Use `<main>`, `<article>`, `<header>`, `<nav>`, `<section>` where appropriate. Avoid `<div>` soup.
+- **Buttons.** Always set `type="button"` unless submitting a form. Provide `:hover` and `:focus-visible` styles that match the rest of the page.
+- **Icons.** The chevron SVG used in call-to-action spans is copy-pasted across cards. Reuse the exact same snippet so all arrows look identical.
+
+## JavaScript
+
+- **IIFEs.** Wrap app logic in an immediately invoked function expression to avoid polluting the global scope:
+  ```js
+  (function () {
+    'use strict';
+    // ...
+  })();
+  ```
+- **`const`/`let` only.** Never use `var`.
+- **Guard clauses.** Check that DOM nodes exist before wiring events:
+  ```js
+  const btn = document.getElementById('next');
+  if (!btn) return;
+  btn.addEventListener('click', handleNext);
+  ```
+  This prevents shared scripts from crashing on pages that omit certain elements.
+- **Empty dataset handling.** Always check with `Array.isArray(data) ? data : []`. Filter falsy records before rendering. Show friendly fallback copy (`"No jokes available."`) and a `'💩'` placeholder when the array is empty.
+- **Large table rendering.** Build rows with `document.createElement` and append via `DocumentFragment` before touching the live DOM. Update the count badge (`[data-count]`) with `toLocaleString()`.
+- **Keyboard shortcuts.** Mirror the pattern from the jokes and quotes apps: `ArrowLeft` / `ArrowRight` for prev/next, `Space` to toggle reveal.
+
+## Datasets
+
+- **File format.** Dataset files are plain JS files that assign arrays to `window.*`:
+  ```js
+  window.jokes = [
+    { "id": "j-001", "joke": "...", "punchline": "...", "sourceId": "..." },
+  ];
+  ```
+- **Property names.** `joke`/`punchline` for jokes, `text`/`author`/`tags` for quotes, `term`/`definition` for slang. Do not rename these fields.
+- **Formatting.** Match the generated double-quote style of existing entries when making manual edits. Avoid reformatting adjacent entries.
+- **Validation before commit.** Run the syntax and shape checks from each app's `AGENTS.md`:
+  ```bash
+  node --check apps/jokes/jokes.js
+  node -e "const d = require('./apps/jokes/jokes.js'); console.log(Array.isArray(window.jokes));"
+  ```
+
+## Accessibility
+
+- Use `aria-live="polite"` on regions that update dynamically (progress bars, status messages).
+- Use `aria-pressed` on toggle buttons (punchline reveal, definition reveal).
+- Provide visually hidden captions for screen reader users where visual context is conveyed by position alone.
+- Label navigation landmarks with `aria-label` when more than one `<nav>` element is present.
+
+## Adding a new app
+
+1. Create `apps/<name>/index.html` plus any supporting files (`app.js`, dataset, `AGENTS.md`).
+2. Follow the inline-style pattern. Wrap JS in an IIFE.
+3. Add a Home link targeting `../../`:
+   ```html
+   <a href="../../" aria-label="Home">← Home</a>
+   ```
+4. Add the app card to `index.html`. Use a unique emoji that no existing card uses.
+5. Run `npm run build:offline` to include new assets in the offline manifest.
+6. Add or extend a Playwright spec under `tests/`.
+7. Update `docs/docs/apps.md` with the new app's entry.
+8. Update `docs/index.html` if a new guide is added to `docs/docs/`.
+
+## Updating existing documentation
+
+- `docs/docs/` is the human-facing Markdown knowledge base. Update the relevant guide whenever you change a workflow, script, or dataset pipeline.
+- `ai-docs/` (this directory) is the AI-agent-focused reference. Keep it in sync with any architectural or tooling changes.
+- `AGENTS.md` (root) is the top-level agent guide. It covers the same conventions as this file but in summary form; update both when the conventions change.
+- Each app may also have its own `apps/<name>/AGENTS.md`. Update that file when the app's maintenance commands or dataset shape changes.
+
+## Common mistakes to avoid
+
+- Forgetting to run `npm run build:offline` after adding or renaming assets — the offline manifest will be stale.
+- Editing a dataset without regenerating manifests and embeddings — downstream tools and tests will diverge.
+- Adding a new app without a Home link — `tests/home-navigation.spec.js` will fail.
+- Using `var` or global function declarations — violates the IIFE convention.
+- Removing a test to make a failing suite green — never acceptable.
diff --git a/ai-docs/project-overview.md b/ai-docs/project-overview.md
new file mode 100644
index 0000000..9285344
--- /dev/null
+++ b/ai-docs/project-overview.md
@@ -0,0 +1,50 @@
+# Project overview
+
+## What is this project?
+
+**denisvaleev.github.io** is a static toolbox served from GitHub Pages. The landing page (`index.html`) lists a collection of small, self-contained web apps. Each app lives under `apps/<name>/`, runs entirely in the browser, and requires no build step or backend.
+
+The toolbox is intentionally minimal: no framework, no bundler, no server-side logic. Pages load HTML files directly, or through any static HTTP server.
+
+## Repository layout
+
+| Path | Purpose |
+| --- | --- |
+| `index.html` | Landing page. Advertises every app, handles offline bootstrap, registers the service worker. |
+| `apps/` | One folder per app. Each contains HTML with inline CSS, a JavaScript controller, and any needed datasets. |
+| `data/` | Canonical datasets, manifests, embedding stores, similarity reports, and audit logs. |
+| `tools/` | Node.js maintenance scripts for offline manifests, metadata, embeddings, similarity, and diagnostics. |
+| `tests/` | Playwright end-to-end specs covering the landing page and every app. |
+| `docs/` | Human-facing Markdown knowledge base rendered by a browser-side docs app. |
+| `ai-docs/` | This directory — AI-agent-focused documentation. |
+| `service-worker.js` | Cache controller that precaches toolbox assets for offline use. |
+| `offline-manifest.json` | Machine-generated list of every shipped asset with byte sizes and a SHA-256 digest. |
+| `package.json` | Dev dependency (`@playwright/test`) plus `npm test` and `npm run build:offline` scripts. |
+| `playwright.config.js` | Playwright configuration (browser, server startup, timeouts). |
+| `.github/` | GitHub Actions workflows for CI, offline manifest refresh, and observatory data refresh. |
+| `AGENTS.md` | Top-level agent guide with coding conventions and validation rules. |
+
+## Apps at a glance
+
+| App folder | Title | Type |
+| --- | --- | --- |
+| `apps/jokes` | Dad Jokes | Deck + archive |
+| `apps/quotes` | Quotes | Deck + archive |
+| `apps/slang` | Slang | Deck + archive |
+| `apps/similarity-report` | Cosine Similarity Lab | Analytics |
+| `apps/asset-observatory` | Asset Observatory | Dashboard |
+| `apps/embedding-explorer` | Embedding Explorer | Analytics |
+| `apps/value-formatter` | Value Formatter | Utility |
+| `apps/wiki` | Wiki | Content browser |
+| `apps/total-recall` | Total Recall | Interactive tool |
+| `apps/enchanted-bunny` | Enchanted Forest Bunny | Interactive toy |
+| `apps/bunny-moon-choir` | Moonpetal Bunny Choir | Interactive toy |
+| `apps/cloth` | Cloth Lab | Physics simulation |
+
+## Key ideas
+
+- **Static-first.** No bundler, no server. Opening any HTML file is enough during development.
+- **Offline-capable.** `service-worker.js` + `offline-manifest.json` precache every asset so the toolbox works without a network connection.
+- **Curated datasets.** Jokes, quotes, and slang share a content pipeline: deterministic IDs, embedding stores, and cosine-similarity reports for deduplication.
+- **Playwright coverage.** Every interactive surface has an automated end-to-end spec.
+- **No `var`.** JavaScript follows modern idioms: IIFEs, `const`/`let`, guard clauses for missing DOM nodes.
diff --git a/ai-docs/testing.md b/ai-docs/testing.md
new file mode 100644
index 0000000..0f0f8c7
--- /dev/null
+++ b/ai-docs/testing.md
@@ -0,0 +1,85 @@
+# Testing
+
+## Setup
+
+Install dev dependencies and the Chromium browser bundle once per environment:
+
+```bash
+npm install
+npx playwright install --with-deps chromium
+```
+
+Use `npx playwright install chromium` (without `--with-deps`) if your environment already provides the system libraries.
+
+## npm scripts
+
+| Command | What it does |
+| --- | --- |
+| `npm test` | Runs the full Playwright suite. The `pretest` hook installs Chromium if missing. |
+| `npm run test:ui` | Opens the Playwright UI runner for interactive, step-through debugging. |
+| `npm run test:record` | Runs `tools/record-playwright-log.js` to capture traces, videos, and console logs for every spec. |
+| `npm run build:offline` | Regenerates `offline-manifest.json` via `tools/generate-offline-manifest.js`. |
+
+## Playwright specs
+
+| Spec | Responsibility |
+| --- | --- |
+| `tests/index.spec.js` | Landing page renders all app cards and developer shortcut links. |
+| `tests/home.spec.js` | Every app has a working Home link back to the landing page. |
+| `tests/home-navigation.spec.js` | Regression guard ensuring no app loses its Home navigation after UI changes. |
+| `tests/jokes.spec.js` | Deck controls, punchline reveal, keyboard shortcuts, and dataset fallbacks for the jokes app. |
+| `tests/jokes-dataset.spec.js` | Dataset invariants: unique IDs, punchline presence, manifest alignment. |
+| `tests/jokes-all.spec.js` | Archive page renders count, search, and table interactions. |
+| `tests/quotes.spec.js` | Deck controls, attribution toggle, keyboard shortcuts for the quotes app. |
+| `tests/quotes-data.spec.js` | Dataset invariants for quotes. |
+| `tests/quotes-all.spec.js` | Quotes archive page interactions. |
+| `tests/slang-app.spec.js` | Deck controls, definition reveal, keyboard shortcuts for the slang app. |
+| `tests/slang-dataset.spec.js` | Slang dataset invariants. |
+| `tests/slang-all.spec.js` | Slang archive page interactions. |
+| `tests/value-formatter.spec.js` | Preset transforms, persistence, and manual formatting logic. |
+| `tests/similarity-report.spec.js` | Dataset toggles, score threshold slider, and similarity overlays. |
+| `tests/asset-observatory.spec.js` | Observatory dashboard stays aligned with `asset-data.js`. |
+| `tests/embedding-explorer.spec.js` | Dataset switching, record filtering, neighbor list, and chart rendering. |
+| `tests/offline-manifest.spec.js` | Manifest enumerates every shipped HTML, JS, and JSON asset. |
+| `tests/enchanted-bunny.spec.js` | Enchanted bunny app interactions and navigation. |
+
+## Running a single spec
+
+```bash
+npx playwright test tests/asset-observatory.spec.js
+```
+
+Combine with `--headed` to watch the browser:
+
+```bash
+npx playwright test tests/jokes.spec.js --headed
+```
+
+## Capturing diagnostics
+
+```bash
+npm run test:record
+```
+
+Traces and console logs land in `data/test-runs/`. Attach that directory to pull requests when reporting failures.
+
+## What to run after common changes
+
+| Change type | Required checks |
+| --- | --- |
+| Any HTML/JS/CSS edit | `npm test` |
+| Deck dataset edit (jokes/quotes/slang) | `npm test` focusing on the matching dataset + app + all specs |
+| Asset observatory data refresh | `npx playwright test tests/asset-observatory.spec.js` |
+| Offline manifest regeneration | `npx playwright test tests/offline-manifest.spec.js` |
+| Enchanted bunny changes | `npx playwright test tests/enchanted-bunny.spec.js tests/home-navigation.spec.js` |
+| New app added | `npm test` (index + home-navigation specs in particular) |
+
+## Continuous integration (GitHub Actions)
+
+Three workflows run automatically:
+
+1. **Playwright smoke tests** — runs `npm test` on every push, pull request, and a weekly cron. Same command as local.
+2. **Refresh offline manifest** — triggers after a PR merges; regenerates `offline-manifest.json` and commits it.
+3. **Refresh asset observatory data** — triggers when dataset files change in a merged PR; re-runs `tools/generate-asset-report.js` and commits the updated snapshot.
+
+A fourth **Deploy static site** workflow publishes the repository to GitHub Pages. It writes `.nojekyll` to skip Jekyll processing.