Update copilot-instructions.md with current conventions

Reflect YAML content format, 14 locales, proof files, JDK filter
ranges, and practical i18n rules. Remove outdated examples.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: brunoborges

.github/copilot-instructions.md

@@ -1,192 +1,106 @@
 # Copilot Instructions for java.evolved
 
-## Project Overview
+## Build & Serve
 
-This is a static site showcasing modern Java patterns vs legacy approaches.
-It is hosted on GitHub Pages at https://javaevolved.github.io.
+```bash
+jbang html-generators/generate.java                # Rebuild all locales
+jbang html-generators/generate.java --locale es     # Rebuild single locale
+jwebserver -b 0.0.0.0 -d site -p 8090              # Serve locally
+```
+
+Requires **Java 25+** and **JBang**. No npm, Maven, or Gradle.
+
+**Validation:** There is no test suite. Validate changes by running the generator and confirming it completes without errors. The `proof/` directory contains one JBang script per pattern that proves the modern code compiles:
+
+```bash
+jbang proof/language/TypeInferenceWithVar.java      # Run single proof
+```
 
 ## Architecture
 
-### Source of Truth: JSON Files
+Static site generator: YAML content → JBang generator → HTML pages.
 
-Each pattern is defined as a JSON file under **`content/category/`**:
+- **`content/`** — Source of truth. One YAML/JSON file per pattern, organized by category.
+- **`templates/`** — HTML templates with `{{placeholder}}` tokens. The generator replaces tokens with content fields and UI strings.
+- **`html-generators/generate.java`** — JBang script that reads content + translations + templates and produces all HTML under `site/`.
+- **`site/app.js`** and **`site/styles.css`** — Manually maintained client-side code (vanilla JS, no frameworks).
+- **`translations/strings/{locale}.yaml`** — UI string translations (labels, nav, footer). Tokens use dotted keys: `{{nav.allPatterns}}`.
+- **`translations/content/{locale}/`** — Partial content translations (only translatable fields; structural data always comes from English source).
+- **`proof/{category}/{PascalCaseSlug}.java`** — JBang scripts proving each pattern's modern code compiles on Java 25.
 
-```
-content/language/type-inference-with-var.json
-content/collections/immutable-list-creation.json
-content/streams/stream-tolist.json
-...
-```
+### Generated files — DO NOT EDIT directly
 
-**Categories:** `language`, `collections`, `strings`, `streams`, `concurrency`, `io`, `errors`, `datetime`, `security`, `tooling`, `enterprise`
+Everything under `site/` except `app.js` and `styles.css` is generated:
+- `site/index.html`, `site/{category}/*.html`, `site/data/snippets.json`
+- `site/{locale}/index.html`, `site/{locale}/{category}/*.html`, `site/{locale}/data/snippets.json`
 
-### Generated Files (DO NOT EDIT)
+Run the generator to rebuild after any content, template, or translation change.
 
-The following are **generated by `html-generators/generate.java`** and must not be edited directly:
+## Content Schema
 
-- `site/index.html` — English homepage with preview cards (generated from `templates/index.html`)
-- `site/language/*.html`, `site/collections/*.html`, etc. — English detail pages
-- `site/data/snippets.json` — English aggregated search index
-- `site/{locale}/index.html` — localized homepage (e.g., `site/es/index.html`)
-- `site/{locale}/language/*.html`, etc. — localized detail pages
-- `site/{locale}/data/snippets.json` — localized search index
+Content files are YAML (preferred) or JSON under `content/{category}/{slug}.yaml`. The generator auto-detects format by extension (`.yaml`, `.yml`, `.json`).
 
-Run `jbang html-generators/generate.java` to rebuild all generated files from the JSON sources and translations.
+### Required fields
 
-### Manually Maintained Files
+| Field | Constraint |
+|-------|-----------|
+| `slug` | Must match filename (without extension) |
+| `category` | Must match parent folder name |
+| `whyModernWins` | Exactly **3** entries, each with `icon`, `title`, `desc` |
+| `related` | Exactly **3** entries as `category/slug` paths (cross-category OK) |
+| `docs` | At least **1** entry with `title` and `href` |
+| `prev` / `next` | `category/slug` path or `null` for first/last in the global chain |
+| `jdkVersion` | The JDK version where the feature became **final** (not preview) |
+| `difficulty` | One of: `beginner`, `intermediate`, `advanced` |
+| `support.state` | One of: `available`, `preview`, `experimental` |
 
