From aa9c55277cb346d9cb8b3af1da64f3375fac20f9 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Sun, 22 Mar 2026 23:40:03 +0300
Subject: [PATCH] docs: document usage for Just intrumentation

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I11f818ca94867d483caf89c1753e28876a6a6964
---
 docs/README.md | 67 ++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 49 insertions(+), 18 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 69145fe..9d8a072 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -11,19 +11,41 @@ PostgreSQL (production deployments) as available database backends.
 
 ## Building
 
+This project uses [Just](https://just.systems/) as its command runner to help
+run cargo with a consistent interface. You are recommended to get it with Nix,
+using the default devshell which provides Just.
+
 ```bash
-# Build all compilable crates
+# Build everything (core crates + UI)
+$ just build
+
+# Build only core crates (cargo)
+$ just build-core
+
+# Build only the UI (uses dx - see note below)
+$ just build-ui
+```
+
+> [!IMPORTANT]
+> The Dioxus UI (`pinakes-ui`) must be built with `dx` (Dioxus CLI) to compile
+> SCSS stylesheets. Using `cargo build -p pinakes-ui` will not work correctly as
+> it skips the SCSS compilation step. This was previously "remedied" with an
+> intermediate build wrapper, which turned out to be fragile. It is highly
+> recommended that you prefer `just` to build.
+
+Manual build commands if not using Just:
+
+```bash
+# Core crates (standard cargo)
 $ cargo build -p pinakes-core -p pinakes-server -p pinakes-tui
 
-# The Dioxus UI requires GTK3 and libsoup system libraries:
+# UI (requires Dioxus CLI for SCSS compilation)
+$ dx build -p pinakes-ui
+
+# System dependencies for the UI:
 # On Debian/Ubuntu: apt install libgtk-3-dev libsoup-3.0-dev libwebkit2gtk-4.1-dev
 # On Fedora: dnf install gtk3-devel libsoup3-devel webkit2gtk4.1-devel
 # On Nix: Use the dev shell, everything is provided :)
-$ cargo build -p pinakes-ui
-
-# Alternatively, while app deps are in PATH, you may simply build the entire
-# workspace.
-$ cargo build --workspace
 ```
 
 ## Configuration
@@ -53,17 +75,20 @@ Key settings:
 
 ## Running
 
+All commands are available via Just. Run `just --list` to see all available
+recipes.
+
 ### Server
 
 To use Pinakes, you will need the server to be running. The GUI on its own will
 work, but it will not be functional without the server.
 
-```sh
-# Start the server first
-$ cargo run -p pinakes-server -- pinakes.toml
+```bash
+# Using Just
+$ just run-server
 
-# or:
-$ cargo run -p pinakes-server -- --config pinakes.toml
+# Or manually:
+$ cargo run -p pinakes-server -- pinakes.toml
 ```
 
 The server starts on the configured host:port (default `127.0.0.1:3000`). In a
@@ -77,11 +102,11 @@ terminal. While the server is running you may connect to it using the `--server`
 flag.
 
 ```bash
-# Using defaults
-$ cargo run -p pinakes-tui
+# Using Just
+$ just run-tui
 
-# or with a custom server URL:
-$ cargo run -p pinakes-tui -- --server http://localhost:3000
+# Or manually:
+$ cargo run -p pinakes-tui
 ```
 
 #### Keybindings
@@ -120,9 +145,15 @@ Pinakes features a fully fledged Desktop and Web UI powered by Dioxus. Those two
 components are meant as a GUI frontend for the Pinakes server, and are
 interchangeable in terms of usage.
 
+> [!IMPORTANT]
+> The UI must be run with `dx` (Dioxus CLI), not `cargo run`.
+
 ```bash
-# Build the UI
-$ cargo run -p pinakes-ui
+# Using Just
+$ just run-ui
+
+# Or manually with dx:
+$ dx serve -p pinakes-ui
 ```
 
 > [!TIP]