create-new-funnel

/create-new-funnel — Orchestrator

Sei una guida passo-passo per creare una pagina funnel Shopify da zero. Il funnel è una pagina (templates/page.*) non un prodotto: ospita contenuti storytelling / listicle / quiz che portano l'utente a cliccare una CTA verso una PDP esistente.

Segui le 9 fasi in sequenza. Non saltare fasi. Usa AskUserQuestion come gate tra una fase e la successiva.

Principi generali

• 🔒 Mai toccare template o sezioni esistenti. Le PDP e altre page template dello store sono intoccabili. Il funnel vive in file nuovi con prefisso nuovo (mai uguale a uno già presente).
• Brand-consistent: i colori e font del funnel vengono ereditati da una PDP di riferimento (Fase 3). Non inventare palette/tipografia.
• CTA → PDP: tutti i bottoni CTA del funnel puntano all'URL PDP del prodotto fornito in Fase 5. Mai href="#" o URL placeholder.
• Mobile-first: il traffico funnel è >80% mobile (ads paid). Ogni sezione deve leggersi benissimo a 375px.
• No framework esterni: niente Tailwind, Bootstrap, ecc. Solo CSS scoped dentro la sezione, con class-prefix che match del prefisso file.
• Un push per volta, selettivo. Mai theme push senza --only. Il --only include SOLO i file del nuovo funnel.
• Conferma prima di ogni azione irreversibile (creazione file, push live, rinomina).

Lettura dello stato iniziale

All'avvio devi trovare il file config/stores.json del plugin.

REGOLA ASSOLUTA — senza eccezioni, senza interpretazione:

1. NON creare MAI nessun file dentro ~/.claude/skills/. Quella cartella contiene solo i symlink di sviluppo. Se stai per scrivere un file il cui path contiene .claude/skills/, fermati subito: è sbagliato.
2. stores.json vive SOLO nella cartella del plugin, cioè <plugin-root>/config/stores.json. Mai altrove.
3. stores.example.json esiste già nel repo — non va mai creato né copiato dalla skill.

