canonical · akcano · Jul 9, 2026 · Jul 9, 2026
diff --git a/docs/doc-style-guide.md b/docs/doc-style-guide.md
@@ -177,6 +177,35 @@ Use `.. @artefact` comments to mark key concepts for coverage tracking:
 The current list of these concepts is maintained in `docs/coverage.yaml`;
 update it as needed.
 
+**Prerequisites sections**
+
+State a page's prerequisites in a dedicated `Prerequisites` section so readers
+can confirm they are ready before following any steps.
+
+- In a how-to, place `Prerequisites` as a top-level section (H2, dashes)
+  immediately after the opening paragraph and before the first procedure section.
+  In a tutorial that installs Workshop, place it as a subsection (H3, tildes)
+  under the `Install` section instead.
+- Open the section with `Before starting, ensure you have these requirements satisfied:`,
+  followed by a bullet list with one requirement per item.
+- List only genuine, non-obvious prerequisites: specific external tools, accounts,
+  or hardware, and version-pinned dependencies such as LXD 6.8 or later.
+- Omit the universally assumed baseline (an existing `workshop.yaml`, the Workshop
+  CLI, an Ubuntu or snap-enabled host) unless a particular version or
+  configuration matters. If a page needs nothing beyond that baseline, omit the
+  section rather than pad it.
+
+```restructuredtext
+Prerequisites
+-------------
+
+Before starting, ensure you have these requirements satisfied:
+
+- LXD 6.8 or later running on the host.
+
+- An Ubuntu One account.
+```
+
 ---
 
 ## Writing style and tone

diff --git a/docs/how-to/customize-workshops/use-host-devices.rst b/docs/how-to/customize-workshops/use-host-devices.rst
@@ -27,6 +27,18 @@ find the subsystem, declare a plug, connect the interface,
 then use the devices inside the workshop.
 
 
+Prerequisites
+-------------
+
+Before starting, ensure you have these requirements satisfied:
+
+- A host device you want to expose to the workshop,
+  such as an input device at :file:`/dev/input/event0`.
+
+- :command:`udevadm` available on the host
+  to identify the device subsystem.
+
+
 Identify the device subsystem
 -----------------------------
 

diff --git a/docs/how-to/develop-sdks/configure-mount.rst b/docs/how-to/develop-sdks/configure-mount.rst
@@ -45,8 +45,11 @@ or when the SDK should not be able to write to the mount.
 Prerequisites
 -------------
 
-You need an :file:`sdkcraft.yaml` that declares at least one mount plug;
-:ref:`ref_sdk_plugs_slots` covers the declarations.
+Before starting, ensure you have these requirements satisfied:
+
+- An :file:`sdkcraft.yaml` that declares at least one mount plug.
+  :ref:`ref_sdk_plugs_slots` covers the declarations.
+
 The attributes below extend the plug entries
 under the top-level :samp:`plugs:` key.
 

diff --git a/docs/how-to/develop-sdks/declare-plugs-slots.rst b/docs/how-to/develop-sdks/declare-plugs-slots.rst
@@ -26,11 +26,15 @@ follow the same shape.
 Prerequisites
 -------------
 
-You need a working |sdk_markup| installation
-and an :file:`sdkcraft.yaml` you can edit.
-If you don't have one yet,
-:ref:`tut_craft_sdks` walks through scaffolding an SDK with
-:command:`sdkcraft init`.
+Before starting, ensure you have these requirements satisfied:
+
+- |sdk_markup| installed.
+
+- An :file:`sdkcraft.yaml` you can edit.
+  If you don't have one yet,
+  :ref:`tut_craft_sdks` walks through scaffolding an SDK with
+  :command:`sdkcraft init`.
+
 The declarations below go under top-level
 :samp:`plugs:` and :samp:`slots:` keys in :file:`sdkcraft.yaml`.
 

diff --git a/docs/how-to/develop-sdks/write-runtime-hooks.rst b/docs/how-to/develop-sdks/write-runtime-hooks.rst
@@ -31,9 +31,13 @@ Where it differs is the privilege, working directory, and extra environment.
 Prerequisites
 -------------
 
-You need a working |sdk_markup| installation
-and a workshop you can launch and refresh
-on a host with |ws_markup| installed.
+Before starting, ensure you have these requirements satisfied:
+
+- |sdk_markup| installed.
+
+- A workshop you can launch and refresh
+  on a host with |ws_markup| installed.
+
 The examples use a synthesized SDK named :file:`dotfiles-sdk`.
 If you don't have an SDK yet,
 :ref:`tut_craft_sdks` walks through scaffolding one with

diff --git a/docs/how-to/develop-with-workshops/run-jetbrains-gateway.rst b/docs/how-to/develop-with-workshops/run-jetbrains-gateway.rst
@@ -21,14 +21,14 @@ letting you use your favorite JetBrains IDEs against |ws_markup|.
 Prerequisites
 -------------
 
-Before starting, ensure you have:
+Before starting, ensure you have these requirements satisfied:
 
 - `JetBrains Gateway <https://www.jetbrains.com/remote-development/gateway/>`__
-   installed on your host system.
+  installed on your host system.
 
 - An SSH key pair available on the host system.
-   If you don't have one already,
-   generate it with:
+  If you don't have one already,
+  generate it with:
 
   .. code-block:: console
 

diff --git a/docs/how-to/develop-with-workshops/run-workshops-in-github-actions.rst b/docs/how-to/develop-with-workshops/run-workshops-in-github-actions.rst
@@ -26,7 +26,7 @@ see :ref:`how_run_github_actions_locally`.
 Prerequisites
 -------------
 
-Before getting started, ensure you have:
+Before starting, ensure you have these requirements satisfied:
 
 - A GitHub repository with Actions enabled
 

diff --git a/docs/how-to/develop-with-workshops/use-workshops-with-ai-agents.rst b/docs/how-to/develop-with-workshops/use-workshops-with-ai-agents.rst
@@ -63,19 +63,21 @@ and synthesizes the optimal approach in different ways:
 Prerequisites
 -------------
 
-Working with AI agents in workshops builds on :ref:`how_git_workshops`
-and :ref:`how_add_actions`,
-particularly the use of Git worktrees with workshops.
-Worktrees help isolate and track different agents' runs and outcomes
-while sharing the same project directory and the workshops in it.
-
-Note that the :program:`claude-code` and :program:`copilot` SDKs
-will prompt for login credentials on their first run;
-you should have a browser window open with the respective account signed in.
-Alternatively,
-the agents support token-based API authentication via environment variables,
-which allows you to skip the login steps below;
-refer to their respective documentation and runtime help for details.
+Before starting, ensure you have these requirements satisfied:
+
+- Familiarity with Git worktrees in workshops,
+  as covered in :ref:`how_git_workshops` and :ref:`how_add_actions`.
+  Worktrees help isolate and track different agents' runs and outcomes
+  while sharing the same project directory and the workshops in it.
+
+- Access to the :program:`claude-code` and :program:`copilot` agents
+  (or similar alternatives).
+  Both agents prompt for login credentials on their first run,
+  so have a browser window open with the respective account signed in.
+  Alternatively,
+  the agents support token-based API authentication via environment variables,
+  which allows you to skip the login steps below;
+  refer to their respective documentation and runtime help for details.
 
 Agent prompts
 -------------