foundriesio · vanmaegima · Jul 16, 2025 · Jul 1, 2025 · Jul 15, 2025
diff --git a/source/getting-started/install-fioctl/index.rst b/source/getting-started/install-fioctl/index.rst
@@ -203,6 +203,9 @@ After :ref:`Fioctl <ref-fioctl>` is setup, you can leverage it as a Git credenti
 This allows pushing to your :ref:`Factory <ref-factory-definition>` repositories.
 With this, Git knows when you connect to ``source.foundries.io`` and uses Fioctl for authentication when utilizing ``git`` commands.
 
+.. note::
+   Make sure ``git`` is installed on your host machine.
+
 Setting Up Git
 ^^^^^^^^^^^^^^
 

diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst
@@ -6,6 +6,12 @@
 The following tutorials will help familiarize you with the workflow for your Factory.
 As the concepts build upon others, follow them sequentially.
 
+.. important::
+   The tutorials assume you have followed the Getting Started and that you have a :ref:`registered device <gs-register>`.
+
+   Make sure you have ``git`` and :ref:`Fioctl <gs-install-fioctl>` installed on your host machine.
+   ``QEMU`` is also required if it is set in your Factory.
+
 :ref:`tutorial-gs-with-docker` introduces ``docker-compose`` apps.
 Next is :ref:`tutorial-creating-first-target` —learning what a :term:`Target` is through experience is key to using your Factory.
 

diff --git a/source/user-guide/qemu/arm.rst b/source/user-guide/qemu/arm.rst
@@ -34,3 +34,7 @@ QEMU CLI
 
 .. tip::
     You can register your device by following the steps from :ref:`gs-register`.
+
+.. include:: resize.template
+
+.. include:: booting-graphically.template
diff --git a/source/user-guide/qemu/arm64.rst b/source/user-guide/qemu/arm64.rst
@@ -61,3 +61,7 @@ QEMU CLI
 
 .. tip::
     You can register your device by following the steps from :ref:`gs-register`.
+
+.. include:: resize.template
+
+.. include:: booting-graphically.template
diff --git a/source/user-guide/qemu/booting-graphically.template b/source/user-guide/qemu/booting-graphically.template
@@ -0,0 +1,51 @@
+Booting Graphically
+-------------------
+
+This section shows how to boot QEMU with an OpenGL capable virtual GPU—required for Wayland/Weston.
+To check the available options for your system, use the ``-display help`` flag:
+
+.. parsed-literal::
+   $ qemu-system-aarch64 -display help
+   Available display backend types:
+   none
+   curses
+   cocoa
+   dbus
+
+In general, adding the following flags to the QEMU CLI should work:
+
+.. tabs::
+
+   .. group-tab:: Linux
+
+      .. parsed-literal::
+
+         |QEMU_GUI_FLAGS_LINUX|
+
+   .. group-tab:: macOS
+
+      .. parsed-literal::
+
+         |QEMU_GUI_FLAGS_MAC|
+
+Also, do not copy the ``-nographic`` flag at the end of the QEMU CLI below.
+
+.. note::
+
+    You can also utilize the option ``-display default``.
+    This attempts to use the default display type corresponding to the operating system on which you are running the command.
+
+.. important::
+
+   Specifying display options in QEMU does not make console-only images graphical.
+   It just opens a potential graphical output window; interaction remains text-based.
+   Images created with ``DISTRO=lmp-xwayland`` or ``DISTRO=lmp-wayland`` have graphical interfaces.
+   For further information see: :ref:`LmP Wayland and LmP XWayland <ref-lmp-wayland-xwayland>`.
+
+   If you are following :ref:`gs-flash-device` and downloading the console image, it will not boot with a graphical interface.
+   See :ref:`Customizing the Distro <ref-customizing-the-distro>` to know how to build a new Target image.
+   Ensure that you download the image with the interface, which is usually prefixed with ``lmp-factory-image``.
+
+   Compatibility of the display options may vary, and not all options are supported on every host OS.
+   Refer to the `QEMU Documentation <https://www.qemu.org/>`_ for more advanced configurations and options.
+
diff --git a/source/user-guide/qemu/qemu-instructions.template b/source/user-guide/qemu/qemu-instructions.template
@@ -1,14 +1,14 @@
 **Artifacts:**
 
-.. important::
-    If you are using a prebuilt Target, your artifacts may begin with ``lmp-base-console-image`` instead.
-
 .. parsed-literal::
 
      └── |ARCH|
          ├── lmp-factory-image-|MACHINE|.wic.gz
          └── |FIRMWARE_BLOB|
 
+.. important::
+    If you are using a prebuilt Target, your artifacts may begin with ``lmp-base-console-image`` instead.
+
 Booting in QEMU
 ---------------
 
@@ -40,96 +40,20 @@ Booting in QEMU
    .. parsed-literal::
         gunzip lmp-factory-image-|MACHINE|.wic.gz
 