-- `site/app.js` — client-side search, filtering, code highlighting, locale detection
-- `site/styles.css` — all styling
-- `templates/slug-template.html` — HTML template with `{{placeholder}}` tokens (content + UI strings) used by the generator
-- `templates/index.html` — homepage template with `{{tipCards}}`, `{{snippetCount}}`, and UI string placeholders
-- `templates/index-card.html` — preview card template for the homepage grid
-- `html-generators/categories.properties` — category ID → display name mapping
-- `html-generators/locales.properties` — supported locales registry (locale=Display name)
-- `translations/strings/{locale}.yaml` — UI strings per locale (labels, nav, footer, etc.)
-- `translations/content/{locale}/` — translated pattern JSON files (partial, translatable fields only)
+### Adding a new pattern
 
-### Project Structure
+1. Create `content/{category}/new-slug.yaml` with all required fields (use `content/template.json` as reference).
+2. Update `prev`/`next` in the adjacent patterns to maintain the navigation chain.
+3. Create `proof/{category}/{PascalCaseSlug}.java` — JBang script wrapping the modern code.
+4. Run `jbang html-generators/generate.java` and verify it completes.
+5. Translations are optional — the AI translation workflow handles them, or create partial files under `translations/content/{locale}/`.
 
-```
-content/            # English content JSON files (source of truth, one per pattern)
-translations/       # All i18n artifacts
-  strings/          # UI strings per locale (en.yaml, es.yaml, pt-BR.yaml)
-  content/          # Translated pattern files per locale (partial, translatable fields only)
-    es/             # Spanish translations (mirrors content/ folder structure)
-    pt-BR/          # Brazilian Portuguese translations
-site/               # Deployable site (static assets + generated HTML)
-  es/               # Generated Spanish pages
-  pt-BR/            # Generated Portuguese pages
-templates/          # HTML templates with {{…}} tokens for content + UI strings
-html-generators/    # Build scripts, categories.properties, locales.properties
-specs/              # Feature specifications (e.g., i18n-spec.md)
-```
+### Removing or reordering a pattern
 
-## JSON Snippet Schema
-
-Each `content/category/slug.json` file has this structure:
-
-```json
-{
-  "id": 1,
-  "slug": "type-inference-with-var",
-  "title": "Type inference with var",
-  "category": "language",
-  "difficulty": "beginner|intermediate|advanced",
-  "jdkVersion": "10",
-  "oldLabel": "Java 8",
-  "modernLabel": "Java 10+",
-  "oldApproach": "Explicit Types",
-  "modernApproach": "var keyword",
-  "oldCode": "// old way...",
-  "modernCode": "// modern way...",
-  "summary": "One-line description.",
-  "explanation": "How it works paragraph.",
-  "whyModernWins": [
-    { "icon": "⚡", "title": "Short title", "desc": "One sentence." },
-    { "icon": "👁", "title": "Short title", "desc": "One sentence." },
-    { "icon": "🔒", "title": "Short title", "desc": "One sentence." }
-  ],
-  "support": {
-    "state": "available",
-    "description": "Widely available since JDK 10 (March 2018)"
-  },
-  "prev": "category/slug-of-previous",
-  "next": "category/slug-of-next",
-  "related": [
-    "category/slug-1",
-    "category/slug-2",
-    "category/slug-3"
-  ],
-  "docs": [
-    { "title": "Javadoc or Guide Title", "href": "https://docs.oracle.com/..." }
-  ]
-}
-```
+Update `prev`/`next` in adjacent patterns. Search for the slug in other patterns' `related` arrays and replace with an appropriate alternative.
+
+## Internationalization
+
+Full spec: `specs/i18n/i18n-spec.md`. Key rules:
+
+- All locales (including English) go through the same build pipeline.
+- UI strings: `translations/strings/{locale}.yaml`. Missing keys fall back to English with a build-time warning.
+- Content translations contain **only** translatable fields: `title`, `summary`, `explanation`, `oldApproach`, `modernApproach`, `whyModernWins`, `support.description`. Code, slugs, navigation, and docs are never translated.
+- `oldCode`/`modernCode` in translation files are **always overwritten** with English values at build time to prevent hallucinated code.
+- Locale registry: `html-generators/locales.properties` (format: `locale=Display Name`).
+- When adding a new UI string key, add it to `en.yaml` first, then to all other locale files. The generator warns on missing keys but doesn't fail.
+- YAML colons in string values must be quoted (Jackson parser is stricter than PyYAML).
+
+## Proof Files
 