Procedura deterministica (esegui nell'ordine, senza saltare step):

# Step A — prova path canonico
test -f "$HOME/Desktop/shopify-pdp-builder/config/stores.json" && echo "FOUND:$HOME/Desktop/shopify-pdp-builder/config/stores.json"

# Step B — risolvi via symlink della skill (se A non ha trovato nulla)
PLUGIN_ROOT=$(dirname "$(dirname "$(readlink "$HOME/.claude/skills/create-new-funnel")")")
test -f "$PLUGIN_ROOT/config/stores.json" && echo "FOUND:$PLUGIN_ROOT/config/stores.json"

# Step C — prova il path plugin standard di Claude Code
test -f "$HOME/.claude/plugins/shopify-pdp-builder/config/stores.json" && echo "FOUND:$HOME/.claude/plugins/shopify-pdp-builder/config/stores.json"

Comportamento:

• Se uno qualsiasi degli step stampa FOUND:<path> → usa quel path con Read per leggere stores.json e procedi con la Fase 1.
• Se tutti e tre falliscono → FERMATI. Non scrivere nulla. Chiedi all'utente in chiaro: "Non trovo config/stores.json. Dimmi il path assoluto del plugin shopify-pdp-builder sul tuo disco." Attendi risposta, poi ricontrolla.

Mai usare Write o Edit per creare stores.json o stores.example.json. Se manca, è un problema di setup utente, non un file da generare dalla skill.

---

Rilevamento "sandbox mode" (Working Suite)

Subito dopo aver caricato stores.json e prima della Fase 1, esegui questo check deterministico:

# Working Suite host la skill dentro un proprio runtime sandbox e inietta 2 env var.
# Standalone (uso diretto dell'utente) → entrambe assenti → modalità normale.
# Sandbox WS → entrambe presenti → modalità sandbox.
test -n "$WSA_INTERNAL_KEY" && test -n "$WSA_DAEMON_URL" && echo "SANDBOX:1" || echo "SANDBOX:0"

Salva in memoria:

• ws.sandbox_mode = true se l'output è SANDBOX:1.
• ws.sandbox_mode = false altrimenti.
• Se sandbox_mode = true: salva ws.daemon_url = $WSA_DAEMON_URL e ws.internal_key = $WSA_INTERNAL_KEY (NON loggare mai internal_key in chiaro, mai includerla in artefatti generati).

Effetti del sandbox mode (li applicherai più avanti, qui solo riferimento):

• Fase 4 — funnel.type è forzato ad advertorial, niente AskUserQuestion per il tipo. Stampa una nota informativa all'utente: "Sandbox mode (Working Suite) rilevato → tipo funnel forzato a advertorial. Le altre tipologie sono disponibili solo in modalità standalone."
• Verifica finale — dopo che tutti i check passano e il funnel è live, esegui la Fase 10 — Notifica Working Suite (in fondo a questo file).

Se solo UNA delle due env vars è presente (es. WSA_INTERNAL_KEY ma non WSA_DAEMON_URL): è un setup parziale errato. Stampa un warning chiaro e procedi in modalità standalone (sandbox_mode = false). NON fare il bridge call: meglio standalone visibile che bridge silenziosamente broken.

---

Fase 1 — Scelta store

Mostra all'utente la lista store configurati. Usa AskUserQuestion con un'opzione per store + "Altro".

Se "Altro": chiedi nome, shopify_domain (*.myshopify.com), theme ID, path workdir, path env. Aggiungi voce a stores.json.

Salva in memoria: store.name, store.shopify_domain, store.theme_id, store.workdir_path, store.env_path.

---

Fase 2 — Verifica auth + scelta tema

1. Se store.env_path non esiste: guida alla creazione del .env (Theme Access token → shptka_*). Fonte: references/auth-pattern.md.
2. Lancia:

   cd "<store.workdir_path>"
   set -a; source "<store.env_path>"; set +a
   npx @shopify/cli@latest theme list --no-color
   

3. Se 401 / Invalid API key: token scaduto, utente rigenera e riprova.
4. Mostra i temi parsati: [live], [unpublished], [development] con nome + ID.
5. AskUserQuestion: "Su quale tema operare?" Default: [live] (o store.theme_id del config). Opzioni: una per tema.
6. Salva scelta in store.theme_id (sovrascrive config per sessione) e store.theme_name.
7. Pull fresco:

   cd "<store.workdir_path>"
   set -a; source "<store.env_path>"; set +a
   npx @shopify/cli@latest theme pull --theme <store.theme_id> --nodelete
   

   Chiedi conferma prima (il pull sovrascrive file locali non pushati).

---

Fase 3 — Brand identity discovery

Obiettivo: capire palette + tipografia del brand per mantenere il funnel visivamente coerente col resto del sito. Fonte di verità: references/brand-identity-discovery.md.

3.1 Scelta PDP di riferimento

1. Elenca i product.*.json in <store.workdir_path>/templates/.
2. AskUserQuestion: "Quale PDP usare come riferimento per colori e tipografia?"
   • Mostra i nomi leggibili (es. berberina-pills, crema-borse-occhiaie-pdp).
   • Se ce n'è uno solo (oltre al default product.json) assumilo automaticamente.
3. Salva in brand.reference_pdp.

3.2 Estrazione automatica

Leggi in parallelo:

• templates/product.<reference>.json
• 2-3 sezioni principali referenziate (hero, prima sezione con CTA button)
• config/settings_data.json (color_schemes + type_header_font + type_body_font)
• config/settings_schema.json (opzionale, per nomi umani dei settings)

Estrai secondo le regole di brand-identity-discovery.md:

• Palette: primary, primary_text, secondary, accent, text, background (HEX).
• Tipografia: heading_font, body_font (normalizzati da Shopify handle a "Nome, fallback").
• Stili ricorrenti: border-radius, shadow, heading weight/style.

3.3 Mostra riepilogo e chiedi conferma

Presenta all'utente un blocco leggibile (esempio in brand-identity-discovery.md, sezione "Output atteso"). Usa AskUserQuestion o chiedi in chiaro:

• "Confermi questo brand profile?" → procedi.
• "Correggo un valore" → l'utente dice cosa cambiare, applica, ripresenta.
• "Cambio PDP di riferimento" → torna a 3.1.

Salva l'oggetto brand.* in memoria. Verrà iniettato nelle sezioni in Fase 8.

---

Fase 4 — Scelta tipo di funnel

PRIMA di creare il template, devi sapere che tipo di funnel stiamo costruendo. Tipo e materiali informeranno il nome del template, il prefisso sezioni e la struttura.

Sandbox mode (Working Suite) — se ws.sandbox_mode == true (vedi sezione "Rilevamento sandbox mode" prima della Fase 1): NON eseguire AskUserQuestion. Setta direttamente funnel.type = 'advertorial' e stampa una nota informativa all'utente:

"Sandbox mode (Working Suite) rilevato. Tipo funnel forzato a advertorial per coerenza con la pipeline WS. Le altre tipologie restano disponibili in modalità standalone."

Poi procedi alla Fase 5.

Modalità standalone (ws.sandbox_mode == false) — comportamento normale:

AskUserQuestion: "Che tipo di funnel stiamo creando?"

Opzioni:

• Advertorial — articolo narrativo, storytelling personale che porta a PDP. Target freddo.
• Listicle — articolo "N motivi per", benefici ordinati, confronto. Target semi-caldo.
• Quiz — domande + risultato personalizzato, engagement-driven. Target freddo.
• Altro — descrivi liberamente la struttura, poi forniamo esempi.

Salva in funnel.type ∈ {advertorial, listicle, quiz, other}.

Carica la struttura base di riferimento da references/funnel-types.md per il tipo scelto. Sarà usata come ipotesi di partenza in Fase 5; verrà raffinata con gli esempi competitor sempre in Fase 5.

Se other: chiedi all'utente una descrizione della struttura che ha in mente (numero sezioni, ordine, ruoli).

---

Fase 5 — Struttura funnel (URL destinazione + competitor)

Questa fase serve SOLO a definire la STRUTTURA del funnel (quante sezioni, in che ordine, con che ruolo). Non chiedere ancora i contenuti del prodotto — quelli vengono nella Fase 6.

5.1 URL PDP destinazione (OBBLIGATORIO)

AskUserQuestion o chiedi in chiaro: "Qual è l'URL della PDP di destinazione? (dove porteranno tutte le CTA del funnel)"

Esempi:

• https://nimea-beauty.it/products/crema-borse-occhiaie-ufficiale
• https://glowria.com/products/crema-corpo-autoabbronzante-ufficiale

Valida che:

• Inizia con https://.
• Contiene /products/<slug>.

Salva in funnel.cta_url. Sarà il href di TUTTI i bottoni CTA del funnel.

5.2 Esempi competitor del tipo scelto

Chiedi 2-5 URL / screenshot di funnel competitor dello stesso tipo (funnel.type di Fase 4). Per ogni esempio chiedi un contesto breve: perché ti piace, cosa copieresti, cosa cambieresti.

Se l'utente non ha esempi: suggerisci Facebook Ads Library, swipefile.com, aggregator tipo advertorial.com. Se l'utente risponde skip: procedi con la struttura base di references/funnel-types.md per il tipo scelto.

Claude analizza i competitor per:

• Confermare/raffinare la struttura di partenza (aggiungere/rimuovere/riordinare sezioni).
• Identificare pattern ricorrenti di hook, problem, proof, CTA.
• Stimare lunghezza/density media (word count per sezione).

5.3 Struttura proposta + conferma

Presenta all'utente la struttura sezioni definitiva (dopo l'analisi competitor):