-#. `Optional`. Create and resize a qcow2 image:
-
-   .. parsed-literal::
-        qemu-img create -f qcow2 -F raw -b lmp-factory-image-|MACHINE|.wic |MACHINE|\_device1.qcow2
-        qemu-img resize -f qcow2 |MACHINE|\_device1.qcow2 8G
-
-   The above example creates and then resizes to 8G—set to meet your needs.
 
-
 #. The directory tree should now look like this:
 
    .. parsed-literal::
 
         lmp-qemu/
         └── |ARCH|
             ├── lmp-factory-image-|MACHINE|.wic
-            ├── |MACHINE|\_device1.qcow2 # optional, needed if resizing is required
             └── |FIRMWARE_BLOB|
 
-#. Run the QEMU script below against the artifacts inside of ``lmp-qemu/``.
+#. Run the QEMU script in the next section against the artifacts inside of ``lmp-qemu/``.
    You can save this as ``run.sh`` inside the directory for convenience.
 
-.. important::
-    Use  .qcow2 if you wish to change the QEMU disk size, or if you are looking to emulate multiple devices.
-    Each image converted and subsequently run with QEMU will be recognized as a distinct device.
-    If you are using the qcow2 image, change the script so that:
-
-       * ``file=`` is set as the qcow2 image name, i.e., |MACHINE|\_device1.qcow2
-       * ``format=raw`` is replaced with ``format=qcow2``.
-
-    For example, replacing `MACHINE` appropriately:
-
-       .. parsed-literal::
-
-            |QEMU_COW|
-
 .. note::
     The QEMU CLI passes the necessary flags and parameters to the appropriate qemu-system command.
     This includes path to the image, CPU, network, and other device information.
     For specifics, consult `QEMU's Documentation. <https://www.qemu.org/docs/master/index.html>`_
-
-Booting Graphically
--------------------
-
-This section shows how to boot QEMU with an OpenGL capable virtual GPU—required for Wayland/Weston.
-To check the available options for your system, use the ``-display help`` flag:
-
-.. parsed-literal::
-   $ qemu-system-aarch64 -display help
-   Available display backend types:
-   none
-   curses
-   cocoa
-   dbus
-
-In general, adding the following flags to the QEMU CLI should work:
-
-.. tabs::
-
-   .. group-tab:: Linux
-
-      .. parsed-literal::
-
-         |QEMU_GUI_FLAGS_LINUX|
-
-   .. group-tab:: macOS
-
-      .. parsed-literal::
-
-         |QEMU_GUI_FLAGS_MAC|
-
-Also, do not copy the ``-nographic`` flag at the end of the QEMU CLI below.
-
-.. note::
-
-    You can also utilize the option ``-display default``.
-    This attempts to use the default display type corresponding to the operating system on which you are running the command.
-
-
-.. important::
-
-   Specifying display options in QEMU does not make console-only images graphical.
-   It just opens a potential graphical output window; interaction remains text-based.
-   Images created with ``DISTRO=lmp-xwayland`` or ``DISTRO=lmp-wayland`` have graphical interfaces.
-   For further information see: :ref:`LmP Wayland and LmP XWayland <ref-lmp-wayland-xwayland>`.
-
-   If you are following :ref:`gs-flash-device` and downloading the console image, it will not boot with a graphical interface.
-   See :ref:`Customizing the Distro <ref-customizing-the-distro>` to know how to build a new Target image.
-   Ensure that you download the image with the interface, which is usually prefixed with ``lmp-factory-image``.
-
-   Compatibility of the display options may vary, and not all options are supported on every host OS.
-   Refer to the `QEMU Documentation <https://www.qemu.org/>`_ for more advanced configurations and options.
-
diff --git a/source/user-guide/qemu/resize.template b/source/user-guide/qemu/resize.template
@@ -0,0 +1,26 @@
+Image Resizing
+^^^^^^^^^^^^^^
+
+If required, the Factory image can be resized for more space available.
+
+Create and resize a ``qcow2`` image:
+
+.. parsed-literal::
+   qemu-img create -f qcow2 -F raw -b lmp-factory-image-|MACHINE|.wic |MACHINE|\_device1.qcow2
+   qemu-img resize -f qcow2 |MACHINE|\_device1.qcow2 8G
+
+The above example creates and then resizes to 8G—set to meet your needs.
+
+This requires changes to the script so that:
+
+       * ``file=`` is set as the qcow2 image name, i.e., |MACHINE|\_device1.qcow2
+       * ``format=raw`` is replaced with ``format=qcow2``.
+
+So for example, the CLI command to run the resized image is:
+
+.. parsed-literal::
+   |QEMU_COW|
+
+.. important::
+    Use ``qcow2`` if you wish to change the QEMU disk size, or if you are looking to emulate multiple devices.
+    Each image converted and subsequently run with QEMU will be recognized as a distinct device.
diff --git a/source/user-guide/qemu/x86_64.rst b/source/user-guide/qemu/x86_64.rst
@@ -31,3 +31,7 @@ QEMU CLI
 
 .. tip::
     You can register your device following the steps from :ref:`gs-register`.
+
+.. include:: resize.template
+
+.. include:: booting-graphically.template