✨ Add Blowfish discovery and freshness path

exampleSite/content/guides/202608-upgrade-to-blowfish-v3/index.md

@@ -0,0 +1,48 @@
+---
+title: "Upgrade an existing Hugo site to Blowfish 3"
+description: "Move an existing Blowfish site to version 3 with no breaking configuration changes."
+date: 2026-08-30
+lastmod: 2026-08-30
+tags: ["blowfish", "hugo", "migration", "v3"]
+showauthor: false
+authors: ["nunocoracao"]
+---
+
+{{< lead >}}
+Blowfish 3 is backwards compatible. Existing sites can upgrade without rewriting their configuration or content.
+{{< /lead >}}
+
+## Before you upgrade
+
+Commit your current site and make sure your Hugo version is within the range declared by Blowfish. If you have custom files inside the theme directory, move them into your site's `assets/` or `layouts/` directories first so upgrades do not overwrite them.
+
+## Upgrade your installation
+
+### Hugo module
+
+Update the module path in `config/_default/module.toml` to include `/v3`, then refresh dependencies:
+
+```toml
+[[imports]]
+path = "github.com/nunocoracao/blowfish/v3"
+```
+
+```shell
+hugo mod get -u
+```
+
+### Git submodule
+
+```shell
+git submodule update --remote --merge
+```
+
+### Manual install
+
+Download the latest release, replace `themes/blowfish/`, and keep your site-level configuration in `config/_default/`.
+
+## Verify the result
+
+Run `hugo server`, check your homepage and a representative article, then deploy as usual. New Blowfish 3 features are opt-in, so your existing site should render as before.
+
+For a new site instead, use `npx blowfish-tools new <site>` and follow the [installation guide]({{< ref "docs/installation" >}}).

exampleSite/content/guides/_index.md

@@ -1,6 +1,7 @@
 ---
-title: "Recipes"
-description: "Recipes, guides, and tutorials for Blowfish"
+title: "Guides"
+description: "Practical guides for building, migrating, and publishing Hugo sites with Blowfish"
+lastmod: 2026-08-30
 
 cascade:
   showDate: false
@@ -9,11 +10,11 @@ cascade:
 ---
 
 {{< lead >}}
-Recipes, guides, and tutorials for Blowfish
+Practical guides for building, migrating, and publishing Hugo sites with Blowfish.
 {{< /lead >}}
 
 **Blowfish user?** To add your guide to this list, [check the template](/guides/template/).
 
-This section contains guides for a variety of scenarios on how to configure your theme. If you're new, check out the [Installation]({{< ref "docs/installation" >}}) guide to begin or visit the [Samples]({{< ref "samples" >}}) section to see what Blowfish can do.
+Start with [installation]({{< ref "docs/installation" >}}), upgrade an existing site to [Blowfish 3]({{< ref "guides/202608-upgrade-to-blowfish-v3" >}}), or browse the [Showcase]({{< ref "examples" >}}) for inspiration.
 
 ---