Struttura advertorial proposta (11 sezioni, basata su 3 competitor + base):

01. announcement   — top bar urgency/offer
02. hero           — headline + foto protagonista + CTA 1
03. problem-hook   — amplifica dolore, identifica target
04. story          — storia personale (before/after narrativo)
05. solution-intro — presentazione prodotto come risposta
06. how-it-works   — 3 step + ingredienti chiave
07. social-proof   — testimonianze + recensioni
08. faq            — 5-7 obiezioni gestite
09. cta-offer      — offerta + urgency + CTA 2
10. trust-badges   — garanzia / spedizione / pagamenti
11. footer         — disclaimer legale

AskUserQuestion: "Confermi questa struttura o vuoi modificarla?" — l'utente può aggiungere/rimuovere/riordinare/rinominare.

Salva la lista finale in funnel.sections_plan (array ordinato con nn, role, notes).

---

Fase 6 — Studio prodotto + angle marketing

Questa è la fase più articolata del funnel (advertorial in particolare). A differenza della PDP che è "solo" riscrittura testi, qui devi capire il prodotto in profondità e scegliere un angle (l'angolazione narrativa) che renderà l'advertorial convincente.

L'obiettivo: arrivare a fine fase con abbastanza materiale per scrivere hook + story + proof + obiezioni che girino attorno a un angle chiaro.

6.1 Studio della PDP propria

Claude fetcha e legge funnel.cta_url (PDP di destinazione, Fase 5.1). Usa WebFetch sull'URL per estrarre:

• Nome prodotto esatto come usato sullo store.
• Claim principali (H1, H2, bullet benefici).
• Ingredienti chiave / tecnologia / brevetti citati.
• Proof points già in pagina (numeri, certificazioni, test clinici).
• Prezzo + eventuali varianti/bundle.
• Tono di voce della PDP.

Presenta un riepilogo strutturato all'utente e chiedi cosa manca / cosa è sbagliato (spesso le PDP sono ottimizzate per conversione diretta, non per storytelling — l'utente ha info extra).

Salva in product.*.

6.2 Studio PDP competitor (stessa categoria)

AskUserQuestion o chiedi: "Dammi 2-3 URL di PDP competitor nello stesso spazio prodotto."

Per ciascuna: WebFetch + estrai claim, ingredienti, proof, pricing, posizionamento.

Obiettivo: capire come gli altri comunicano lo stesso problema/soluzione e trovare lo spazio bianco dove il nostro prodotto può differenziarsi.

Output: tabella sintetica competitor vs nostro, con colonne claim_primario, differenziatore, prezzo, gap.

6.3 Analisi angle competitor + proposta (OBBLIGATORIO)

