Guides section makeover phase 2-add unifying elements/related reading sections (superfly#2288)

* guides makeover phase 2

* second batch of guides updates

* guides updates batch 3

* one more

Author: kcmartin

blueprints/autoscale-machines.html.md

@@ -9,12 +9,14 @@ redirect_from: /docs/blueprints/autoscale-machines-like-a-boss/
   <img src="/static/images/autoscale-machines.png" alt="Illustration by Annie Ruygt of two machines dancing and one standing still" class="w-full max-w-lg mx-auto">
 </figure>
 
+## Overview
+
 You have an app with services that's configured to [automatically start
 and stop Machines based on traffic demand](/docs/launch/autostop-autostart/). But the traffic to your app changes
 significantly during the day and you don't want to keep a lot of stopped
 Machines during the period of low traffic.
 
-This blueprint will guide you through the process of configuring the
+This guide will take you through the process of configuring the
 [`fly-autoscaler` app](/docs/launch/autoscale-by-metric/) in conjunction with 
 [Fly Proxy autostop/autostart](/docs/launch/autostop-autostart/) to 
 always keep a fixed number of Machines ready to be quickly started 
@@ -108,10 +110,8 @@ And finally, deploy the autoscaler, using the `--ha` option to deploy only one M
 $ fly deploy --ha=false
 ```
 
-## Read more
+## Related reading
 
 - [Autoscale based on metrics](/docs/launch/autoscale-by-metric/)
-
 - [Autostop/autostart Machines](/docs/launch/autostop-autostart/)
-
 - [Autostop/autostart private apps](/docs/blueprints/autostart-internal-apps/)

blueprints/autostart-internal-apps.html.md

@@ -8,11 +8,13 @@ nav: guides
   <img src="/static/images/autostart-internal-apps.png" alt="Illustration by Annie Ruygt of Frankie the balloon having a picnic with an app and eating strawberries" class="w-full max-w-lg mx-auto">
 </figure>
 
+## Overview
+
 You have a private, or internal, app that communicates only with other apps on your [private network](/docs/networking/private-networking/). This private app might be a database, authentication server, or any other "backend" app that you don't want exposed to the public Internet. You want the app's Machines to stop when they're not serving requests from your other apps, and start again automatically when needed.
 
 To use Fly Proxy autostop/autostart you need to configure services in `fly.toml`, like you would for a public app. But instead of using a public Anycast address, you assign a Flycast address to expose those services only on your private network.
 
-This blueprint focuses on using autostop/autostart to control Machines based on incoming requests. But when you use Flycast for private apps you also get other [Fly Proxy features](/docs/reference/fly-proxy/) like geographically aware load balancing.
+This guide focuses on using autostop/autostart to control Machines based on incoming requests. But when you use Flycast for private apps you also get other [Fly Proxy features](/docs/reference/fly-proxy/) like geographically aware load balancing.
 
 Learn more about [Flycast](/docs/networking/flycast/).
 
@@ -113,10 +115,9 @@ Run `fly deploy` for the configuration changes to take effect.
 
 Other apps in your organization can now reach your private app using the [Flycast](/docs/networking/flycast/) IP address or the `<appname>.flycast` domain.
 
-## Read more
+## Related reading
 
 We've talked about Flycast in some past blog posts:
 
 - [Deploy Your Own (Not) Midjourney Bot on Fly GPUs](https://fly.io/blog/not-midjourney-bot/)
-
 - [Scaling Large Language Models to zero with Ollama](https://fly.io/blog/scaling-llm-ollama/)

blueprints/bridge-deployments-wireguard.html.md

@@ -13,6 +13,8 @@ date: 2024-05-27
   <img src="/static/images/bridge-deployment.png" alt="Illustration by Annie Ruygt of a figure with wings and a ship some balloons and planes" class="w-full max-w-lg mx-auto">
 </figure>
 
+## Overview
+
 Sometimes you can recreate production on Fly.io without any issues. Other times you need to be able to incrementally move things over. Fly.io [has private networking](/docs/networking/private-networking/) by default for apps in the same organization, but you can also easily connect your existing external servers to this private network. This lets you use your private network as a way to incrementally move services over.
 
 Say you have an existing service on AWS or a database with RDS that needs to be accessed over RDS. You can use that AWS instance to pivot traffic from your Fly Machines to those other services. You can also go the other way and access your Fly apps (such as [an instance of Ollama](https://fly.io/blog/scaling-llm-ollama/)) from AWS, your laptop, or any other self-hosted server you have in your arsenal. Or maybe you're making a tool for a support team, and it needs to hit that one database on prem.
@@ -109,3 +111,9 @@ Getting ping working should be good enough to get you started, but here's some o
 - Connect a few other computers to your private network. Install a Minecraft server on one of them and play together.
 
 Hint: you may need to allow private network addresses through your firewall. Check the documentation of your firewall tool of choice and allow traffic from `fly0` through as if it's an "internal" interface.
+
+## Related Reading
+
+- [Jack into your private network with WireGuard](https://fly.io/docs/blueprints/connect-private-network-wireguard/) A guide showing how to connect a laptop or external server to your Fly.io private network via WireGuard.  
+- [Private Networking](https://fly.io/docs/networking/private-networking/) Overview of Fly’s internal IPv6 mesh (6PN), how apps talk to each other privately, and how WireGuard‑based tunnels integrate.  
+- [Custom Private Networks](https://fly.io/docs/networking/custom-private-networks/) How to isolate tenants, apps, or services by creating separate private networks inside your organization — relevant when bridging external infrastructure.

blueprints/connecting-to-user-machines.html.md

@@ -9,9 +9,9 @@ date: 2025-04-02
   <img src="/static/images/connecting-to-users.png" alt="Illustration by Annie Ruygt of a bird holding hands with a computer" class="w-full max-w-lg mx-auto">
 </figure>
 
-# Connecting to User Machines
+## Overview
 
-When running machines for end users, a common challenge is efficiently managing and routing requests to these machines. This document outlines the recommended approach for connecting to user machines on Fly.io, focusing on the following key concepts:
+When running machines for end users, a common challenge is efficiently managing and routing requests to these machines. This guide outlines the recommended approach for connecting to user machines on Fly.io.
 
 ## Typical Stack
 
@@ -156,3 +156,9 @@ async function handleRequest(request: Request): Promise<Response> {
 ```
 
 This code checks the `fly-replay-src` header, parses out the `state` value, and compares it to the preshared key. If it matches, the request is authenticated. 
