= Project Name: Authority-First Deployment
:author: Hyperpolymath
:revnumber: 0.1.0-Alpha
:toc: macro
:toclevels: 3
:icons: font

toc::[]

---

== Status: Alpha
This project adheres to the *Mustfile* and *must-spec* (0.1.0-Alpha) for deployment. It represents a **Contract of Physical State** based on Ephapax Linear Logic.

IMPORTANT: This project strictly forbids the use of `Makefiles`. All local tasks are orchestrated via `just`, and all deployment transitions are managed via `must`.

== Design Philosophy
The deployment architecture is environment-agnostic and prioritises **Just Route** logic. Every operation is treated as a state transition where resources are consumed to produce outputs, ensuring no orphaned state or unvalidated side effects.

* **Podman First**: Containerisation is the primary deployment vector.
* **Universal Shell Support**: 17 shell variants (bash, oil, nushell, etc.) are supported via referenced scripts.
* **Configuration**: Handled via `nickel` for validated, type-safe manifests.

== Prerequisites
To maintain the integrity of the build and deployment pipeline, ensure the following are installed:

1. **just**: Command runner for local development.
2. **must**: The supervisor for `must-spec` contract enforcement.
3. **podman**: Primary container engine.
4. **asdf**: Multi-runtime version manager (plugin installation is automated via `just`).

[source,bash]
----
# Quick bootstrap for essential tools
./scripts/bootstrap.sh
----

== Usage

=== Local Development
Local tasks are documented in the `cookbook.adoc`. Use `just` to view available recipes:

[source,bash]
----
just --list
----

=== Deployment (The Mustfile)
The `Mustfile.epx` governs the physical state of the deployment. It handles everything from `rpm-ostree` layering to `nala` extensions on Debian-based systems.

[source,bash]
----
# Execute the deployment contract
must deploy
----

== Shell Support
This project provides native wrappers for a comprehensive list of shells to ensure compatibility across Linux, Minix, macOS, iOS, Android, and PC (ASIC/Edge-specific environments included).

Only the **bash** entry point is shown here. All other 16 shell implementations (cmd, oil, ash, csh, dash, elvish, fish, ion, ksh, murex, ngs, nushell, powershell-core, tcsh, tsh, zsh, and minix shell) are located in the link:scripts/shells/[scripts/shells/] directory.

.scripts/entrypoint.sh (Bash)
[source,bash]
----
#!/usr/bin/env bash
set -euo pipefail

# Ensure just is present
if ! command -v just &> /dev/null; then
    echo "Error: 'just' not found. Please install via https://just.systems"
    exit 1
fi

# Route to just recipe
just "$@"
----

== Package Management
Supported package managers and deployment routes are managed through `nicagu` (Nickel-Augmented) manifests:

| OS / Area | Tooling |
| :--- | :--- |
| **Fedora/Silverblue** | `rpm-ostree`, `dnf` |
| **Debian/Ubuntu** | `apt`, `nala` |
| **macOS** | `brew`, `macports` |
| **Windows** | `winget`, `scoop` |
| **Arch** | `pacman` |
| **Cross-platform** | `asdf`, `cargo`, `pwa` |

== Documentation
* link:cookbook.adoc[**Cookbook**]: Detailed recipes for all `just` commands.
* link:docs/must-spec.adoc[**must-spec**]: Technical specification for the Mustfile transitions.
* link:docs/man/[**Man Pages**]: CLI help and man documents for all custom binaries.