Step fisso, non saltabile. Dopo aver studiato le PDP competitor (6.2), identifica l'angle dominante prima di chiedere alternative.

1. Identifica il MAIN ANGLE usato dai competitor (dalle PDP analizzate in 6.2 + dai funnel competitor di Fase 5.2). L'angle è l'angolazione narrativa — NON un claim, è il frame da cui il prodotto viene raccontato. Esempi:

   • "Ingrediente scientifico esclusivo" (angle scientifico)
   • "Routine naturale di 5 minuti al giorno" (angle lifestyle)
   • "Alternativa economica al trattamento estetico da €300" (angle risparmio)
   • "Before/after reale di persone come te" (angle social proof)
   • "Risolve X in N giorni — garantito" (angle result-driven)

2. Presenta il main angle all'utente con evidenze concrete:

   Dall'analisi competitor emerge questo angle dominante:
   
   ➤ ANGLE: <frase di 1 riga>
      Evidenze:
      - Competitor A (URL): <frase/claim specifica che lo dimostra>
      - Competitor B (URL): <idem>
      - Funnel competitor X (URL): <idem>
   

3. Chiedi anche gli ads attuali del nostro prodotto:

   • 1-3 copy ads attualmente girati (headline + body + concept video, se ci sono).
   • Se l'utente risponde skip: OK, procedi.

4. AskUserQuestion: "Vuoi usare questo stesso angle per il nostro funnel?"

   • Sì, uso questo angle → salva in funnel.angle e procedi a 6.4.
   • No, proponimi alternative → vai al punto 5.
   • Ho un angle mio in mente → l'utente lo descrive, salva e procedi.

5. Se l'utente chiede alternative: proponi 2-3 angle alternativi che sono:

   • Usati in adiacenza (competitor minori, prodotti simili della stessa categoria).
   • Coerenti con i proof points / ingredienti del nostro prodotto (niente angle insostenibili).
   • Differenzianti rispetto al main angle (per evitare "l'ennesima copia di X").

   Ogni alternativa presentata con: nome angle + 1 frase di pitch + perché funzionerebbe meglio del main. Poi AskUserQuestion di scelta finale.

Salva in funnel.angle — sarà la bussola narrativa di TUTTE le sezioni.

6.4 Research prodotto — rifinitura finale

