### Diagram: Customer Journey + checklisty SEO (high‑level)

```mermaid
flowchart LR
    A[Inicjacja<br/>Awareness] --> B[Badania<br/>Consideration]
    B --> C[Porównywanie<br/>Evaluation]
    C --> D[Transakcja<br/>Decision]
    D --> E[Doświadczenie<br/>Retention]

    subgraph S1["Inicjacja – SEO"]
        A1["Poradniki: co to jest / jak działa"]
        A2["Treści problemowe"]
        A3["FAQ / Glossary"]
        A4["Checklisty startowe"]
    end

    subgraph S2["Badania – SEO"]
        B1["Rankingi TOP"]
        B2["Przewodniki zakupowe"]
        B3["Opinie / Recenzje"]
        B4["Case studies"]
    end

    subgraph S3["Porównywanie – SEO"]
        C1["X vs Y"]
        C2["Alternatywy"]
        C3["Tabele porównawcze"]
        C4["Kalkulatory"]
    end

    subgraph S4["Transakcja – SEO"]
        D1["Strony produktowe"]
        D2["Cenniki / Pakiety"]
        D3["Gdzie kupić"]
        D4["Landing pages"]
    end

    subgraph S5["Doświadczenie – SEO"]
        E1["Instrukcje How-To"]
        E2["Troubleshooting"]
        E3["Knowledge Base"]
        E4["Cross-sell / Up-sell"]
    end

    A --> A1
    A --> A2
    A --> A3
    A --> A4

    B --> B1
    B --> B2
    B --> B3
    B --> B4

    C --> C1
    C --> C2
    C --> C3
    C --> C4

    D --> D1
    D --> D2
    D --> D3
    D --> D4

    E --> E1
    E --> E2
    E --> E3
    E --> E4

```

***

### Wariant alternatywny (jeśli chcesz **czystszy diagram pod README / GitHub**)

Bez `<br/>`, tylko ASCII — **najmniej awaryjna wersja**:

```mermaid
flowchart LR
    Inicjacja --> Badania --> Porownywanie --> Transakcja --> Doswiadczenie

    Inicjacja --> I1["Poradniki"]
    Inicjacja --> I2["FAQ"]
    Inicjacja --> I3["Problemy"]

    Badania --> B1["Rankingi"]
    Badania --> B2["Przewodniki"]
    Badania --> B3["Opinie"]

    Porownywanie --> P1["X vs Y"]
    Porownywanie --> P2["Alternatywy"]

    Transakcja --> T1["Produkt"]
    Transakcja --> T2["Cena"]
    Transakcja --> T3["Kup teraz"]

    Doswiadczenie --> D1["Instrukcje"]
    Doswiadczenie --> D2["Pomoc"]
```

## Diagram Mermaid: AI Content Ops dla SEO (per etap)

```mermaid
flowchart TB
  %% =========================
  %% AI SEO CONTENT OPS PIPELINE
  %% =========================

  subgraph G["Globalne bramki QA (AI) - obowiazkowe dla kazdej strony"]
    G1["Meta: Title + Description (unikalne, zgodne z intencja)"] 
    G2["On-page: H1/H2, odpowiedz na intencje, linkowanie wewn."]
    G3["Tech: indexing, duplicate content, canonical, pagination"] 
    G4["Structured Data: FAQ/HowTo/Product/Review (gdy pasuje)"]
    G5["UX: link text opisowy + crawlable"]
    G6["Mobile-first + performance budzet"]
  end

  subgraph P["AI Pipeline (jedna iteracja)"]
    P0["Brief: etap + persona + intencja + KPI"]
    P1["Research: SERP intents + PAA/FAQ + konkurencja"]
    P2["Plan: outline H2/H3 + mapa linkow (prev/next etap)"]
    P3["Draft: wersja 1 (z sekcja TLDR)"]
    P4["On-page pass: meta + naglowki + internal links"]
    P5["Schema pass: dobierz i wygeneruj JSON-LD"]
    P6["QA pass: zgodnosc z bramkami G1-G6"]
    P7["Publish: URL + breadcrumbs + monitoring"]
    P8["Measure: GSC/GA sygnaly + refresh plan"]
    P0 --> P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7 --> P8
  end

  %% =========================
  %% CUSTOMER JOURNEY STAGES
  %% =========================
  subgraph J["Customer Journey - etapy i AI deliverables"]
    A["Inicjacja (Awareness)"]
    B["Badania (Consideration)"]
    C["Porownywanie (Evaluation)"]
    D["Transakcja (Decision)"]
    E["Doswiadczenie (Retention)"]

    A --> B --> C --> D --> E
  end

  %% =========================
  %% PER-STAGE CONTENT OUTPUTS
  %% =========================
  subgraph OA["AI Output: Inicjacja"]
    A1["Content types: definicje, poradniki, problem->rozwiazanie, FAQ/glossary"]
    A2["Prompt focus: wyjasnij prosto, nie sprzedawaj, edukuj"]
    A3["Schema: FAQ / HowTo (jesli krok po kroku)"]
  end

  subgraph OB["AI Output: Badania"]
    B1["Content types: rankingi, przewodniki zakupowe, recenzje, case studies"]
    B2["Prompt focus: kryteria wyboru, metodologia, rekomendacje dla person"]
    B3["Schema: FAQ; (opcjonalnie) Review gdy masz realne dane"]
  end

  subgraph OC["AI Output: Porownywanie"]
    C1["Content types: X vs Y, alternatywy, tabele, kalkulatory, demo/walkthrough"]
    C2["Prompt focus: roznice, trade-offs, dla kogo co, obiekcje"]
    C3["Schema: FAQ; (opcjonalnie) HowTo dla konfiguracji"]
  end

  subgraph OD["AI Output: Transakcja"]
    D1["Content types: product/landing, pricing, gdzie kupic, kategorie z filtrami"]
    D2["Prompt focus: jasne value prop, CTA, dostepnosc, warunki"]
    D3["Schema: Product/Offer/Breadcrumb (gdy dotyczy)"]
  end

  subgraph OE["AI Output: Doswiadczenie"]
    E1["Content types: KB, instrukcje, troubleshooting, akcesoria/upsell"]
    E2["Prompt focus: szybka diagnoza, kroki naprawy, linki do powiazanych"]
    E3["Schema: HowTo / FAQ"]
  end

  %% =========================
  %% WIRING PIPELINE TO STAGES
  %% =========================
  A -. "AI iteracja P0-P8" .-> P0
  B -. "AI iteracja P0-P8" .-> P0
  C -. "AI iteracja P0-P8" .-> P0
  D -. "AI iteracja P0-P8" .-> P0
  E -. "AI iteracja P0-P8" .-> P0

  A --> OA
  B --> OB
  C --> OC
  D --> OD
  E --> OE

  %% QA gates referenced by pipeline
  P6 --> G1
  P6 --> G2
  P6 --> G3
  P6 --> G4
  P6 --> G5
  P6 --> G6
```