-### Key Rules
-
-- `slug` must match the filename (without `.json`)
-- `category` must match the parent folder name
-- `whyModernWins` must have exactly **3** entries
-- `related` must have exactly **3** entries (as `category/slug` paths)
-- `docs` must have at least **1** entry linking to Javadoc or Oracle documentation
-- `prev`/`next` are `category/slug` paths or `null` for first/last
-- Code in `oldCode`/`modernCode` uses `\n` for newlines
-
-## Category Display Names
-
-Categories and their display names are defined in `html-generators/categories.properties`:
-
-| ID | Display |
-|----|---------|
-| `language` | Language |
-| `collections` | Collections |
-| `strings` | Strings |
-| `streams` | Streams |
-| `concurrency` | Concurrency |
-| `io` | I/O |
-| `errors` | Errors |
-| `datetime` | Date/Time |
-| `security` | Security |
-| `tooling` | Tooling |
-| `enterprise` | Enterprise |
-
-## Adding a New Pattern
-
-1. Create `content/category/new-slug.json` with all required fields
-2. Update `prev`/`next` in the adjacent patterns' JSON files
-3. Run `jbang html-generators/generate.java`
-4. (Optional) Create translated content files under `translations/content/{locale}/category/new-slug.json` with only translatable fields — or let the AI translation workflow handle it
-
-## Internationalization (i18n)
-
-The site supports multiple languages. See `specs/i18n/i18n-spec.md` for the full specification.
-
-### Key Concepts
-
-- **UI strings:** Hard-coded template text (labels, nav, footer) is extracted into `translations/strings/{locale}.yaml`. Templates use `{{dotted.key}}` tokens (e.g., `{{nav.allPatterns}}`, `{{sections.codeComparison}}`). Missing keys fall back to the English value with a build-time warning.
-- **Content translations:** Translated pattern files under `translations/content/{locale}/` contain **only** translatable fields (`title`, `summary`, `explanation`, `oldApproach`, `modernApproach`, `whyModernWins`, `support.description`). All other fields (`oldCode`, `modernCode`, `slug`, `id`, `prev`, `next`, `related`, `docs`, etc.) are always taken from the English source.
-- **Locale registry:** `html-generators/locales.properties` lists supported locales (format: `locale=Display name`). The first entry is the default.
-- **English is a first-class locale:** All locales — including English — go through the same build pipeline.
-- **Fallback:** If a pattern has no translation file for a locale, the English content is used and an "untranslated" banner is shown.
-
-### Supported Locales
-
-Defined in `html-generators/locales.properties`:
-
-| Locale | Display Name |
-|--------|-------------|
-| `en` | English |
-| `es` | Español |
-| `pt-BR` | Português (Brasil) |
-
-### Content Translation File Example
-
-Translation files contain **only** translatable fields — no structural data:
-
-```json
-// translations/content/pt-BR/language/type-inference-with-var.json
-{
-  "title": "Inferência de tipo com var",
-  "oldApproach": "Tipos explícitos",
-  "modernApproach": "Palavra-chave var",
-  "summary": "Use var para deixar o compilador inferir o tipo local.",
-  "explanation": "...",
-  "whyModernWins": [
-    { "icon": "⚡", "title": "Menos ruído", "desc": "..." },
-    { "icon": "👁",  "title": "Mais legível", "desc": "..." },
-    { "icon": "🔒", "title": "Seguro", "desc": "..." }
-  ],
-  "support": {
-    "description": "Amplamente disponível desde o JDK 10 (março de 2018)"
-  }
+Each pattern has a corresponding proof file: `proof/{category}/{PascalCaseSlug}.java`.
+
+```java
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//JAVA 25+
+
+/// Proof: slug-name
+/// Source: content/category/slug-name.yaml
+void main() {
+    // modern code only — no old code, no assertions
 }
 ```
 
-## Local Development
+Uses Java 25 implicit classes (`void main()`, not `static void main`). Add minimal scaffolding (imports, dummy variables) to make the modern code compile.
 
-```bash
-jbang html-generators/generate.java  # Build HTML pages + snippets.json
-jwebserver -d site -p 8090              # Serve locally
-```
+## Key Conventions
+
+- **Vanilla JS only** — `site/app.js` uses no frameworks or build tools.
+- **Category display names** are defined in `html-generators/categories.properties`, not hardcoded.
+- **JDK filter ranges** in `app.js` map LTS versions to ranges: `11→[9-11]`, `17→[12-17]`, `21→[18-21]`, `25→[22-25]`.
+- **JetBrains Mono ligatures** are disabled on `.code-text` elements to prevent operators like `->` from rendering as special characters.
+- **Dark theme** uses CSS custom properties (`--modern-bg`, `--old-bg`). Theme state is in `localStorage.theme` and `data-theme` on `<html>`.
+- **RTL support** — Arabic (`ar`) locale sets `dir="rtl"` on the page.
+- When both old and modern approaches are from the same JDK version, use descriptive labels (e.g., "Full syntax" / "Compact") instead of version numbers.