aievolutionpl · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "meta-ads-designer",
   "description": "Design and generate posters, flyers, Meta/social ads and promo graphics that look art-directed instead of AI-generated.",
-  "version": "5.10.0",
+  "version": "6.2.0",
   "author": { "name": "AI Evolution Labs", "url": "https://github.com/aievolutionpl" },
   "homepage": "https://github.com/aievolutionpl/meta-ads-designer",
   "license": "MIT",

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -19,3 +19,5 @@ jobs:
         run: python scripts/check_docs.py
       - name: QA gate self-test
         run: python scripts/test_qa.py
+      - name: Creative diagnostics self-test
+        run: python scripts/test_diagnostics.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,58 @@ All notable changes to Meta Ads Designer. Versions follow [SemVer](https://semve
 
 ---
 
+## [6.2.0] — 2026-09-24
+
+### Added
+- **`R52` The words must sell.** A five-question sell test (what is it · why me · why believe it · why now · only we could say it) runs on every on-image string. Mood lines, unproven superlatives and generic questions count as copy slop and a hard fail. Added to `headline-system.md` §0 with before/after rewrites, `core.md` §11a and the `SKILL.md` decision steps.
+- **AI-generated README showcase** (`assets/showcase/`): a hero and three ads generated from the skill's prompts, analysed in `examples/08-generated-showcase.md`. The analysis covers text transcription, defects and R52 copy failures, and `prompts/readme-showcase-v2.txt` carries the round-2 selling hooks.
+
+---
+
+## [6.1.0] — 2026-09-24
+
+### Fixed
+- **5.11.0 and 6.0.0 now reach `main`.** The previous merge only carried 5.10.0.
+- **R50 contradictions removed.** Older guidance in core, the engine, the charter, headline system, model routing, prompt library, QA gate, layout system, hospitality and niche playbooks, style atlas and static formats told the agent to typeset text or compose logos in code (Mode B). It now says to generate with quoted copy, pass references and transcribe the result. Mode B survives only as an explicit-request fallback, and examples 00, 01 and 04 carry the R50 note.
+
+### Added
+- **`scripts/generate_fal.py`**: generates ads through fal.ai's queue API from a prompt file, saves the images and a reproducibility log (model, prompt, seed, request id). Standard library only; needs `FAL_KEY`.
+- **`examples/08-generated-showcase.md`** and `examples/prompts/readme-showcase.txt`: the full R51 loop and three ready prompts for the README showcase.
+
+---
+
+## [6.0.0] — 2026-09-24
+
+Doctrine change, hence the major version: final ads are always generated by an AI image model, and the agent researches and asks before it generates.
+
+### Added
+- **`R50` Generated, never coded.** Every final ad (imagery, headline, copy, layout) comes out of an image model: an API model, Codex or the host's tool. HTML, code or programmatic overlays are used only on explicit request. It overrides every earlier "Mode B / deterministic composition / typesetting handoff" instruction. Text reliability now comes from quoted copy with diacritics, "no other text", hierarchy and position, reference images with roles, post-render transcription, and regeneration or targeted model edits.
+- **`R51` Research and ask before generating.** Research the brand site, Meta Ad Library, competitors, reviews and season. Ask 3–6 questions in one message, each with a default. Write a decision note, then prompt, generate and analyse each result.
+- **`references/discovery-and-research.md`**: research table, question bank, decision-note template and the post-generation analysis order.
+
+### Changed
+- `SKILL.md` (new first section, generation-first text contract, analysis step, description), `core.md` §0 and §12, `prompt-craft.md` §2, the engine's precedence note, `design-rules.md` §4, both READMEs, and notes on examples 02, 03, 05 and 07.
+
+### Removed
+- The HTML-typeset Style Atlas board (`assets/style-atlas-2026.png`, `assets/generated/style-atlas.html`). A coded board contradicted R50.
+
+---
+
+## [5.11.0] — 2026-09-24
+
+Skills as repeatable jobs, following Metaflow's overview of Claude skills for Meta ads (CPA diagnostics, creative fatigue detection, competitor creative analysis).
+
+### Added
+- **`R49` Diagnose before you redesign**: read results first, stop at the first broken funnel step, and change only the creative decision it points to.
+- **`references/creative-diagnostics.md`**: input and output contracts, a symptom → cause → change table, and guardrails against claiming causation.
+- **`scripts/creative_diagnostics.py`**: reads an Ads Manager CSV export (comma, semicolon or tab; Polish decimal commas), compares each ad with the account median, flags fatigue, weak hook, weak hold, low CTR, high CPM, high CPA and winners, and prints the next-brief action for each. Standard library only; `scripts/test_diagnostics.py` in CI.
+
+### Changed
+- **`SKILL.md`**: campaign requests deliver a package (working note, prompt, typesetting handoff, per-placement output, landing continuity line); results route to diagnostics first.
+- **`core.md`** §19a, the engine, both READMEs, the charter and CI.
+
+---
+
 ## [5.10.0] — 2026-09-24
 
 The 2026 feed layer: what current Meta ads look like, which structures persuade, and what changed on the platform. Researched from Behance and Dribbble portfolio patterns, Penji's Meta design guidance, Meta's Ads Guide and about thirty 2026 sources on creative performance, trends and placement changes. Third-party figures are labelled as such and never presented as promised results.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,7 +8,7 @@ This is a **rules repo** — the value is the design doctrine. Every contributio
 
 | File | Role | When to edit it |
 |------|------|-----------------|
-| **`visual-advertising-engine.md`** | The canonical standard (48 rules) | **Adding/refining a rule → edit here FIRST.** This is the source of truth. English. |
+| **`visual-advertising-engine.md`** | The canonical standard (52 rules) | **Adding/refining a rule → edit here FIRST.** This is the source of truth. English. |
 | `design-rules.md` | The readable charter (English canonical) | Summarize a rule already in the engine. |
 | `core.md` | The complete general-knowledge inject | Add only if a rule is so essential it must be in the inject. |
 | `SKILL.md` | Agent manual | Procedural/workflow changes. |

diff --git a/README.en.md b/README.en.md
@@ -6,13 +6,17 @@ An AI agent skill for choosing **composition, typography, colour and visual dire
 
 [Polski](README.md) · [Agent instructions](SKILL.md) · [Quick start](#quick-start) · [Examples](examples/README.md)
 
-![Version](https://img.shields.io/badge/version-5.10.0-222222)
+![Version](https://img.shields.io/badge/version-6.2.0-222222)
 ![License](https://img.shields.io/badge/license-MIT-222222)
 ![Model independent](https://img.shields.io/badge/prompts-model_independent-222222)
 
-![Meta Ads Designer — bold contemporary typography and three advertising concepts](assets/meta-ads-designer-bold.png)
+![Meta Ads Designer — AI-generated showcase](assets/showcase/hero.jpg)
 
-*AI-generated demonstration concepts: fictional cafe DAYBREAK, event AFTER HOURS and brand FORM. These illustrate design directions, not client campaigns or measured advertising performance. [Exact prompt and image notes](examples/06-readme-showcase.md).*
+| | | |
+|---|---|---|
+| ![PORA](assets/showcase/ad-pora.jpg) | ![NURT](assets/showcase/ad-nurt.jpg) | ![NOC BRZMI](assets/showcase/ad-noc-brzmi.jpg) |
+
+*Fully AI-generated from the skill's prompts: no retouching, no code overlays. Brands are fictional. [Prompts, analysis and round 2](examples/08-generated-showcase.md).*
 
 ## What the skill does
 
@@ -36,11 +40,13 @@ The same concepts can also take a quieter editorial direction:
 
 *A second demonstration board. The art direction changes; the skill is not restricted to either style.*
 
-## New in 5.10: the 2026 feed layer
+## New in 6.0: research, questions, AI generation
 
-![Style Atlas 2026: six fictional ads, each pairing a static format with one visual language](assets/style-atlas-2026.png)
+- **Always generated by AI from scratch.** Every final ad comes out of an image model (API, Codex or the host's tool), headline and layout included. No HTML or coded composition (R50).
+- **Research first, then questions.** The agent checks the brand's site, Meta Ad Library, competitors and reviews, then asks 3–6 sharp questions at once, each with a default, and writes prompts from a decision note (R51).
+- **Analysis after generation.** The agent transcribes every word in the image, checks product and logo fidelity, runs the thumbnail test and changes one decision per iteration.
 
-*Six fictional ads typeset deterministically in HTML ([source](assets/generated/style-atlas.html)): no image model, no client assets, no performance claims. Each pairs a persuasion format with one visual language.*
+### The 2026 layer
 
 The skill now knows what current Meta ads look like and why some structures persuade:
 
@@ -59,6 +65,7 @@ flowchart LR
     D --> E["Image and visual review"]
 ```
 
+1. **Research and questions** — study the brand, Ad Library and competitors, ask 3–6 questions, write a decision note.
 1. **Brief** — establish audience, verified offer, goal, format and available assets.
 2. **Idea** — choose what makes the benefit visible: product, action, detail, situation or type.
 3. **Art direction** — pick a format the proof supports and one visual language, then define the focal element, reading order, copy space, fonts and palette.
@@ -96,9 +103,7 @@ git clone https://github.com/aievolutionpl/meta-ads-designer.git
 
 ## Text and logos
 
-Short copy can be generated with the ad and inspected afterwards. When exact fonts, diacritics, prices or official logos matter, the skill supports separate typesetting: an image with planned copy space plus a composition specification.
-
-A prompt communicates intent. It cannot guarantee identical fonts, pixel coordinates or perfect spelling in every tool.
+The whole ad, text included, is generated by the AI model. The skill quotes exact copy with correct diacritics, gives hierarchy and position, and passes the logo and product as reference images. After generation the agent transcribes every word. On an error it regenerates or runs a targeted edit with the same model instead of overlaying text in code.
 
 ## Repository guide
 
@@ -108,12 +113,14 @@ A prompt communicates intent. It cannot guarantee identical fonts, pixel coordin
 | [core.md](core.md) | Self-contained chat instruction |
 | [Art direction](references/art-direction.md) | Marketing goal to composition and typography |
 | [Prompt craft](references/prompt-craft.md) | Writing and reviewing prompts |
+| [Discovery and research](references/discovery-and-research.md) | Research, pre-generation questions, decision note, result analysis |
 | [Style atlas 2026](references/style-atlas-2026.md) | Twelve visual languages, trend slop, reading reference boards |
 | [Static ad formats](references/static-ad-formats.md) | Persuasion skeletons, proof, funnel and vertical fit |
 | [Worked prompts](examples/05-model-independent-directions.md) | Flyer, food and local service |
 | [2026 style directions](examples/07-2026-style-directions.md) | Format plus style briefs and an Andromeda-ready campaign set |
-| [Visual Advertising Engine](visual-advertising-engine.md) | Canonical rules R01–R48 |
+| [Visual Advertising Engine](visual-advertising-engine.md) | Canonical rules R01–R52 |
 | [Layout system](references/layout-system.md) | Starting values for grids, margins and type |
+| [Creative diagnostics](references/creative-diagnostics.md) | From an Ads Manager export to the next brief (`scripts/creative_diagnostics.py`) |
 | [Platform guidance](references/platform-compliance.md) | Safe zones, text limits, Advantage+, AI labels |
 | [QA gate](references/qa-gate.md) | Reviewing actual rendered images |
 | [More examples](examples/README.md) | Briefs, prompts and design decisions |
@@ -124,6 +131,7 @@ A prompt communicates intent. It cannot guarantee identical fonts, pixel coordin
 pip install -r requirements.txt
 python scripts/check_docs.py
 python scripts/test_qa.py
+python scripts/test_diagnostics.py
 ```
 
 Documentation checks validate links, rule references and versions. Image QA measures selected technical properties; composition, credibility and brief fidelity need separate review. Campaign performance requires measurement after publication.

diff --git a/README.md b/README.md
@@ -6,13 +6,17 @@ Skill dla agentów AI, który pomaga dobierać **kompozycję, typografię, kolor
 
 [English](README.en.md) · [Instrukcja skilla](SKILL.md) · [Szybki start](#szybki-start) · [Przykłady](examples/README.md)
 
-![Version](https://img.shields.io/badge/version-5.10.0-222222)
+![Version](https://img.shields.io/badge/version-6.2.0-222222)
 ![License](https://img.shields.io/badge/license-MIT-222222)
 ![Model independent](https://img.shields.io/badge/prompts-model_independent-222222)
 
-![Meta Ads Designer — nowoczesna typografia i trzy wyraziste kreacje reklamowe](assets/meta-ads-designer-bold.png)
+![Meta Ads Designer — AI-generated showcase](assets/showcase/hero.jpg)
 
-*Koncepcje demonstracyjne wygenerowane z art-directed promptu: fikcyjna kawiarnia DAYBREAK, wydarzenie AFTER HOURS i marka FORM. To ilustracja kierunków projektowych, nie kampanie klientów ani dowód skuteczności reklamowej. [Prompt i opis grafiki](examples/06-readme-showcase.md).*
+| | | |
+|---|---|---|
+| ![PORA](assets/showcase/ad-pora.jpg) | ![NURT](assets/showcase/ad-nurt.jpg) | ![NOC BRZMI](assets/showcase/ad-noc-brzmi.jpg) |
+
+*Przykłady wygenerowane w całości przez AI z promptów skilla: bez retuszu i bez nakładek w kodzie. Marki są fikcyjne. [Prompty, analiza i runda 2](examples/08-generated-showcase.md).*
 
 ## Co robi ten skill
 
@@ -36,11 +40,13 @@ Ten sam zestaw pomysłów można rozwinąć w spokojniejszym kierunku editorial:
 
 *Druga plansza demonstracyjna. Zmienia się charakter art direction, a nie zakres możliwości skilla.*
 
-## Nowość w 5.10: warstwa 2026
+## Nowość w 6.0: research, pytania i generacja AI
 
-![Style Atlas 2026: sześć fikcyjnych reklam, każda łączy format statyczny z jednym językiem wizualnym](assets/style-atlas-2026.png)
+- **Zawsze generacja AI od zera.** Każda finalna reklama powstaje w modelu obrazu (API, Codex albo narzędzie hosta), razem z nagłówkiem i układem. Żadnego składania grafik w HTML czy kodzie (R50).
+- **Najpierw research, potem pytania.** Agent sprawdza stronę marki, Meta Ad Library, konkurencję i opinie, a potem zadaje 3–6 trafnych pytań naraz, z domyślną odpowiedzią przy każdym. Dopiero z notatki decyzyjnej pisze prompty (R51).
+- **Analiza po generacji.** Agent przepisuje każde słowo z obrazu, sprawdza wierność produktu i logo, robi test miniatury i zmienia jedną decyzję na iterację.
 
-*Sześć fikcyjnych reklam złożonych deterministycznie w HTML ([źródło](assets/generated/style-atlas.html)): bez modelu obrazu, bez materiałów klientów, bez obietnic wyników. Każda łączy format perswazji z jednym językiem wizualnym.*
+### Warstwa 2026
 
 Skill wie teraz, jak wyglądają aktualne reklamy Meta i dlaczego pewne struktury przekonują:
 
@@ -59,6 +65,7 @@ flowchart LR
     D --> E["Obraz i ocena wizualna"]
 ```
 
+1. **Research i pytania** — agent bada markę, Ad Library i konkurencję, zadaje 3–6 pytań i spisuje notatkę decyzyjną.
 1. **Brief** — agent ustala odbiorcę, prawdziwą ofertę, cel, format i dostępne materiały.
 2. **Pomysł** — wybiera, co pokaże korzyść: produkt, działanie, detal, sytuacja lub typografia.
 3. **Art direction** — wybiera format, na który pozwala dowód, i jeden język wizualny, a potem określa dominantę, kolejność czytania, przestrzeń na tekst, fonty i paletę.
@@ -96,9 +103,7 @@ Instrukcją wejściową jest [SKILL.md](SKILL.md). Szczegóły dla poszczególny
 
 ## Tekst i logo w reklamie
 
-Dla krótkich treści można poprosić generator o gotową reklamę i sprawdzić jej pisownię. Gdy liczą się dokładny font, polskie znaki, cena lub oficjalne logo, skill przewiduje osobny skład: obraz z zaplanowanym miejscem na tekst oraz specyfikację typografii.
-
-Prompt wyraża intencję projektową. Nie gwarantuje identycznego fontu, położenia co do piksela ani bezbłędnej pisowni w każdym narzędziu.
+Cała reklama, łącznie z tekstem, powstaje w modelu AI. Skill pisze dokładne cytaty tekstu z polskimi znakami, podaje hierarchię i położenie, a logo i produkt przekazuje jako obrazy referencyjne. Po generacji agent przepisuje każde słowo z obrazu. Przy błędzie generuje ponownie albo robi celowaną edycję tym samym modelem, zamiast nakładać tekst kodem.
 
 ## Materiały w repozytorium
 
@@ -108,12 +113,14 @@ Prompt wyraża intencję projektową. Nie gwarantuje identycznego fontu, położ
 | [core.md](core.md) | Samodzielna instrukcja do wklejenia w czacie |
 | [Art direction](references/art-direction.md) | Od celu marketingowego do kompozycji i typografii |
 | [Prompt craft](references/prompt-craft.md) | Pisanie i sprawdzanie promptów |
+| [Research i pytania](references/discovery-and-research.md) | Research, pytania przed generacją, notatka decyzyjna, analiza wyników |
 | [Atlas stylów 2026](references/style-atlas-2026.md) | Dwanaście języków wizualnych, trend slop, czytanie plansz referencyjnych |
 | [Formaty statyczne](references/static-ad-formats.md) | Szkielety perswazji, dowód, lejek i dopasowanie do branży |
 | [Przykłady promptów](examples/05-model-independent-directions.md) | Flyer, gastronomia i usługa lokalna |
 | [Kierunki 2026](examples/07-2026-style-directions.md) | Briefy „format + styl” i zestaw kampanii pod Andromedę |
-| [Visual Advertising Engine](visual-advertising-engine.md) | Kanoniczne reguły R01–R48 |
+| [Visual Advertising Engine](visual-advertising-engine.md) | Kanoniczne reguły R01–R52 |
 | [Layout system](references/layout-system.md) | Punkty wyjścia dla siatki, marginesów i skali tekstu |
+| [Diagnostyka kreacji](references/creative-diagnostics.md) | Z eksportu Ads Managera do kolejnego briefu (`scripts/creative_diagnostics.py`) |
 | [Platformy](references/platform-compliance.md) | Strefy bezpieczne, limity tekstu, Advantage+, etykiety AI |
 | [QA gate](references/qa-gate.md) | Ocena rzeczywiście wygenerowanych obrazów |
 | [Pozostałe przykłady](examples/README.md) | Briefy, prompty i omówienie decyzji |
@@ -124,6 +131,7 @@ Prompt wyraża intencję projektową. Nie gwarantuje identycznego fontu, położ
 pip install -r requirements.txt
 python scripts/check_docs.py
 python scripts/test_qa.py
+python scripts/test_diagnostics.py
 ```
 
 Kontrole dokumentacji sprawdzają linki, odwołania do reguł i wersje. Skrypt QA bada wybrane cechy techniczne obrazu; ocenę kompozycji, wiarygodności i zgodności z briefem trzeba wykonać osobno. Wyniki kampanii wymagają pomiaru po publikacji.