Docs: Migrate structure to diataxes framework in markdown documents

Author: ByteOtter

docs/contributing/.gitkeep

@@ -0,0 +1,78 @@
+# Command-Line Interface
+
+This page documents all available command-line tools provided by
+python-gardenlinux-lib. Run `command --help` for detailed usage information.
+
+## Features Commands
+
+### gl-cname
+
+Generate a canonical name (cname) from feature sets.
+
+```bash
+gl-cname [options]
+```
+
+### gl-features-parse
+
+Parse and extract information from GardenLinux features.
+
+```bash
+gl-features-parse [options]
+```
+
+## Flavors Commands
+
+### gl-flavors-parse
+
+Parse flavors.yaml and generate combinations.
+
+```bash
+gl-flavors-parse [options]
+```
+
+## OCI Commands
+
+### gl-oci
+
+Push OCI artifacts to a registry and manage manifests.
+
+```bash
+gl-oci [command] [options]
+```
+
+Commands:
+
+- `push` - Push OCI artifacts to a registry
+- `manifest` - Manage OCI manifests
+
+## S3 Commands
+
+### gl-s3
+
+Upload and download artifacts from S3 buckets.
+
+```bash
+gl-s3 [command] [options]
+```
+
+Commands:
+
+- `upload` - Upload artifacts to S3
+- `download` - Download artifacts from S3
+
+## GitHub Commands
+
+### gl-gh-release
+
+Create and manage GitHub releases.
+
+```bash
+gl-gh-release [command] [options]
+```
+
+Commands:
+
+- `create` - Create a new release
+- `update` - Update an existing release
+- `list` - List all releases

docs/explanation/.gitkeep

@@ -0,0 +1,51 @@
+# Release Documentation
+
+_python-gardenlinux-lib_ strictly follows the syntax and intention of
+[Semantic Versioning](https://www.semver.org). Each release reflects the
+intention and expected impact therefore.
+
+A new release is done by tagging a commit with a valid version. This will create
+a GitHub pre-release for proof-reading. Once done a new release can be published
+using GitHub CLI or UI.
+
+Newly added docstrings should contain the first version supporting the new API /
+command line.
+
+## Step by Step Guide
+
+1. **Set version files:**
+
+   _python-gardenlinux-lib_ versioning needs to be set in:
+
+   - `pyproject.toml`
+   - `.github/actions/setup/action.yml`
+
+   Additionally at the moment (removal pending):
+
+   - `.github/actions/features_parse/action.yml`
+   - `.github/actions/flavors_parse/action.yml`
+
+2. **Create git tag:**
+
+   ```bash
+   git tag <tag>
+   ```
+
+3. **Review and publish:**
+
+   Review the generated pre-release changelog by visiting the GitHub project
+   release page and publish it if applicable.
+
+4. **Consume the library:**
+
+   Projects consuming the _python-gardenlinux-lib_ may use the following git URL
+   for dependency definition:
+
+   ```bash
+   pip install git+https://github.com/gardenlinux/python-gardenlinux-lib.git@1.0.0
+   ```
+
+   Or in `requirements.txt`:
+   ```
+   gardenlinux @ git+https://github.com/gardenlinux/python-gardenlinux-lib.git@1.0.0
+   ```

docs/how-to/cli.md

@@ -0,0 +1,43 @@
+# Garden Linux Python Library Documentation
+
+Welcome to the Garden Linux Python Library documentation. This library provides
+Python tools and utilities for working with Garden Linux features, flavors, OCI
+artifacts, S3 buckets, and GitHub releases.
+
+![Garden Linux Logo](../_static/gardenlinux-logo.svg)
+
+## Overview
+
+The Garden Linux Python Library is a comprehensive toolkit for managing and
+interacting with Garden Linux components. It includes:
+
+- **Feature Management**: Parse and work with Garden Linux features and generate
+  canonical names
+- **Flavor Processing**: Parse flavors.yaml and generate combinations
+- **OCI Operations**: Push OCI artifacts to registries and manage manifests
+- **S3 Integration**: Upload and download artifacts from S3 buckets
+- **GitHub Integration**: Create and manage GitHub releases with release notes
+
+## Quick Start
+
+### Command-Line Interface
+
+The library provides several command-line tools for common operations. See the
+[Command-Line Interface documentation](../reference/cli.md) for detailed
+information about all available commands.
+
+### Release Management
+
+For information about versioning and release procedures, see the
+[Release documentation](../how-to/release.md).
+
+### API Reference
+
+For detailed Python API documentation, including all modules, classes, and
+functions, see the
+[API Reference on ReadTheDocs](https://gardenlinux.github.io/python-gardenlinux-lib/api.html).
+
+## Documentation Sections
+
+- [Command-Line Interface](../reference/cli.md)
+- [Release documentation](../how-to/release.md)