Update recipes overview

astro.config.mjs

@@ -144,9 +144,12 @@ export default defineConfig({
                 { slug: "packaging/workflow" },
                 { slug: "packaging/workflow/prerequisites" },
                 { slug: "packaging/workflow/basic-workflow" },
+                { slug: "packaging/workflow/preparing-for-packaging" },
                 { slug: "packaging/workflow/creating-a-new-recipe" },
                 { slug: "packaging/workflow/updating-an-existing-recipe" },
+                { slug: "packaging/workflow/building-and-testing-packages" },
                 { slug: "packaging/workflow/submitting-a-pr" },
+                { slug: "packaging/workflow/checking-for-updates" },
               ],
             },
             {

src/content/docs/Packaging/Recipes/overview.mdx

@@ -1,6 +1,6 @@
 ---
 title: 'Overview'
-lastUpdated: 2024-09-07T23:44:13Z
+lastUpdated: 2026-01-26T09:00:00Z
 description: Introduction to the `stone.yaml` format
 ---
 
@@ -13,15 +13,26 @@ How might a `stone.yml` look like for a very trivial package, such as the [Nano
 
 ```yaml
 name        : nano
-version     : 5.5
-release     : 2
-summary     : GNU Text Editor
-license     : GPL-3.0-or-later
+version     : 8.7
+release     : 38
 homepage    : https://www.nano-editor.org/
-description : |
-    The GNU Text Editor
 upstreams   :
-    - https://www.nano-editor.org/dist/v5/nano-5.5.tar.xz: 390b81bf9b41ff736db997aede4d1f60b4453fbd75a519a4ddb645f6fd687e4a
+    - https://www.nano-editor.org/dist/v8/nano-8.7.tar.xz : afd287aa672c48b8e1a93fdb6c6588453d527510d966822b687f2835f0d986e9
+summary     : GNU Text Editor
+description : |
+    Nano is a small and simple text editor for use on the terminal.
+    It copied the interface and key bindings of the Pico editor but
+    added several missing features: undo/redo, syntax highlighting,
+    line numbers, softwrapping, multiple buffers, selecting text by
+    holding Shift, search-and-replace with regular expressions, and
+    several other conveniences.
+license     :
+    - GPL-3.0-or-later
+builddeps   :
+    - binary(msgfmt)
+    - pkgconfig(libmagic)
+    - pkgconfig(ncursesw)
+    - pkgconfig(zlib)
 setup       : |
     %configure
 build       : |

src/content/docs/Packaging/Workflow/basic-workflow.mdx

@@ -1,5 +1,5 @@
 ---
-title: 'Basic Packaging Workflow'
+title: 'Basic packaging workflow'
 lastUpdated: 2025-06-23T00:00:00Z
 description: "Building packages locally and testing them"
 ---

src/content/docs/Packaging/Workflow/building-and-testing-packages.mdx

@@ -0,0 +1,54 @@
+---
+title : 'Building and testing packages'
+lastUpdated: 2026-01-25T12:00:00+00:00
+description: "How to build and test packages locally on your system"
+---
+import { Aside } from '@astrojs/starlight/components';
+
+
+This guide will walk you through the process of building and testing packages locally on your system, regardless of whether they come from new package recipes or existing ones you are updating.
+
+## Build the package
+
+Once you have created or updated a package recipe, you will need to build it locally. If you are only updating one package, you can either keep your local repository disabled prior to building the package. If you prefer to keep it enabled, make sure there are no other packages indexed locally that could interfere with your new package build.
+
+<Aside type="note">
+    Please ensure you have followed the steps in the [Preparing for Packaging](/packaging/workflow/preparing-for-packaging/) guide to ensure you volatile repository is enabled.
+</Aside>
+
+
+The command to build the updated package is:
+
+```bash
+just build
+```
+
+If the package is successfully built, you will need to move it to your local repository. You can do this using the following command:
+
+```bash
+just mv-local
+```
+
+If you have not yet enabled the local repository, you do this with the following command:
+
+```bash
+sudo moss repo enable local
+```
+
+You will then need to sync the local repository using the command:
+
+```bash
+sudo moss sync -u
+```
+
+Note, if you already have an older version of the package installed, you will be asked if you want to update to the new local version you have just built. If you have not yet installed this package, you would install it as normal using the command:
+
+```bash
+sudo moss install "package name"
+```
+
+Once you have tested the package, you can make a submission for including the update in the repository.
+
+<Aside type="tip" title="How to submit pull requests">
+  To find guidance on how to submit a pull request (PR), you can refer to our [submit a pull request](/packaging/workflow/submitting-a-pr) page.                    s
+</Aside>

src/content/docs/Packaging/Workflow/checking-for-updates.mdx

@@ -0,0 +1,48 @@
+---
+title : 'Checking for package updates'
+lastUpdated: 2026-01-25T12:00:00+00:00
+description: "How to check for package updates"
+---
+import { Aside } from '@astrojs/starlight/components';
+
+
+## Use `ent` to check for package updates
+
+This guide will walk you through the process using `ent`, a tool built by the AerynOS team to check for package updates. `ent` checks recipes against upstream sources to determine whether updates are available.
+
+`ent` is not installed on your system by default. To install `ent` using `moss`, use the following command:
+
+```bash
+sudo moss install ent
+```
+### How `ent` works
+
+`ent` scans the current directory and all subdirectories beneath it. It inspects each recipe `monitoring.yaml` file and compares the referenced `stone.yaml` recipe upstreams to determine whether newer versions are available.
+
+Because `ent` operates relative to the directory in which it is executed, you can control the scope of the update check by choosing where to run the command within the recipes repository.
+
+### Running update checks
+
+To check for updates across all recipes, run the following command from the root of the recipes repository:
+
+```bash
+gotoaosrepo
+ent check updates
+```
+
+You can also run this command from more specific locations:
+
+* **Repository root**
+  Checks all recipes in the repository.
+
+* **Letter directory (for example, `f/`)**
+  Checks only recipes whose names start with that letter.
+
+* **Specific recipe directory (for example, `f/firefox/`)**
+  Checks only that single recipe.
+
+For example, running the command from `f/firefox/` will check only the Firefox recipe for available updates.
+
+<Aside type="note" title="What is ent?">
+    `ent` queries an upstream site for package release info *every time you run it*. Please be mindful of not running it gratuitously so as to remain a good ecosystem citizen.
+</Aside>