Documentation review of Flatpak install guide

content/install-guides/flatpak.md

@@ -1,9 +1,9 @@
 ---
 title: "Flatpak"
 minutes_to_complete: 10
-official_docs: "https://flatpak.org"
+official_docs: "https://docs.flatpak.org/en/latest/"
 author: "Jason Andrews"
-description: "Install Flatpak on Arm Linux, add the Flathub remote, and verify the setup by running a native aarch64 application."
+description: "Install Flatpak on Arm Linux, add the Flathub remote, and verify the setup by installing and running a native aarch64 application."
 weight: 1
 draft: true
 tool_install: true
@@ -12,29 +12,29 @@ multi_install: false
 multitool_install_part: false
 ---
 
-Flatpak is a framework for distributing Linux applications. It provides distribution-agnostic packaging and a sandboxed runtime, so the same application bundle runs on Ubuntu, Fedora, Arch, and openSUSE without repackaging. [Flathub](https://flathub.org/) is the primary community-maintained repository of Flatpak applications, many of which publish native Arm builds.
+[Flatpak](https://flatpak.org/) is a framework for distributing Linux applications. It provides distribution-agnostic packaging and a sandboxed runtime, so the same application bundle runs on Ubuntu, Fedora, Arch, and openSUSE without repackaging. [Flathub](https://flathub.org/) is the primary community-maintained repository of Flatpak applications, many of which publish native Arm builds.
 
-## How does Flatpak sandboxing work?
+## How Flatpak sandboxing works
 
-Each Flatpak application runs inside an isolated environment built on three Linux kernel features: namespaces, seccomp, and cgroups. Namespaces give the application its own view of the filesystem, network, and process tree. Seccomp filters restrict the system calls the application can make. Together, these mechanisms prevent an application from reading files outside its sandbox or interfering with other processes on the host.
+Each Flatpak application runs inside an isolated environment built on three Linux kernel features: namespaces, secure computing mode (seccomp), and control groups (cgroups). Namespaces give the application its own view of the filesystem, network, and process tree. Seccomp filters restrict the system calls the application can make. Together, these mechanisms prevent an application from reading files outside its sandbox or interfering with other processes on the host.
 
 The sandbox is implemented by [bubblewrap](https://github.com/containers/bubblewrap), a low-level sandboxing tool that Flatpak calls at launch time. Applications declare the permissions they need, such as access to the home directory, the network, or audio devices, in a manifest. You can inspect and override these permissions using `flatpak override`.
 
-## How are Flatpak applications packaged?
+## How Flatpak applications are packaged
 
-A Flatpak application is distributed as an OSTree commit, a content-addressed filesystem tree stored in a local repository. When you install an application, Flatpak fetches only the changed objects from the remote, similar to how Git fetches commits. This makes updates efficient even for large applications.
+A Flatpak application is distributed as an [OSTree](https://ostreedev.github.io/ostree/introduction/) commit, a content-addressed filesystem tree stored in a local repository. When you install an application, Flatpak fetches only the changed objects from the remote, similar to how Git fetches commits. This makes updates efficient even for large applications.
 
-Applications either bundle their own libraries directly or declare runtime dependencies, such as `org.freedesktop.Platform` or `org.gnome.Platform`. The runtime provides a consistent base set of libraries, such as libc and GTK, that multiple applications can share on disk, reducing total storage. The application and its runtime are kept separate from the host system libraries, which means you don't need to resolve conflicts.
+Applications either bundle their own libraries directly or declare runtime dependencies, such as `org.freedesktop.Platform` or `org.gnome.Platform`. The runtime provides a consistent base set of libraries, such as libc and GTK. Multiple applications can share these libraries on disk, reducing total storage. The application and its runtime are kept separate from the host system libraries, which means you don't need to resolve conflicts.
 
 For Arm developers, the key advantage is that Flatpak applications can publish separate builds for `x86_64` and `aarch64` under the same application ID. Flatpak selects the correct architecture automatically at install time.
 
-## How does Flatpak compare to Linux package managers?
+## How Flatpak compares to Linux package managers
 
-Linux package managers like `apt`, `dnf`, and `pacman` are tightly coupled to the distribution release cycle. An application packaged for Ubuntu 24.04 may lag the upstream version, and some applications aren't packaged for every Linux distribution. Flatpak addresses this by letting upstream developers publish and maintain their own builds directly on Flathub. This allows you to get the current release of an application on any supported Linux distribution.
+Linux package managers such as `apt`, `dnf`, and `pacman` are tightly coupled to the distribution release cycle. An application packaged for Ubuntu 24.04 may lag the upstream version, and some applications aren't packaged for every Linux distribution. Flatpak addresses this by letting upstream developers publish and maintain their own builds directly on Flathub. This allows you to get the current release of an application on any supported Linux distribution.
 
-Because a Flatpak application bundles its own libraries or pins a specific runtime version, installing or updating it can't conflict with host system libraries or break other packages. A distro upgrade won't silently change the libraries an application links against. This also means you can run two different applications that require incompatible versions of the same library side by side without issues.
+A Flatpak application bundles its own libraries or pins a specific runtime version. As a result, installing or updating a Flatpak application can't conflict with host system libraries or break other packages. A distro upgrade won't silently change the libraries an application links against. This also means you can run two different applications that require incompatible versions of the same library side by side without issues. 
 
-The instructions below cover installing Flatpak on Arm Linux (aarch64), adding the Flathub remote, and verifying the installation by installing VSCodium.
+The following instructions cover installing Flatpak on Arm Linux (aarch64), adding the Flathub remote, and verifying the installation by installing and running VSCodium.
 
 ## Before you begin
 
@@ -44,13 +44,15 @@ Confirm your system is running a 64-bit Arm Linux distribution:
 uname -m
 ```
 
-The output should be:
+The output is similar to:
 
 ```output
 aarch64
 ```
 
-## How do I install Flatpak?
+## Install Flatpak
+
+The installation steps depend on your Linux distribution.
 
 ### Ubuntu or Debian
 
@@ -86,23 +88,23 @@ sudo zypper refresh
 sudo zypper install -y flatpak
 ```
 
-After installing, log out and back in to ensure desktop integration works correctly.
+After installing, log out and log back in to ensure that the desktop integration works correctly.
 
-## Verify Flatpak is installed
+## Confirm Flatpak is available
 
 Confirm Flatpak is available and check the version:
 
 ```bash
 flatpak --version
 ```
 
-The output will look similar to:
+The output is similar to:
 
 ```output
 Flatpak 1.16.1
 ```
 
-## How do I add the Flathub remote?
+## Add Flathub as a remote source
 
 Add the Flathub repository as a remote source:
 
@@ -123,17 +125,17 @@ Name    Options
 flathub system
 ```
 
-## How do I install the VSCodium Flatpak?
+## Verify Flatpak installation by installing and running VSCodium
 
-[VSCodium](https://vscodium.com/) is the telemetry-free build of VS Code, available on Flathub with a native Arm build, making it a useful application to test. 
+[VSCodium](https://vscodium.com/) is the telemetry-free build of VS Code that's available on Flathub with a native Arm build. This makes it a useful application to test Flatpak with. 
 
-Install it with the `--assumeyes` flag, which automatically answers yes to any prompts during installation:
+Install VSCodium with the `--assumeyes` flag, which automatically answers yes to any prompts during installation:
 
 ```bash
 flatpak install --assumeyes flathub com.vscodium.codium
 ```
 
-Confirm the installation and check the architecture:
+Confirm the VSCodium installation and check the architecture:
 
 ```bash
 flatpak info com.vscodium.codium
@@ -163,55 +165,80 @@ Installation: system
         Date: 2026-03-30 05:03:53 +0000
 ```
 
-The `Arch: aarch64` line confirms a native Arm build is installed.
+The `Arch: aarch64` line in the output confirms that you installed a native Arm build. 
 
-To start VSCodium on the project in your current directory, run:
+To run VSCodium on a project in your current directory, run:
 
 ```bash
 flatpak run com.vscodium.codium . &
 ```
+{{% notice Tip %}}
 
-You can also create an alias to make it easier:
+You can create an alias to make starting a project easier:
 
 ```bash
 alias codium='flatpak run com.vscodium.codium'
 ```
 
-Now, run using the alias:
+To run VSCodium using the alias, run:
 
 ```bash
 codium . &
+```  
+{{% /notice %}}
+
+By using Flatpak to install and run VSCodium successfully, you've verified that the Flatpak installation was a success.
+
+## Find Arm-native applications on Flathub
+
+You can now use Flatpak to install Arm-native applications. Flatpak makes it straightforward to discover which applications support aarch64. Visit the [Flathub app browser](https://flathub.org/apps) and filter by architecture to find applications with native Arm builds. You can also search from the command line after adding the Flathub remote:
+
+```bash
+flatpak remote-ls --app --arch=aarch64 flathub
 ```
 
-## What are some other useful Flatpak commands? 
+The command lists every application on Flathub that publishes a native aarch64 build. Use `grep` to narrow results by name or category.
+
+## Troubleshoot Flatpak issues
+
+You can use the following commands to troubleshoot issues with Flatpak.
+
+### Fix a corrupted, incomplete, or outdated installation
 
-If an installation becomes corrupted or incomplete, run `flatpak repair` to check your local Flatpak installation and fix any inconsistencies:
+If a Flatpak installation becomes corrupted or incomplete, run the following command to check your local Flatpak installation and fix any inconsistencies:
 
 ```bash
 flatpak repair
 ```
-
-To update all installed Flatpak applications and runtimes to their latest versions, run:
+To keep all installed Flatpak applications and runtimes up-to-date, run:
 
 ```bash
 flatpak update
 ```
 
-To inspect the sandbox permissions granted to an application, run:
+### Debug application permission or runtime issues
+
+If you need to inspect the sandbox permissions granted to a Flatpak application, run:
 
 ```bash
 flatpak info --show-permissions com.vscodium.codium
 ```
+The example command returns the sandbox permissions granted to VSCodium installed in the previous step. To adapt the command for your use case, replace `com.vscodium.codium` with your application's identifier. 
 
-To open an interactive shell inside an application's sandbox, which is useful for debugging permission or runtime issues, run:
+Opening an interactive shell inside a Flatpak application's sandbox is useful for debugging permission or runtime issues. To do so, run:
 
 ```bash
 flatpak run --command=bash com.vscodium.codium
 ```
+The example command opens a shell in VSCodium's sandbox. To adapt the command for your use case, replace `com.vscodium.codium` with your application's identifier. 
+
+{{% notice Note %}}
+Not all applications include `bash` in their sandbox, so this command may not work for every Flatpak application. In such cases, your shell prompt may not look any different, but you are in the sandbox. 
+{{% /notice %}}
 
-Note that not all applications include `bash` in their sandbox, so this command may not work for every Flatpak. Your shell prompt may not look any different, but you are in the sandbox. To confirm run:
+To confirm that the shell is open, run:
 
-```bash 
+```bash
 ls /app
 cat /etc/os-release
 ```
@@ -228,21 +255,11 @@ PRETTY_NAME="Freedesktop SDK 25.08 (Flatpak runtime)"
 BUG_REPORT_URL=https://gitlab.com/freedesktop-sdk/freedesktop-sdk/issues
 ```
 
-The `/app` directory contains the application runtime files, and the `os-release` file shows the Flatpak runtime rather than the host OS. 
-
-## How can I find Arm-native applications on Flathub?
-
-Flatpak makes it straightforward to discover which applications support aarch64. Visit the [Flathub app browser](https://flathub.org/apps) and filter by architecture to find applications with native Arm builds. You can also search from the command line after adding the Flathub remote:
-
-```bash
-flatpak remote-ls --app --arch=aarch64 flathub
-```
-
-This lists every application on Flathub that publishes a native aarch64 build. Use `grep` to narrow results by name or category.
+The `/app` directory contains the application runtime files. The `os-release` file shows the Flatpak runtime rather than the host OS. 
 
-## Uninstall
+## Clean up
 
-To remove VSCodium, run:
+To uninstall VSCodium, run:
 
 ```bash
 flatpak uninstall --assumeyes com.vscodium.codium
@@ -253,3 +270,4 @@ To remove the Flathub remote, run:
 ```bash
 sudo flatpak remote-delete flathub
 ```
+