📝 Sync v3 docs and content across all nine languages

New shortcode sections, landing layout docs, agent skill sections,
v2→v3 upgrade instructions, translated homepages, and sample
article feature images.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

exampleSite/content/docs/installation/index.de.md

@@ -13,6 +13,21 @@ Folgen Sie einfach dem standardmäßigen Hugo [Schnellstart](https://gohugo.io/g
 
 Detaillierte Installationsanweisungen finden Sie unten. Anweisungen zum [Aktualisieren des Themes](#updates-installieren) sind ebenfalls verfügbar.
 
+## Agent-Skill
+
+Blowfish enthält einen [Agent-Skill](https://github.com/nunocoracao/blowfish/tree/main/.claude/skills/blowfish), der KI-Coding-Agents — wie Claude Code — beibringt, wie man das Theme installiert, konfiguriert und damit Websites erstellt. Wenn du mit einem Agent an deiner Website arbeitest, installiere den Skill, damit er sich mit den Konfigurationsdateien, Layouts, Front Matter und Shortcodes von Blowfish auskennt.
+
+Installation über den Blowfish-Plugin-Marketplace in Claude Code:
+
+```shell
+/plugin marketplace add nunocoracao/blowfish
+/plugin install blowfish@blowfish
+```
+
+Alternativ kannst du den Skill-Ordner unter `.claude/skills/blowfish/` in dein Website-Repository kopieren — Agents laden Skills aus dem `.claude/skills/`-Verzeichnis eines Projekts automatisch.
+
+---
+
 ## Installation
 
 Diese Anweisungen bringen Sie von einem komplett leeren Zustand mit Hugo und Blowfish zum Laufen. Die meisten der in diesem Leitfaden erwähnten Abhängigkeiten können mit dem Paketmanager Ihrer Wahl für Ihre Plattform installiert werden.
@@ -27,7 +42,7 @@ Stellen Sie sicher, dass Sie **Hugo Version 0.158.0** oder höher verwenden, da
 
 Sie finden detaillierte Installationsanweisungen für Ihre Plattform in der [Hugo-Dokumentation](https://gohugo.io/getting-started/installing).
 
-### Blowfish Tools (empfohlen)
+### Blowfish Tools
 
 Wir haben gerade ein neues CLI-Tool veröffentlicht, das Ihnen beim Einstieg mit Blowfish hilft. Es erstellt ein neues Hugo-Projekt, installiert das Theme und richtet die Theme-Konfigurationsdateien für Sie ein. Es befindet sich noch in der Beta-Phase, also [melden Sie bitte alle Probleme, die Sie finden](https://github.com/nunocoracao/blowfish-tools).
 
@@ -112,7 +127,7 @@ Für diese Methode verwenden Sie Hugo zur Verwaltung Ihrer Themes. Hugo verwende
    ```toml
    [[imports]]
    disable = false
-   path = "github.com/nunocoracao/blowfish/v2"
+   path = "github.com/nunocoracao/blowfish/v3"
    ```
 
 4. Starten Sie Ihren Server mit `hugo server` und das Theme wird automatisch heruntergeladen.
@@ -209,3 +224,14 @@ Beachten Sie, dass alle lokalen Anpassungen, die Sie an den Theme-Dateien vorgen
 2. Entpacken Sie das Archiv, benennen Sie den Ordner in `blowfish` um und verschieben Sie ihn in das Verzeichnis `themes/` im Stammordner Ihres Hugo-Projekts. Sie müssen das vorhandene Verzeichnis überschreiben, um alle Theme-Dateien zu ersetzen.
 
 3. Erstellen Sie Ihre Website neu und überprüfen Sie, ob alles wie erwartet funktioniert.
+---
+
+## Upgrade von v2 auf v3
+
+Blowfish v3 ist vollständig abwärtskompatibel zu v2-Websites: Alle neuen Features sind opt-in, es wurden keine Konfigurationsoptionen entfernt und keine Templates oder Partials umbenannt. Deine Website sieht nach dem Upgrade genauso aus und verhält sich gleich, bis du die neuen Features aktivierst.
+
+- **Git-Submodul:** Wie üblich aktualisieren — `git submodule update --remote --merge`. Mehr ist nicht nötig.
+- **Hugo-Modul:** Bearbeite `config/_default/module.toml` und ändere den Importpfad von `github.com/nunocoracao/blowfish/v2` zu `github.com/nunocoracao/blowfish/v3`, dann führe `hugo mod get -u` aus.
+- **Manuelle Installation:** Lade das neueste Release herunter und ersetze den Theme-Ordner wie oben beschrieben.
+
+Nach dem Upgrade findest du in der [Konfigurationsdokumentation]({{< ref "configuration" >}}) die neuen Opt-in-Optionen — den Floating-Header, das Landing-Homepage-Layout, den Hintergrund-Canvas, den Lesefortschrittsbalken und mehr.

exampleSite/content/docs/installation/index.es.md

@@ -13,6 +13,21 @@ Simplemente sigue el procedimiento estándar de Hugo [Inicio Rápido](https://go
 
 Las instrucciones de instalación detalladas se encuentran a continuación. También están disponibles instrucciones para [actualizar el tema](#instalación-de-actualizaciones).
 
+## Skill para agentes
+
+Blowfish incluye un [skill para agentes](https://github.com/nunocoracao/blowfish/tree/main/.claude/skills/blowfish) que enseña a los agentes de programación con IA — como Claude Code — a instalar, configurar y crear sitios con el tema. Si usas un agente para trabajar en tu sitio, instala el skill para que conozca los archivos de configuración, los layouts, el front matter y los shortcodes de Blowfish.
+
+Instálalo desde el marketplace de plugins de Blowfish en Claude Code:
+
+```shell
+/plugin marketplace add nunocoracao/blowfish
+/plugin install blowfish@blowfish
+```
+
+Como alternativa, copia la carpeta del skill en el repositorio de tu sitio, en `.claude/skills/blowfish/` — los agentes cargan automáticamente los skills almacenados en el directorio `.claude/skills/` de un proyecto.
+
+---
+
 ## Instalación
 
 Estas instrucciones te ayudarán a empezar con Hugo y Blowfish desde un estado completamente vacío. La mayoría de las dependencias mencionadas en esta guía se pueden instalar utilizando el gestor de paquetes de tu elección para tu plataforma.
@@ -27,7 +42,7 @@ Asegúrate de estar usando **Hugo versión 0.158.0** o posterior, ya que el tema
 
 Puedes encontrar instrucciones de instalación detalladas para tu plataforma en la [documentación de Hugo](https://gohugo.io/getting-started/installing).
 
-### Blowfish Tools (recomendado)
+### Blowfish Tools
 
 Acabamos de lanzar una nueva herramienta CLI para ayudarte a empezar con Blowfish. Creará un nuevo proyecto Hugo, instalará el tema y configurará los archivos de configuración del tema por ti. Todavía está en beta, así que por favor [reporta cualquier problema que encuentres](https://github.com/nunocoracao/blowfish-tools).
 
@@ -112,7 +127,7 @@ Para este método usarás Hugo para gestionar tus temas. Hugo usa **Go** para in
    ```toml
    [[imports]]
    disable = false
-   path = "github.com/nunocoracao/blowfish/v2"
+   path = "github.com/nunocoracao/blowfish/v3"
    ```
 
 4. Inicia tu servidor usando `hugo server` y el tema se descargará automáticamente.
@@ -209,3 +224,14 @@ Ten en cuenta que cualquier personalización local que hayas hecho a los archivo
 2. Extrae el archivo, renombra la carpeta a `blowfish` y muévela al directorio `themes/` dentro de la carpeta raíz de tu proyecto Hugo. Necesitarás sobrescribir el directorio existente para reemplazar todos los archivos del tema.
 
 3. Reconstruye tu sitio y verifica que todo funcione como se esperaba.
+---
+
+## Actualizar de v2 a v3
+
+Blowfish v3 es totalmente compatible con los sitios de v2: todas las novedades son opcionales, no se ha eliminado ninguna opción de configuración y no se ha renombrado ningún template ni partial. Tu sitio se verá y funcionará igual tras actualizar, hasta que actives las nuevas funciones.
+
+- **Submódulo Git:** actualiza como siempre — `git submodule update --remote --merge`. No hace falta nada más.
+- **Módulo de Hugo:** edita `config/_default/module.toml` y cambia la ruta de importación de `github.com/nunocoracao/blowfish/v2` a `github.com/nunocoracao/blowfish/v3`; después ejecuta `hugo mod get -u`.
+- **Instalación manual:** descarga la última versión y sustituye la carpeta del tema, como se describe arriba.
+
+Tras actualizar, consulta la [documentación de configuración]({{< ref "configuration" >}}) para conocer las nuevas opciones — el header flotante, el layout de portada landing, el fondo global, la barra de progreso de lectura y más.

exampleSite/content/docs/installation/index.fr.md

@@ -13,6 +13,21 @@ Suivez simplement la procédure standard Hugo [Démarrage Rapide](https://gohugo
 
 Des instructions d'installation détaillées sont disponibles ci-dessous. Des instructions pour [mettre à jour le thème](#installation-des-mises-à-jour) sont également disponibles.
 
+## Skill pour agents
+
+Blowfish inclut un [skill pour agents](https://github.com/nunocoracao/blowfish/tree/main/.claude/skills/blowfish) qui apprend aux agents de codage IA — comme Claude Code — à installer, configurer et créer des sites avec le thème. Si vous utilisez un agent pour travailler sur votre site, installez le skill afin qu'il connaisse les fichiers de configuration, les layouts, le front matter et les shortcodes de Blowfish.
+
+Installez-le depuis la marketplace de plugins de Blowfish dans Claude Code :
+
+```shell
+/plugin marketplace add nunocoracao/blowfish
+/plugin install blowfish@blowfish
+```
+
+Vous pouvez aussi copier le dossier du skill dans le dépôt de votre site, sous `.claude/skills/blowfish/` — les agents chargent automatiquement les skills présents dans le répertoire `.claude/skills/` d'un projet.
+
+---
+
 ## Installation
 
 Ces instructions vous permettront de démarrer avec Hugo et Blowfish à partir d'un état complètement vierge. La plupart des dépendances mentionnées dans ce guide peuvent être installées à l'aide du gestionnaire de paquets de votre choix pour votre plateforme.
@@ -27,7 +42,7 @@ Assurez-vous d'utiliser **Hugo version 0.158.0** ou ultérieure car le thème ti
 
 Vous pouvez trouver des instructions d'installation détaillées pour votre plateforme dans la [documentation Hugo](https://gohugo.io/getting-started/installing).
 
-### Blowfish Tools (recommandé)
+### Blowfish Tools
 
 Nous venons de lancer un nouvel outil CLI pour vous aider à démarrer avec Blowfish. Il créera un nouveau projet Hugo, installera le thème et configurera les fichiers de configuration du thème pour vous. Il est encore en bêta, veuillez donc [signaler tout problème que vous rencontrez](https://github.com/nunocoracao/blowfish-tools).
 
@@ -112,7 +127,7 @@ Pour cette méthode, vous utiliserez Hugo pour gérer vos thèmes. Hugo utilise
    ```toml
    [[imports]]
    disable = false
-   path = "github.com/nunocoracao/blowfish/v2"
+   path = "github.com/nunocoracao/blowfish/v3"
    ```
 
 4. Démarrez votre serveur en utilisant `hugo server` et le thème sera téléchargé automatiquement.
@@ -209,3 +224,14 @@ Notez que toutes les personnalisations locales que vous avez apportées aux fich
 2. Extrayez l'archive, renommez le dossier en `blowfish` et déplacez-le dans le répertoire `themes/` à l'intérieur du dossier racine de votre projet Hugo. Vous devrez écraser le répertoire existant pour remplacer tous les fichiers du thème.
 
 3. Reconstruisez votre site et vérifiez que tout fonctionne comme prévu.
+---
+
+## Mettre à niveau de v2 vers v3
+
+Blowfish v3 est entièrement rétrocompatible avec les sites v2 : toutes les nouveautés sont optionnelles, aucune option de configuration n'a été supprimée et aucun template ni partial n'a été renommé. Votre site aura le même aspect et le même comportement après la mise à niveau, jusqu'à ce que vous activiez les nouvelles fonctionnalités.
+
+- **Sous-module Git :** mettez à jour comme d'habitude — `git submodule update --remote --merge`. Rien d'autre n'est nécessaire.
+- **Module Hugo :** modifiez `config/_default/module.toml` en remplaçant le chemin d'import `github.com/nunocoracao/blowfish/v2` par `github.com/nunocoracao/blowfish/v3`, puis exécutez `hugo mod get -u`.
+- **Installation manuelle :** téléchargez la dernière version et remplacez le dossier du thème, comme décrit ci-dessus.
+
+Après la mise à niveau, parcourez la [documentation de configuration]({{< ref "configuration" >}}) pour découvrir les nouvelles options — le header flottant, la mise en page landing, le fond global, la barre de progression de lecture et plus encore.

exampleSite/content/docs/installation/index.it.md

@@ -13,6 +13,21 @@ Segui semplicemente la procedura standard [Avvio Rapido](https://gohugo.io/getti
 
 Sono riportate le istruzioni dettagliate per l'installazione. Sono disponibili anche le istruzioni per [aggiornare il tema](#installazione-degli-aggiornamenti).
 
+## Skill per agenti
+
+Blowfish include una [skill per agenti](https://github.com/nunocoracao/blowfish/tree/main/.claude/skills/blowfish) che insegna agli agenti di programmazione IA — come Claude Code — come installare, configurare e creare siti con il tema. Se usi un agente per lavorare sul tuo sito, installa la skill così conoscerà i file di configurazione, i layout, il front matter e gli shortcode di Blowfish.
+
+Installala dal marketplace dei plugin di Blowfish in Claude Code:
+
+```shell
+/plugin marketplace add nunocoracao/blowfish
+/plugin install blowfish@blowfish
+```
+
+In alternativa, copia la cartella della skill nel repository del tuo sito in `.claude/skills/blowfish/` — gli agenti caricano automaticamente le skill presenti nella directory `.claude/skills/` di un progetto.
+
+---
+
 ## Installazione
 
 Queste istruzioni ti consentiranno di iniziare a utilizzare Hugo e Blowfish partendo da uno stato completamente vuoto. La maggior parte delle dipendenze menzionate in questa guida possono essere installate utilizzando il gestore pacchetti corretti per la tua piattaforma.
@@ -28,7 +43,7 @@ Assicurati di usare la **versione 0.158.0 di Hugo** o successiva, poiché il tem
 
 Puoi trovare le istruzioni dettagliate sull'installazione per la propria piattaforma in [Documenti Hugo](https://gohugo.io/getting-started/installing).
 
-### Strumenti Blowfish (raccomandato)
+### Strumenti Blowfish
 
 Abbiamo appena lanciato un nuovo strumento CLI per aiutarti a iniziare con Blowfish. Questo ti permette di creare un nuovo progetto Hugo, di installare il tema e di impostare i file di configurazione del tema per te. È ancora in fase beta, quindi per favore [segnala qualsiasi problema che riscontri] (https://github.com/nunocoracao/blowfish-tools).
 
@@ -111,7 +126,7 @@ Per questo metodo utilizzerai Hugo per gestire i tuoi temi. Hugo utilizza **Go**
    ```toml
    [[imports]]
    disable = false
-   path = "github.com/nunocoracao/blowfish/v2"
+   path = "github.com/nunocoracao/blowfish/v3"
    ```
 
 4. Avvia il tuo server utilizzando `hugo server` e il tema verrà scaricato automaticamente.
@@ -208,3 +223,14 @@ Tieni presente che ogni personalizzazione locale apportata ai file del tema andr
 2. Estrai l'archivio, rinomina la cartella in "blowfish" e spostala nella directory "themes/" all'interno della cartella principale del tuo progetto Hugo. Dovrai sovrascrivere la directory esistente per sostituire tutti i file del tema.
 
 3. Riavvia il tuo sito e verifica che tutto funzioni come previsto.
+---
+
+## Aggiornare da v2 a v3
+
+Blowfish v3 è completamente retrocompatibile con i siti v2: tutte le novità sono opt-in, nessuna opzione di configurazione è stata rimossa e nessun template o partial è stato rinominato. Il tuo sito avrà lo stesso aspetto e comportamento dopo l'aggiornamento, finché non attivi le nuove funzionalità.
+
+- **Submodule Git:** aggiorna come al solito — `git submodule update --remote --merge`. Non serve altro.
+- **Modulo Hugo:** modifica `config/_default/module.toml` cambiando il percorso di import da `github.com/nunocoracao/blowfish/v2` a `github.com/nunocoracao/blowfish/v3`, poi esegui `hugo mod get -u`.
+- **Installazione manuale:** scarica l'ultima release e sostituisci la cartella del tema, come descritto sopra.
+
+Dopo l'aggiornamento, consulta la [documentazione di configurazione]({{< ref "configuration" >}}) per le nuove opzioni — l'header flottante, il layout landing, lo sfondo globale, la barra di avanzamento della lettura e altro.

exampleSite/content/docs/installation/index.ja.md

@@ -13,6 +13,21 @@ Hugo の[クイックスタートガイド](https://gohugo.io/getting-started/qu
 
 詳細なインストール手順は以下に記載されています。[テーマのアップデート方法](#テーマのアップデート方法)についても説明しています。
 
+## エージェントスキル
+
+Blowfish には、Claude Code などの AI コーディングエージェントにテーマのインストール・設定・サイト構築の方法を教える[エージェントスキル](https://github.com/nunocoracao/blowfish/tree/main/.claude/skills/blowfish)が付属しています。エージェントを使ってサイトを開発する場合は、このスキルをインストールすると、Blowfish の設定ファイル、レイアウト、フロントマター、ショートコードをエージェントが理解できるようになります。
+
+Claude Code で Blowfish のプラグインマーケットプレイスからインストールできます:
+
+```shell
+/plugin marketplace add nunocoracao/blowfish
+/plugin install blowfish@blowfish
+```
+
+または、スキルのフォルダをサイトのリポジトリの `.claude/skills/blowfish/` にコピーしてください。エージェントはプロジェクトの `.claude/skills/` ディレクトリにあるスキルを自動的に読み込みます。
+
+---
+
 ## インストール
 
 以下の手順では、全くの新規状態から Hugo と Blowfish を使用してウェブサイトを立ち上げる方法を説明します。このガイドで紹介するツールのほとんどは、お使いのプラットフォームに対応したパッケージマネージャーからインストール可能です。
@@ -27,7 +42,7 @@ Hugo を初めて使用する場合は、[公式サイトの手順](https://gohu
 
 お使いのプラットフォームに合わせた詳細なインストール手順は、[Hugo の公式ドキュメント](https://gohugo.io/getting-started/installing)に記載されています。
 
-### Blowfish Tools (推奨)
+### Blowfish Tools
 
 Blowfish を簡単に使い始められるよう、新しく CLI ツールをリリースしました。このツールは、新しい Hugo プロジェクトの作成、テーマのインストール、そしてテーマ設定ファイルのセットアップを自動的に行います。まだベータ版ですので、[問題を発見した場合は報告にご協力ください](https://github.com/nunocoracao/blowfish-tools)。
 
@@ -112,7 +127,7 @@ git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blo
    ```toml
    [[imports]]
    disable = false
-   path = "github.com/nunocoracao/blowfish/v2"
+   path = "github.com/nunocoracao/blowfish/v3"
    ```
 
 4. `hugo server` を実行してサーバーを起動すると、テーマが自動的にダウンロードされます。
@@ -209,3 +224,14 @@ Blowfish を手動でアップデートするには、テーマの最新コピ
 2. アーカイブを解凍し、フォルダ名を `blowfish` に変更して、Hugo プロジェクトのルートフォルダ内の `themes/` ディレクトリに移動します。すべてのテーマファイルを置き換えるには、既存のディレクトリを上書きする必要があります。
 
 3. サイトを再びビルドし、すべてが期待通りに動作することを確認してください。
+---
+
+## v2 から v3 へのアップグレード
+
+Blowfish v3 は v2 のサイトと完全な後方互換性があります。新機能はすべてオプトインで、設定オプションの削除やテンプレート・パーシャルの名称変更はありません。アップグレード後も、新機能を有効にするまでサイトの見た目や動作は変わりません。
+
+- **Git サブモジュール:** いつも通り更新してください — `git submodule update --remote --merge`。それ以外の作業は不要です。
+- **Hugo モジュール:** `config/_default/module.toml` のインポートパスを `github.com/nunocoracao/blowfish/v2` から `github.com/nunocoracao/blowfish/v3` に変更し、`hugo mod get -u` を実行してください。
+- **手動インストール:** 上記の手順の通り、最新リリースをダウンロードしてテーマフォルダを置き換えてください。
+
+アップグレード後は、[設定ドキュメント]({{< ref "configuration" >}})で新しいオプトイン機能（フローティングヘッダー、ランディングレイアウト、背景キャンバス、読書プログレスバーなど）を確認してください。

exampleSite/content/docs/installation/index.md

@@ -14,6 +14,21 @@ Simply follow the standard Hugo [Quick Start](https://gohugo.io/getting-started/
 
 Detailed installation instructions can be found below. Instructions for [updating the theme](#installing-updates) are also available.
 
+## Agent skill
+
+Blowfish ships an [agent skill](https://github.com/nunocoracao/blowfish/tree/main/.claude/skills/blowfish) that teaches AI coding agents — like Claude Code — how to install, configure, and build sites with the theme. If you use an agent to work on your site, install the skill so it knows its way around Blowfish's configuration files, layouts, front matter, and shortcodes.
+
+Install it from the Blowfish plugin marketplace in Claude Code:
+
+```shell
+/plugin marketplace add nunocoracao/blowfish
+/plugin install blowfish@blowfish
+```
+
+Alternatively, copy the skill folder into your site repository at `.claude/skills/blowfish/` — agents automatically pick up skills stored in a project's `.claude/skills/` directory.
+
+---
+
 ## Installation
 
 These instructions will get you up and running using Hugo and Blowfish from a completely blank state. Most of the dependencies mentioned in this guide can be installed using the package manager of choice for your platform.
@@ -28,7 +43,7 @@ Make sure you are using **Hugo version 0.158.0** or later as the theme takes adv
 
 You can find detailed installation instructions for your platform in the [Hugo docs](https://gohugo.io/getting-started/installing).
 
-### Blowfish Tools (recommended)
+### Blowfish Tools
 
 We just launched a new CLI tool to help you get started with Blowfish. It will create a new Hugo project, install the theme and set up the theme configuration files for you. It's still in beta so please [report any issues you find](https://github.com/nunocoracao/blowfish-tools).
 
@@ -113,7 +128,7 @@ For this method you'll use Hugo to manage your themes. Hugo uses **Go** to initi
    ```toml
    [[imports]]
    disable = false
-   path = "github.com/nunocoracao/blowfish/v2"
+   path = "github.com/nunocoracao/blowfish/v3"
    ```
 
 4. Start your server using `hugo server` and the theme will be downloaded automatically.
@@ -210,3 +225,14 @@ Note that any local customisations you have made to the theme files will be lost
 2. Extract the archive, rename the folder to `blowfish` and move it to the `themes/` directory inside your Hugo project's root folder. You will need to overwrite the existing directory to replace all the theme files.
 
 3. Rebuild your site and check everything works as expected.
+---
+
+## Upgrading from v2 to v3
+
+Blowfish v3 is fully backwards compatible with v2 sites: all new features are opt-in, no configuration options were removed, and no templates or partials were renamed. Your site will look and behave the same after upgrading, until you enable the new features.
+
+- **Git submodule:** update as usual — `git submodule update --remote --merge`. Nothing else is required.
+- **Hugo module:** edit `config/_default/module.toml` and change the import path from `github.com/nunocoracao/blowfish/v2` to `github.com/nunocoracao/blowfish/v3`, then run `hugo mod get -u`.
+- **Manual install:** download the latest release and replace the theme folder, as described above.
+
+After upgrading, browse the [configuration docs]({{< ref "configuration" >}}) for the new opt-in options — the floating header, the landing homepage layout, the background canvas, the reading progress bar, and more.

exampleSite/content/docs/installation/index.pt-br.md

@@ -13,6 +13,21 @@ Simplesmente siga o procedimento padrão do Hugo [Início Rápido](https://gohug
 
 Instruções detalhadas de instalação podem ser encontradas abaixo. Instruções para [atualizar o tema](#instalando-atualizações) também estão disponíveis.
 
+## Skill para agentes
+
+O Blowfish inclui uma [skill para agentes](https://github.com/nunocoracao/blowfish/tree/main/.claude/skills/blowfish) que ensina agentes de programação com IA — como o Claude Code — a instalar, configurar e criar sites com o tema. Se você usa um agente para trabalhar no seu site, instale a skill para que ele conheça os arquivos de configuração, os layouts, o front matter e os shortcodes do Blowfish.
+
+Instale-a a partir do marketplace de plugins do Blowfish no Claude Code:
+
+```shell
+/plugin marketplace add nunocoracao/blowfish
+/plugin install blowfish@blowfish
+```
+
+Como alternativa, copie a pasta da skill para o repositório do seu site em `.claude/skills/blowfish/` — os agentes carregam automaticamente as skills armazenadas no diretório `.claude/skills/` de um projeto.
+
+---
+
 ## Instalação
 
 Estas instruções vão te ajudar a começar com Hugo e Blowfish a partir de um estado completamente vazio. A maioria das dependências mencionadas neste guia pode ser instalada usando o gerenciador de pacotes de sua escolha para sua plataforma.
@@ -27,7 +42,7 @@ Certifique-se de estar usando **Hugo versão 0.158.0** ou posterior, pois o tema
 
 Você pode encontrar instruções de instalação detalhadas para sua plataforma na [documentação do Hugo](https://gohugo.io/getting-started/installing).
 
-### Blowfish Tools (recomendado)
+### Blowfish Tools
 
 Acabamos de lançar uma nova ferramenta CLI para ajudá-lo a começar com o Blowfish. Ela criará um novo projeto Hugo, instalará o tema e configurará os arquivos de configuração do tema para você. Ainda está em beta, então por favor [reporte quaisquer problemas que encontrar](https://github.com/nunocoracao/blowfish-tools).
 
@@ -112,7 +127,7 @@ Para este método, você usará o Hugo para gerenciar seus temas. O Hugo usa **G
    ```toml
    [[imports]]
    disable = false
-   path = "github.com/nunocoracao/blowfish/v2"
+   path = "github.com/nunocoracao/blowfish/v3"
    ```
 
 4. Inicie seu servidor usando `hugo server` e o tema será baixado automaticamente.
@@ -209,3 +224,14 @@ Note que quaisquer personalizações locais que você tenha feito nos arquivos d
 2. Extraia o arquivo, renomeie a pasta para `blowfish` e mova-a para o diretório `themes/` dentro da pasta raiz do seu projeto Hugo. Você precisará sobrescrever o diretório existente para substituir todos os arquivos do tema.
 
 3. Reconstrua seu site e verifique se tudo funciona como esperado.
+---
+
+## Atualizando da v2 para a v3
+
+O Blowfish v3 é totalmente retrocompatível com sites v2: todas as novidades são opcionais, nenhuma opção de configuração foi removida e nenhum template ou partial foi renomeado. Seu site terá a mesma aparência e comportamento após a atualização, até que você ative os novos recursos.
+
+- **Submódulo Git:** atualize como de costume — `git submodule update --remote --merge`. Nada mais é necessário.
+- **Módulo Hugo:** edite `config/_default/module.toml` e altere o caminho de importação de `github.com/nunocoracao/blowfish/v2` para `github.com/nunocoracao/blowfish/v3`; depois execute `hugo mod get -u`.
+- **Instalação manual:** baixe a última versão e substitua a pasta do tema, como descrito acima.
+
+Após atualizar, consulte a [documentação de configuração]({{< ref "configuration" >}}) para conhecer as novas opções — o header flutuante, o layout landing, o fundo global, a barra de progresso de leitura e mais.

exampleSite/content/docs/installation/index.pt-pt.md

@@ -13,6 +13,21 @@ Simplesmente siga o procedimento padrão do Hugo [Início Rápido](https://gohug
 
 Instruções detalhadas de instalação podem ser encontradas abaixo. Instruções para [atualizar o tema](#instalar-atualizações) também estão disponíveis.
 
+## Skill para agentes
+
+O Blowfish inclui uma [skill para agentes](https://github.com/nunocoracao/blowfish/tree/main/.claude/skills/blowfish) que ensina agentes de programação com IA — como o Claude Code — a instalar, configurar e criar sites com o tema. Se utilizar um agente para trabalhar no seu site, instale a skill para que este conheça os ficheiros de configuração, os layouts, o front matter e os shortcodes do Blowfish.
+
+Instale-a a partir do marketplace de plugins do Blowfish no Claude Code:
+
+```shell
+/plugin marketplace add nunocoracao/blowfish
+/plugin install blowfish@blowfish
+```
+
+Em alternativa, copie a pasta da skill para o repositório do seu site em `.claude/skills/blowfish/` — os agentes carregam automaticamente as skills guardadas no diretório `.claude/skills/` de um projeto.
+
+---
+
 ## Instalação
 
 Estas instruções irão ajudá-lo a começar com Hugo e Blowfish a partir de um estado completamente vazio. A maioria das dependências mencionadas neste guia pode ser instalada utilizando o gestor de pacotes da sua escolha para a sua plataforma.
@@ -27,7 +42,7 @@ Certifique-se de que está a utilizar **Hugo versão 0.158.0** ou posterior, poi
 
 Pode encontrar instruções de instalação detalhadas para a sua plataforma na [documentação do Hugo](https://gohugo.io/getting-started/installing).
 
-### Blowfish Tools (recomendado)
+### Blowfish Tools
 
 Acabámos de lançar uma nova ferramenta CLI para o ajudar a começar com o Blowfish. Irá criar um novo projeto Hugo, instalar o tema e configurar os ficheiros de configuração do tema por si. Ainda está em beta, por isso [reporte quaisquer problemas que encontrar](https://github.com/nunocoracao/blowfish-tools).
 
@@ -112,7 +127,7 @@ Para este método, utilizará o Hugo para gerir os seus temas. O Hugo utiliza **
    ```toml
    [[imports]]
    disable = false
-   path = "github.com/nunocoracao/blowfish/v2"
+   path = "github.com/nunocoracao/blowfish/v3"
    ```
 
 4. Inicie o seu servidor utilizando `hugo server` e o tema será transferido automaticamente.
@@ -209,3 +224,14 @@ Note que quaisquer personalizações locais que tenha feito aos ficheiros do tem
 2. Extraia o arquivo, renomeie a pasta para `blowfish` e mova-a para o diretório `themes/` dentro da pasta raiz do seu projeto Hugo. Precisará de sobrescrever o diretório existente para substituir todos os ficheiros do tema.
 
 3. Reconstrua o seu site e verifique se tudo funciona como esperado.
+---
+
+## Atualizar da v2 para a v3
+
+O Blowfish v3 é totalmente retrocompatível com sites v2: todas as novidades são opcionais, nenhuma opção de configuração foi removida e nenhum template ou partial foi renomeado. O seu site terá o mesmo aspeto e comportamento após a atualização, até ativar as novas funcionalidades.
+
+- **Submódulo Git:** atualize como habitualmente — `git submodule update --remote --merge`. Não é necessário mais nada.
+- **Módulo Hugo:** edite `config/_default/module.toml` e altere o caminho de importação de `github.com/nunocoracao/blowfish/v2` para `github.com/nunocoracao/blowfish/v3`; depois execute `hugo mod get -u`.
+- **Instalação manual:** transfira a última versão e substitua a pasta do tema, como descrito acima.
+
+Após atualizar, consulte a [documentação de configuração]({{< ref "configuration" >}}) para conhecer as novas opções — o header flutuante, o layout landing, o fundo global, a barra de progresso de leitura e mais.

exampleSite/content/docs/installation/index.zh-cn.md

@@ -13,6 +13,21 @@ series_order: 2
 
 更详细的安装如下，[更新主题](#更新主题)的教程也可以看此文档。
 
+## 智能体技能
+
+Blowfish 附带一个[智能体技能](https://github.com/nunocoracao/blowfish/tree/main/.claude/skills/blowfish)，用于教 AI 编程智能体（如 Claude Code）如何安装、配置该主题并用它构建网站。如果你使用智能体来开发你的网站，安装此技能后，智能体就能熟悉 Blowfish 的配置文件、布局、front matter 和短代码。
+
+在 Claude Code 中通过 Blowfish 插件市场安装：
+
+```shell
+/plugin marketplace add nunocoracao/blowfish
+/plugin install blowfish@blowfish
+```
+
+或者，将技能文件夹复制到你网站仓库的 `.claude/skills/blowfish/` 目录 — 智能体会自动加载项目 `.claude/skills/` 目录中的技能。
+
+---
+
 ## 前言
 
 本文将一步一步指导你学会使用 Hugo 和 Blowfish。本文中提到的大多数依赖项都可以在任意你想使用的平台中使用和安装。
@@ -27,7 +42,7 @@ series_order: 2
 
 你可以在 [Hugo 文档](https://gohugo.io/getting-started/installing) 中找到不同平台更加详细的安装指南。
 
-### 使用 Blowfish-Tools 工具安装 (推荐)
+### 使用 Blowfish-Tools 工具安装
 
 我们刚刚推出了一个 CLI 工具，帮助你首次使用 Blowfish。该工具将会为你创建一个新的 Hugo 项目、安装 Blowfish 主题并设置配置文件。但目前该工具仍处于测试阶段，如果遇到任何问题，请随时[提交 issues](https://github.com/nunocoracao/blowfish-tools)。
 
@@ -111,7 +126,7 @@ git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blo
    ```toml
    [[imports]]
    disable = false
-   path = "github.com/nunocoracao/blowfish/v2"
+   path = "github.com/nunocoracao/blowfish/v3"
    ```
 
 4. 使用`hugo server` 命令后，主题将会自动下载。
@@ -208,3 +223,14 @@ Hugo 将自动更新项目中所需的任何模块。它通过检查 `module.tom
 2. 解压缩, 将文件夹重命名为 `blowfish`，并移动到根目录 `themes/` 目录下。你需要覆盖旧版以替换所有的主题文件。
 
 3. 重建站点，并检查网站是否一切正常。
+---
+
+## 从 v2 升级到 v3
+
+Blowfish v3 与 v2 站点完全向后兼容：所有新功能均为可选启用，没有删除任何配置选项，也没有重命名任何模板或部件。升级后，在你启用新功能之前，站点的外观和行为保持不变。
+
+- **Git 子模块：** 照常更新 — `git submodule update --remote --merge`，无需其他操作。
+- **Hugo 模块：** 编辑 `config/_default/module.toml`，将导入路径从 `github.com/nunocoracao/blowfish/v2` 改为 `github.com/nunocoracao/blowfish/v3`，然后运行 `hugo mod get -u`。
+- **手动安装：** 按上文所述，下载最新版本并替换主题文件夹。
+
+升级后，请查看[配置文档]({{< ref "configuration" >}})了解新的可选功能 — 悬浮菜单、着陆页布局、全局背景、阅读进度条等。