+
+## Related reading
+
+- [Per‑User Dev Environments with Fly Machines](/docs/blueprints/per-user-dev-environments/) Find out how to run isolated, on‑demand environments for each user.
+- [Observability for User Apps](/docs/blueprints/observability-for-user-apps/) Learn about how to gather logs and telemetry from per‑user apps/machines once you’ve routed traffic to them.
+- [Dynamic Request Routing with fly‑replay](/docs/networking/dynamic-request-routing/) Learn about the `fly‑replay` header and dynamic request routing.

blueprints/going-to-production-with-healthcare-apps.html.md

@@ -9,9 +9,11 @@ redirect_from: /docs/blueprints/going-to-production-with-hipaa-apps
   <img src="/static/images/production-healthcare.png" alt="Illustration by Annie Ruygt of a balloon doctor using stethescope on an app" class="w-full max-w-lg mx-auto">
 </figure>
 
+## Overview
+
 Fly.io was built by security researchers from the ground up to be both productive and secure, making it a great home for HIPAA-compliant production healthcare applications for productive teams that ship often.
 
-This blueprint runs a developer or operations engineer through the process of evaluating Fly.io's security for HIPAA healthcare apps, launching a pilot application, signing a Business Associate Agreement (BAA), and deploying to production.
+This guiide runs a developer or operations engineer through the process of evaluating Fly.io's security for HIPAA healthcare apps, launching a pilot application, signing a Business Associate Agreement (BAA), and deploying to production.
 
 ## HIPAA and Fly.io Primer
 
@@ -178,3 +180,8 @@ Finally run `fly deploy --path fly.production.yml` to deploy your application, t
 ## Wrap-up
 
 Fly.io is a secure, productive platform for deploying HIPAA-compliant healthcare applications. The platform provides the necessary security controls and features to ensure that PHI is protected in accordance with HIPAA requirements while giving development teams the flexibility to ship often and scale quickly.