Consolida in bullet veloci (l'utente può completare/correggere quello che Claude ha estratto):

• Nome prodotto esatto (da PDP).
• Ingredienti chiave (3-5, con effetto specifico legato all'angle scelto).
• Claim principali (3-5, formulati in linea con l'angle).
• Target audience: chi, età, problema specifico (non generico).
• Differenziazione vs competitor (dal gap di 6.2).
• Proof points: numeri, test, recensioni reali, certificazioni, testimoni.
• Obiezioni tipiche che l'advertorial deve gestire (3-5, dalla Facebook Ads Library o da commenti reali).

Se uno di questi campi è debole, Claude lo segnala esplicitamente ("Proof points: nessun numero concreto — l'advertorial sarà meno convincente. Vuoi aggiungerne?").

6.5 Brand assets extra

Chiedi:

• Logo URL CDN (se diverso da quello del tema).
• Eventuali foto prodotto custom, mockup, loghi certificazioni da usare.

Se skip: usa solo quelli estraibili da tema + PDP.

6.6 Riepilogo finale prima del template

Mostra un blocco compatto:

• Tipo funnel + struttura confermata (N sezioni, da Fase 5.3).
• Angle scelto (una frase).
• 3 claim centrali.
• 3 proof points.
• 3 obiezioni da gestire.
• URL CTA.
• Palette + tipografia (richiama brand.* da Fase 3).

AskUserQuestion: "Tutto chiaro, procedo con la creazione del template?"

---

Fase 7 — Creazione template funnel

Ora che conosci tipo + materiali, puoi creare il template con un nome sensato.

7.1 Scelta partenza

AskUserQuestion: "Partire da zero o duplicare un template page esistente?"

• Da zero (default, caso tipico).
• Duplica esistente (se il team ha già un funnel "buono" da cui partire).

Se duplica: riusa il flusso della Fase 3 di /create-new-pdp (lista page.*.json, prefisso, duplicazione sezioni). Fonte: references/section-naming.md.

7.2 Nome nuovo template

AskUserQuestion: "Nome del nuovo template funnel?"

Proponi 2-3 default intelligenti che combinano slug prodotto (dedotto da funnel.cta_url di Fase 5.3) + tipo funnel (funnel.type di Fase 4). Esempi:

• Prodotto crema-borse-occhiaie + tipo advertorial → crema-borse-occhiaie-advertorial
• Prodotto berberina-pills + tipo listicle → berberina-pills-listicle
• Prodotto crema-rassodante + tipo quiz → crema-rassodante-quiz

Vincoli:

• Kebab-case, solo [a-z0-9-].
• Valida che <workdir>/templates/page.<nome>.json NON esista.

Salva in funnel.template_name.

7.3 Layout — header/footer on/off

AskUserQuestion: "Mantenere header e footer Shopify?"

Opzioni:

• No, chromeless (Recommended) → pagina full-screen senza navbar/footer. Layout: theme.chromeless (se supportato) o custom.
• Sì, tema standard → header + footer del tema sempre visibili. Layout: theme.

Fonte: references/page-template-layout.md.

Se l'utente sceglie chromeless:

• Verifica con Glob o ls se esiste <workdir>/layout/theme.chromeless.liquid.
• Se NO: chiedi all'utente se vuole (a) creare un layout custom chromeless ora, (b) procedere con theme e poi decidere, (c) usare nome layout diverso.
• Se SÌ: usa direttamente "layout": "theme.chromeless".

Salva in funnel.layout.

7.4 Prefisso sezioni

Proponi un prefisso di default derivato da funnel.template_name (vedi references/section-naming.md, sezione "Naming per FUNNEL"):

• crema-borse-occhiaie-advertorial → cbo-adv- (esplicita) o cbo- (breve).
• berberina-listicle → bl- o bb-lst-.

AskUserQuestion: "Prefisso sezioni: <default>? (conferma o alternativo)"

Salva in funnel.prefix.

7.5 Generazione template scheletro

Scrivi templates/page.<funnel.template_name>.json con scheletro minimo:

{
  "sections": {},
  "order": [],
  "layout": "<funnel.layout>"
}

(Le sezioni verranno aggiunte progressivamente in Fase 8.)

Se si è scelta la duplicazione da template esistente (7.1): applica la logica di duplicazione della Fase 3 PDP e salta i punti seguenti.

7.6 Push selettivo template

cd "<store.workdir_path>"
set -a; source "<store.env_path>"; set +a
npx @shopify/cli@latest theme push \
  --theme <store.theme_id> --nodelete --allow-live \
  --only "templates/page.<funnel.template_name>.json"

7.7 Istruzioni manuali Page in Admin

Mostra all'utente:

Ora crea la Page in Shopify Admin:
1. Admin → Online Store → Pages → Add page
2. Title: "<titolo visibile della pagina>"
3. Content: lascialo vuoto (le sezioni vengono dal template)
4. In "Theme template" (sidebar destra): seleziona `<funnel.template_name>`
5. Save
6. Torna qui e dimmi lo slug della page (es. `scopri-autoabbronzante`)

Salva lo slug in funnel.page_slug. URL live: https://<store.shopify_domain>/pages/<funnel.page_slug>.

---

Fase 8 — Costruzione sezioni

8.0 Scelta modalità di lavoro (obbligatoria)

AskUserQuestion: "Come vuoi lavorare sulle sezioni?"

Opzione A — Sezione per sezione (Recommended per prima PDP) Per ogni sezione: crea file → push → verifica live → conferma → prossima sezione. Più lento ma sicuro.

Opzione B — Batch Crea tutte le sezioni in parallelo → mostra preview completa → l'utente approva una volta → push finale unico. Più veloce ma meno granulare.

Opzione C — Misto leggero Checkpoint intermedi solo sulle sezioni complesse (hero, CTA offer, quiz-wrapper). Sezioni semplici (FAQ, footer, closing) passano in batch senza conferma individuale. Compromesso consigliato per utenti già rodati.

Salva scelta in funnel.build_mode ∈ {A, B, C}.

8.1 Pianifica la lista sezioni

In base a:

• Struttura confermata in Fase 5.3 (funnel.sections_plan).
• Angle scelto in Fase 6.3 (funnel.angle).

Produci una lista esplicita con nome file + ruolo + note:

Struttura pianificata (es. advertorial, prefisso `aa-`):

01. sections/aa-01-announcement.liquid  → announcement bar
02. sections/aa-02-hero.liquid          → hero advertorial
03. sections/aa-03-problem.liquid       → problem hook
04. sections/aa-04-story.liquid         → storia personale
05. sections/aa-05-solution.liquid      → intro prodotto
06. sections/aa-06-how-it-works.liquid  → come funziona + ingredienti
07. sections/aa-07-proof.liquid         → social proof
08. sections/aa-08-faq.liquid           → obiezioni
09. sections/aa-09-cta-offer.liquid     → CTA + offer
10. sections/aa-10-trust-badges.liquid  → badge garanzia
11. sections/aa-11-footer.liquid        → footer disclaimer

AskUserQuestion di conferma/modifica. L'utente può aggiungere, rimuovere, riordinare, rinominare sezioni.

8.2 Regole per ogni sezione costruita

Per ogni sections/<funnel.prefix><NN>-<ruolo>.liquid:

1. Markup mobile-first, poi @media (min-width: 768px) per desktop. Classi scoped con prefisso che matcha il nome file (es. tutte le classi dentro aa-02-hero.liquid iniziano con .aa-02).
2. Stili inline nel file .liquid dentro <style> scoped (no assets/*.css esterni a meno che sia strettamente necessario). Usa valori di brand.*:
   • Bottoni CTA: background: <brand.primary>, color: <brand.primary_text>, border-radius: <brand.button_radius>, hover più scuro.
   • Headline: font-family: <brand.heading_font>, font-weight: <brand.heading_weight>.
   • Body: font-family: <brand.body_font>, color: <brand.text>.
3. Testi dal research di Fase 6.4 + angle di Fase 6.3 + ispirazione competitor di Fase 5.2, con density/lunghezza coerente al ruolo (vedi references/funnel-types.md).
4. Bottoni CTA puntano a <funnel.cta_url> con <a class="<prefix>__cta" href="<funnel.cta_url>">. Ripeti la CTA almeno 2 volte nel funnel (hero + closing minimo).
5. Tutto editabile dal theme editor — regola fissa. Ogni sezione funnel nasce editabile: testi, immagini, CTA sono section.settings.* / block.settings.* nello schema, mai hardcoded nel markup. Fonte: references/section-schema-patterns.md.
   • Testi: type: "text" per singola riga, type: "textarea" per multiriga semplice, type: "richtext" per paragrafi con inline bold/italic/link (l'editor mostra WYSIWYG).
   • Immagini: type: "image_picker". Mai <img src="https://cdn..." hardcoded. Render via {{ section.settings.<id> | image_url: width: <W> }} per responsive automatico Shopify.
   • CTA: coppia type: "url" + type: "text" per ciascun bottone. href iniziale default = funnel.cta_url (Fase 5.1).
   • Liste ripetibili (FAQ, benefit cards, testimonial, reason cards listicle, domande quiz): usa blocks con type dedicato e max_blocks sensato. Iterazione via {% for block in section.blocks %} nel markup.
   • Default sensati: ogni setting/block ha default popolato dal research/angle di Fase 6, così la pagina live mostra già contenuto reale subito dopo il push, senza passare dall'editor.
   • Placeholder immagini: l'image_picker resta senza default (o con default placeholder SVG data-uri). Il markup gestisce lo stato "vuoto":

     {% if section.settings.hero_image %}
       <img src="{{ section.settings.hero_image | image_url: width: 1600 }}" alt="{{ section.settings.hero_image.alt }}" loading="lazy">
     {% else %}
       <img src="data:image/svg+xml,%3Csvg…%3E" alt="IMG_PLACEHOLDER_02_hero">
     {% endif %}
     

6. Schema Liquid completo (esempio minimo, estendi con tutti i settings/blocks della sezione):

   {% schema %}
   {
     "name": "<NOME LEGGIBILE SEZIONE>",
     "tag": "section",
     "class": "<prefix>-<NN>",
     "settings": [
       { "type": "text", "id": "heading", "label": "Titolo", "default": "…" },
       { "type": "richtext", "id": "body", "label": "Testo", "default": "<p>…</p>" },
       { "type": "image_picker", "id": "hero_image", "label": "Immagine hero" },
       { "type": "url", "id": "cta_url", "label": "Link CTA", "default": "<funnel.cta_url>" },
       { "type": "text", "id": "cta_label", "label": "Testo CTA", "default": "Scopri di più" }
     ],
     "presets": [
       { "name": "<NOME LEGGIBILE SEZIONE>" }
     ]
   }
   {% endschema %}
   

7. Aggiorna il template JSON templates/page.<funnel.template_name>.json:
   • Aggiungi la sezione al blocco sections:

     "<NN>": { "type": "<funnel.prefix><NN>-<ruolo>", "settings": {} }
     

   • Aggiungi la chiave all'array order nella posizione giusta.

8.3 Workflow per Opzione A (sezione per sezione)

Loop sulle sezioni in ordine 01→N:

1. Crea il file .liquid con Write.

2. Aggiorna templates/page.<funnel.template_name>.json aggiungendo la nuova sezione (usa Edit o Read+Write).

3. Push selettivo:

   cd "<store.workdir_path>"
   set -a; source "<store.env_path>"; set +a
   npx @shopify/cli@latest theme push \
     --theme <store.theme_id> --nodelete --allow-live \
     --only "sections/<funnel.prefix><NN>-<ruolo>.liquid" \
     --only "templates/page.<funnel.template_name>.json"
   

4. Chiedi all'utente di aprire https://<store.shopify_domain>/pages/<funnel.page_slug> e confermare mobile+desktop.

5. Gestisci aggiustamenti minimi (typo, font-size, spacing) in loop finché confermato.

6. Prima di passare alla sezione successiva, chiedi esplicitamente con AskUserQuestion:

   "Sezione confermata. Come vuoi procedere con le restanti N sezioni?"

   • Continua sezione-per-sezione → ripeti il ciclo dal punto 1 sulla prossima sezione.
   • Passa a batch (completa tutte le restanti insieme) → switcha al workflow 8.4 (Opzione B batch) per le sezioni ancora da fare. Il progresso sulle sezioni già confermate resta intatto.
   • Passa a misto leggero → switcha al workflow 8.5 (Opzione C) per le sezioni ancora da fare.

   Rispetta la scelta. Non dare per scontato che l'utente voglia finire in una modalità solo perché ha iniziato così.

8.4 Workflow per Opzione B (batch)

1. Crea TUTTI i file .liquid in parallelo (multiple Write nel singolo messaggio).
2. Scrivi il templates/page.<funnel.template_name>.json definitivo con tutte le sezioni ordinate.
3. Mostra all'utente un diff-preview testuale della struttura e i punti chiave di ogni sezione (headline + primo paragrafo). Non dump di tutto il markup.
4. Aspetta approvazione globale o correzioni puntuali.
5. Push selettivo unico con --only di tutti i file (template + sezioni in un comando).
6. Utente verifica live.
7. Aggiustamenti successivi: passa automaticamente a modalità sezione-per-sezione per i fix puntuali.

8.5 Workflow per Opzione C (misto leggero)

1. Identifica sezioni "complesse" (hero, problem, solution, proof, cta-offer, quiz-wrapper, result) vs "semplici" (announcement, trust-badges, faq, footer, disclaimer).
2. Per le complesse: workflow A (checkpoint individuale).
3. Per le semplici: crea in batch, push unico intermedio senza conferma per ciascuna.
4. A fine fase: pull completo live, utente verifica tutto insieme.

8.6 Verifica no-regressioni

Prima di ogni push: conferma a te stesso di non aver aperto/modificato per sbaglio file esistenti fuori dal prefisso <funnel.prefix>. Se è successo: stop, ripristina, riprova.

---

Fase 9 — Guida immagini

Le sezioni sono tutte editabili: ogni immagine è un image_picker nello schema. L'utente le carica dal theme editor, non via URL CDN incollato in chat. Fonte: references/funnel-image-specs.md (specs) + references/section-schema-patterns.md (pattern editor).

Per ogni sezione con uno o più image_picker:

1. Identifica dal markup/schema quante immagini servono e il ruolo di ciascuna (grep image_picker nello schema della sezione).
2. Genera il brief:

   Sezione: <prefix>-<NN>-<ruolo>.liquid
   Immagini richieste: <N>
   
   Per ogni immagine:
     - Ruolo: <es. "hero lifestyle protagonista + emozione">
     - Ratio: <4:5>
     - Dimensioni: <1200×1500>
     - Peso max: 150 KB (.webp)
     - Campo theme editor: "<label del image_picker>"
   

3. Istruzioni utente:

   1. Apri il theme editor: Admin → Online Store → Themes → Customize (tema <store.theme_name>).
   2. Nel top-left picker seleziona Pages → <titolo pagina funnel>.
   3. Nella sidebar sezioni click su <prefix>-<NN>-<ruolo>.
   4. Per ogni campo immagine: click → Select image → Upload → salva.
   5. Save del theme editor.
   

4. L'utente conferma in chat quando ha fatto.
5. Nessun push necessario: le immagini si salvano lato Shopify come setting del template, non nel file .liquid.
6. Chiedi conferma visiva sull'URL live della page.

Modalità di gestione: la stessa funnel.build_mode di Fase 8 (A singola / B batch / C misto) — l'utente può fare tutte le immagini di tutte le sezioni in un passaggio unico nell'editor, poi checkpoint visivo finale.

---

Verifica finale

Checklist chiusura:

• Template templates/page.<funnel.template_name>.json pushato e sincronizzato.
• Tutte le sezioni pushate, schema Liquid senza errori.
• URL live funzionante: https://<store.shopify_domain>/pages/<funnel.page_slug>.
• Mobile 375px: tutte le sezioni leggibili, bottoni cliccabili, testi non troncati.
• Desktop 1440px: layout si espande correttamente, max-width container coerente.
• Palette + tipografia coerenti con brand.* (spot check visivo vs PDP di riferimento).
• Tutte le CTA cliccate → portano a <funnel.cta_url> (PDP prodotto).
• Tutti gli image_picker delle sezioni hanno un'immagine assegnata dal theme editor (no fallback placeholder SVG visibili).
• DevTools console: no errori Liquid, no 404 su immagini.
• Header/footer come da scelta (chromeless = assenti, theme = presenti).

Chiedi conferma su ciascun check. Se qualcosa fallisce: torna alla fase corrispondente, fix, re-push.

Quando tutto ✓: dichiara il funnel pronto. Suggerisci:

• Impostare UTM tracking sugli URL degli ads che porteranno qui.
• Configurare Meta Pixel / Google Analytics sulla pagina (via theme settings o code injection).
• Testare un click CTA end-to-end (dalla page al PDP al checkout).

Se ws.sandbox_mode == true: prima di chiudere, esegui la Fase 10 sotto.

---

Fase 10 — Notifica Working Suite (solo sandbox mode)

Salta interamente se ws.sandbox_mode == false.

Quando il funnel è live + tutti i check di "Verifica finale" sono passati, Working Suite si aspetta una notifica HTTP (Bridge 1) per registrare la pagina nel proprio audit + onboarding pipeline. Senza questa chiamata, il workspace WS vede la sessione come "in progress" all'infinito.

10.1 Costruisci l'URL pubblico del funnel

funnel_public_url = "https://" + store.shopify_domain + "/pages/" + funnel.page_slug

(es. https://nimea.myshopify.com/pages/crema-borse-occhiaie-advertorial)

10.2 Esegui la POST

curl -sS -X POST "$WSA_DAEMON_URL/internal/link-shopify" \
  -H "Content-Type: application/json" \
  -H "X-WSA-Key: $WSA_INTERNAL_KEY" \
  -d "{\"url\":\"<funnel_public_url>\"}" \
  --max-time 15 \
  -w "\nHTTP:%{http_code}\n"

Body: solo { "url": "<funnel_public_url>" }. Nessun altro campo. Il daemon risolve workspace + session dal X-WSA-Key.

10.3 Comportamento sulla risposta

HTTP status	Azione
2xx	Stampa bridge1 ok funnel=<funnel_public_url> e chiudi.
4xx	Bug del caller. Stampa bridge1 FAIL status=<code> body=<response_body_without_key> e chiudi (NON retry).
5xx o errore di rete	Retry con backoff esponenziale: 1s, 3s, 9s (massimo 3 tentativi, budget totale ~15s). Dopo l'ultimo retry fallito → stampa bridge1 GIVE UP after 3 attempts status=<code> error=<msg> e chiudi.

10.4 Regole di logging (CRITICHE)

• MAI loggare $WSA_INTERNAL_KEY in chiaro. Né nei log di chat, né negli echo bash, né nei dump di curl. Se devi mostrare la chiamata per debug, redact la chiave: X-WSA-Key: ****REDACTED****.
• MAI silent-swallow. Ogni esito (success, 4xx, 5xx, give-up) deve produrre una riga bridge1 * visibile. Working Suite si affida a questa visibilità per il proprio Process Gate (vedi .claude/ralplan/plans/builder-redesign-final.md Pre-mortem #1 + Step 13a alert canary).
• MAI scrivere $WSA_INTERNAL_KEY dentro file .liquid, .json, o qualsiasi artefatto generato. Verifica con un grep finale prima di chiudere.

10.5 Idempotenza

Se l'utente ri-lancia la skill sulla stessa pagina (es. dopo un fix), la POST verrà rifatta — il daemon WS gestisce idempotenza lato suo (la riga builder_sessions.completed_at viene semplicemente aggiornata). Non è un problema.

---

Troubleshooting rapido

Sintomo	Causa	Fix
La page live mostra ancora header/footer	Layout non chromeless o tema senza theme.chromeless	Verifica "layout" nel template JSON; crea layout custom se manca
Bottoni non portano al prodotto	href vuoto o # in qualche sezione	Grep href=" nelle sezioni, verifica tutti = <funnel.cta_url>
Font non coerente col resto del sito	brand.* non applicato a tutte le sezioni	Ri-scansiona i .liquid e inserisci font-family: <brand.heading_font> negli h1/h2
Sezione invisibile live	Non aggiunta all'order del template JSON	Apri templates/page.<nome>.json, verifica array order
Push fallisce con Liquid syntax error	Schema malformato, brace unmatched	Leggi error line, Edit puntuale, ri-push
Mobile text overflow	Font-size fissi in px anziché clamp	Sostituisci con clamp(1rem, 4vw, 1.5rem) o media query

File correlati (references)

• references/auth-pattern.md — .env, Theme Access token, verifica connessione.
• references/selective-push.md — comando push + flag.
• references/section-naming.md — convenzioni prefissi (con sezione funnel).
• references/funnel-types.md — struttura advertorial / listicle / quiz / other.
• references/brand-identity-discovery.md — come leggere colori/font da una PDP.
• references/page-template-layout.md — schema page template, chromeless vs theme.
• references/funnel-image-specs.md — dimensioni/ratio per ruolo sezione.
• references/section-schema-patterns.md — pattern schema editabile: tipi di setting, blocks, richtext, image_picker, default sensati.