***

## Co dokładnie jest “AI‑ready” w tym diagramie (krótko i konkretnie)

1.  **Jednolity pipeline P0–P8** (agent robi zawsze te same kroki), a etap (A–E) jedynie **zmienia brief i outputy**.
2.  Masz wprost wpisane bramki jakości, które w materiałach wewnętrznych przewijają się jako SEO must‑have (duplicate/canonical/pagination/structured data/IA/perf/mobile). 
Diagram jest:

*   ✅ parsowalny
*   ✅ bez znaków problematycznych
*   ✅ nadaje się do README / dokumentacji systemowej
*   ✅ logicznie spójny z poprzednim diagramem (pipeline + QA gates)

***

## Diagram 2: AI Agent Router (Sequence Diagram)

```mermaid
sequenceDiagram
    autonumber

    participant HQ as HQ / Orchestrator
    participant R as ResearchAgent
    participant O as OutlineAgent
    participant W as WriterAgent
    participant S as SEOAgent
    participant C as SchemaAgent
    participant Q as QAAgent
    participant P as PublisherAgent
    participant A as AnalystAgent

    %% ===== BRIEF =====
    HQ->>R: Brief JSON (stage, persona, intent, keywords, KPI)

    %% ===== RESEARCH =====
    R->>R: SERP analysis + PAA + competitors
    R-->>HQ: Research JSON (intents, gaps, angles)

    %% ===== OUTLINE =====
    HQ->>O: Research JSON
    O->>O: Build outline (H1-H3, sections, FAQs)
    O-->>HQ: Outline JSON

    %% ===== WRITING =====
    HQ->>W: Outline JSON + tone rules
    W->>W: Draft content (TLDR, sections, internal links)
    W-->>HQ: Draft MD/HTML

    %% ===== ON-PAGE SEO =====
    HQ->>S: Draft + keyword map
    S->>S: Optimize titles, meta, headings, links
    S-->>HQ: SEO-ready content

    %% ===== STRUCTURED DATA =====
    HQ->>C: SEO-ready content
    C->>C: Generate JSON-LD (FAQ, HowTo, Product)
    C-->>HQ: Content + Schema

    %% ===== QUALITY GATES =====
    HQ->>Q: Content + Schema
    Q->>Q: QA checks (intent, dup, canonical, mobile, perf)
    Q-->>HQ: QA report (pass / fix list)

    %% ===== PUBLISH =====
    HQ->>P: Approved content
    P->>P: Publish + index + breadcrumbs
    P-->>HQ: URL + publish metadata

    %% ===== MEASURE & FEEDBACK =====
    HQ->>A: URL + KPI
    A->>A: Analyze GSC/GA signals
    A-->>HQ: Insights + refresh recommendations
```
***

## Jak to czytać (krótko, systemowo)

### 1. HQ / Orchestrator

*   jedyny „świadomy” agent
*   zna **etap customer journey**
*   decyduje **kiedy iterować, a kiedy publikować**

### 2. Agenci są **wąsko wyspecjalizowani**

*   Research ≠ Outline ≠ Writing ≠ SEO ≠ Schema ≠ QA
*   zero mieszania odpowiedzialności

### 3. Artefakty są jawne

*   **JSON** → decyzje
*   **MD / HTML** → treść
*   **JSON‑LD** → struktura
*   **QA report** → bramka decyzyjna

To dokładnie pasuje do Twojego podejścia:

> *deterministyczne, audytowalne, reproducible workflows*

***

## Bonus: mapowanie agentów na etapy (mental model)

| Etap          | Najważniejszy agent |
| ------------- | ------------------- |
| Inicjacja     | Research + Writer   |
| Badania       | Outline + Writer    |
| Porównywanie  | Writer + SEO        |
| Transakcja    | SEO + Schema        |
| Doświadczenie | QA + Analyst        |