+
+## Related reading
+
+- [Healthcare apps on Fly.io](/docs/about/healthcare/) Overview of how Fly.io supports HIPAA‑compliant apps, including encryption, network isolation, and audit‑controls.
+- [Going to production checklist](/docs/apps/going-to-production/) A general production‑readiness checklist for apps on Fly.io.

blueprints/infra-automation-without-terraform.html.md

@@ -164,3 +164,10 @@ The Machines API doesn’t lock you into a flow, we just give you the primitives
 We know it sucks when a tool you relied on gets deprecated. Terraform made a lot of things feel clean and declarative. But when it comes to the Machines API specifically, Terraform was always working at a bit of a mismatch since it tries to express an inherently imperative lifecycle in a declarative model. The Machines API gives you fine-grained control and flexibility that didn’t map cleanly to Terraform's abstractions. With a little effort, you can build exactly what you need, and avoid being boxed in by someone else’s idea of what an app should look like.
 
 If you're rebuilding that tooling now, let us know what you're working on. We might be able to help, or at least learn something from it.
+
+## Related Reading
+
+- [Continuous Deployment with flyctl and GitHub Actions](https://fly.io/docs/launch/continuous-deployment-with-github-actions/) Walk‑through on wiring CI/CD with Fly.io + GitHub Actions.
+- [Access Tokens for Fly.io](https://fly.io/docs/security/tokens/) Deep dive into token scopes, permissions, and best practices for automation workflows.
+- [Working with the Machines API](https://fly.io/docs/machines/api/working-with-machines-api/)  Reference guide for automating at the VM/“machine” level (the lower‑level alternative to flyctl).
+- [App Configuration (`fly.toml`)](https://fly.io/docs/reference/configuration/) Details on how your app config file works, which is often part of your automation setup.

blueprints/multi-region-fly-replay.html.md

@@ -8,9 +8,11 @@ nav: guides
   <img src="/static/images/multi-region.png" alt="Illustration by Annie Ruygt of Frankie looking out over the solar system" class="w-full max-w-lg mx-auto">
 </figure>
 
+## Overview
+
 You want to run your app and database in multiple [regions](/docs/reference/regions/) close to your users, and deploying database read replicas will give you better performance on read requests. This is a good solution for apps with read-heavy database workloads. But you also want writes to be efficient, despite needing to write to a primary database on the other side of the world.
 
-This blueprint will help you understand the concepts to implement an app, with a primary database and read replicas in multiple regions, that uses the `fly-replay` response header to re-route write requests to the primary region. Consider using this blueprint when:
+This guide will help you understand the concepts to implement an app, with a primary database and read replicas in multiple regions, that uses the `fly-replay` response header to re-route write requests to the primary region. Consider using this guide when:
 
 - Your app's users are in more than one geographic region and you want low latency for reads in all regions.
 - Your app has a request distribution of less than 50% writes.
@@ -102,14 +104,11 @@ Example implementations of this multi-region database with `fly-replay` pattern
 - [Fly Ruby gem](https://github.com/superfly/fly-ruby+external) for running database replicas alongside your app instances in multiple regions.
 - [Fly Postgres Elixir library](https://github.com/superfly/fly_postgres_elixir+external) for geographically distributed Elixir applications using Ecto and PostgreSQL in a primary/replica configuration on Fly.io.
 
-## Read more
+## Related reading
 
 We've covered multi-region databases with `fly-replay` in some past blog posts and in our docs:
 
 - [Globally Distributed Postgres](https://fly.io/blog/globally-distributed-postgres/)
-
 - [Multi-Region Laravel with PlanetScale](https://fly.io/laravel-bytes/multi-region-laravel-with-planetscale/)
-
 - [Run Ordinary Rails Apps Globally](https://fly.io/ruby-dispatch/run-ordinary-rails-apps-globally/)
-
-- [Dynamic Request Routing](/docs/networking/dynamic-request-routing/) docs
+- [Dynamic Request Routing](/docs/networking/dynamic-request-routing/)

blueprints/n-tier-architecture.html.md

@@ -10,7 +10,7 @@ date: 2025-08-29
   <img src="/static/images/get-started-n-tier.png" alt="Illustration by Annie Ruygt of a bird slicing a loaf of bread-think app layers" class="w-full max-w-lg mx-auto">
 </figure>
 
-## What is n-tier architecture?
+## Introduction: What is n-tier architecture?
 
 When people talk about “**n-tier architecture**,” they’re describing a way of splitting an app into layers (or “tiers”) that each have a specific job. The “**n**” just means there could be two, three, or more tiers depending on how you slice things.
 
@@ -122,7 +122,7 @@ Every request can hit any Machine, and all Machines share the same Postgres. Tha
 
 ---
 
-## Next steps and related reading
+## Related reading
 
 - Explore the features of [Fly Managed Postgres](/docs/mpg/) 
 - Find out how to [scale apps on Fly](/docs/launch/scale-count/)

blueprints/observability-for-user-apps.html.md

@@ -9,6 +9,8 @@ date: 2025-05-26
   <img src="/static/images/observability.png" alt="Illustration by Annie Ruygt of a printed photo depicting a bird and a ghost backpacking through a forest" class="w-full max-w-lg mx-auto">
 </figure>
 
+## Overview
+
 When you run a platform for users to execute their own code on Fly.io—[think per-user development environments](/docs/blueprints/per-user-dev-environments/) or AI/LLM apps—it's a good idea to have real-time observability for those user apps. You might _also_ want to stream logs from those apps back to the original developer (your end-user), so they can see what their code is doing.
 
 Fly.io offers built-in telemetry based on [**NATS**](https://nats.io/) that you can tap into to achieve this. At a high level, Fly.io captures everything your app writes to stdout and funnels it into an internal NATS log stream. A proxy in front of this NATS cluster ensures that each organization can only access its own applications' logs. Both the `flyctl logs` command and the our web dashboard's "Live Logs" use this pipeline under the hood. We can use the same system! By connecting a NATS client within your Fly organization's [private network](/docs/networking/private-networking/), we can subscribe to log subjects and stream logs out to wherever we need, in real-time.
@@ -111,3 +113,9 @@ The router itself is a Fly app that does the following:
 - Ensure that each developer only receives their own app's logs. The router should use the mapping of app ← → user to publish the right data to the correct output channel (and not mix different users' data).
 
 This approach uses one NATS subscription _per user app_. The messages are forwarded verbatim to the user's websocket in this case (as JSON strings), but you could transform them (for example, format them nicely or filter out certain internal logs) before sending. On the client side, you would simply read from the websocket or SSE stream and append new log lines to a console view.
+
+## Related reading
+
+- [Logging overview](/docs/monitoring/logging-overview/) How logs flow from your Fly apps into the platform’s NATS pipeline.
+- [Logs API options](/docs/monitoring/logs-api/) Guide with approaches for tapping directly into structured logs programmatically.
+- [fly-telemetry](https://github.com/superfly/fly-telemetry) Lightweight reference implementation for quick, out-of-the-box observability for deployments on Fly.io.

blueprints/opensshd.html.md

@@ -13,6 +13,8 @@ redirect_from: /docs/app-guides/opensshd/
   <img src="/static/images/openssh.png" alt="Illustration by Annie Ruygt of a terminal window, a computer and some numbers" class="w-full max-w-lg mx-auto">
 </figure>
 
+## Overview
+
 A number of tools allow you to interact with your server over SSH. These tools are useful for tasks such as
 copying files ([rsync](https://rsync.samba.org/+external), [scp](https://en.wikipedia.org/wiki/Secure_copy_protocol+external), [sshfs](https://github.com/libfuse/sshfs#sshfs+external)), 
 editing ([emacs](https://www.gnu.org/software/emacs/manual/html_node/emacs/Remote-Files.html+external), [vim](https://www.vim.org/scripts/script.php?script_id=1075+external), [vscode](https://code.visualstudio.com/docs/remote/ssh+external)), and
@@ -208,3 +210,8 @@ Additionally, if you want to avoid the fingerprint checking, you can add the fol
 ```config
 StrictHostKeyChecking no
 ```
+
+### Related Reading
+
+- [`flyctl` SSH commands](https://fly.io/docs/flyctl/ssh/) Official reference for how to use `fly ssh`/`fly ssh sftp` to access running machines. 
+- [Multiple processes inside a Fly.io app](https://fly.io/docs/app-guides/multiple-processes/) Explains how to run multiple process groups in a single machine/container. Relevant when you’re adding `sshd` alongside your main app.