stone: Extend the documentation about headers

src/content/docs/Developers/Stone/index.mdx

@@ -1,10 +1,35 @@
 ---
 title: Stone Format
-lastUpdated: 2025-03-28T05:28:00Z
-description: Binary stone format
+lastUpdated: 2026-04-11T00:00:00Z
+description: An overwiew of the Stone format
 ---
 import DirectoryList from '@components/DirectoryList.astro';
 
-The Stone format is a binary format used to package and distribute software in AerynOS. It is designed to be type-safe and version-aware.
+The Stone format is a binary format designed to be type-safe and version-aware.
+It is used to package and distribute software in AerynOS, in fact both the very packages and the index
+file of repositories use the Stone format.
+
+Anything encoded in the Stone format is called a *stone*.
+Each *stone* is composed of a Prelude (the global header) and zero or more payloads, each with its own sub-header.
+No limit is set for the length of a *stone*, but it will always be at least 32 byte long, that is the size of
+the Prelude.
+
+```text
+-------------------------------------------------------------
+|    PRELUDE    |     PAYLOAD 1    |     PAYLOAD 2    | .....
+|               | header | content | header | content | .....
+-------------------------------------------------------------
+       32          variable length    variable length
+```
+
+The fundamental types of the Stone format are integer numbers and strings.
+
+| Type | Format | Length (in bytes) | Description | Abbreviation|
+|---|---|---|---|---|
+| Signed integer | Big-endian | Various | Integer number with a sign. When negative, two's complement is used. The range of values goes from -2^(n-1) to 2^(n-1)-1, where `n` is the number of bytes. |uint|
+| Unsigned integer | Big-endian | Various | Integer number without a sign. The range of values goes from 0 to 2^(n)-1, where `n` is the number of bytes. |int|
+| String | UTF-8 | Various | A string of text, without the NULL termination. |str|
+
+The documentation will delve into the details of each section in the next pages.
 
 <DirectoryList/>

src/content/docs/Developers/Stone/prelude.mdx

@@ -0,0 +1,38 @@
+---
+title: Prelude
+lastUpdated: 2026-04-11T00:00:00Z
+description: The version-agnostic header of Stones
+---
+
+*Stones* are encoded with a version agnostic header, the Prelude, ensuring that version-specific
+fields can be handled separately from version and format detection. This is a 32-byte header at the start of the *stone*.
+
+## Fields
+
+| Field | Type | Size | Description |
+|---|---|---|---|
+| Magic | str | 4 | Always `0x006d6f73` |
+| Data | Version-dependent | 24 | Version-specific header of the *stone* |
+| Version | uint | 4 | Version number, i.e. `1` |
+
+### Magic
+
+It's the [magic number](https://en.wikipedia.org/wiki/Magic_number_(programming)) of the Stone format.
+
+The Magic field always contains `['\0', 'M', 'O', 'S']`.
+It is defined after AerynOS's package manager: `moss`.
+
+In the Rust language it is defined as:
+
+```rust
+pub const STONE_MAGIC: &[u8; 4] = b"\0mos";
+```
+
+### Data
+
+The content of the Data field depends on the Version field.
+Documentation about Stone versions is available in the next pages.
+
+### Version
+
+A number that unique identifies the version of the Stone format in use.