Release version 1.3.1

CHANGELOG.md

@@ -1,3 +1,8 @@
+## [1.3.1] - 2025-12-12
+
+* Updated documentation with better run and installation instructions
+
+
 ## [1.3.0] - 2025-12-12
 
 * **Minor release – Stability & CI hardening**

README.md

@@ -8,8 +8,9 @@
 [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
 [![GitHub license](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![GitHub repo size](https://img.shields.io/github/repo-size/kevinveenbirkenbach/package-manager)](https://github.com/kevinveenbirkenbach/package-manager)
+[![Mark stable commit](https://github.com/kevinveenbirkenbach/package-manager/actions/workflows/mark-stable.yml/badge.svg)](https://github.com/kevinveenbirkenbach/package-manager/actions/workflows/mark-stable.yml)
 
-**Kevin's Package Manager (PKGMGR)** is a *multi-distro* package manager and workflow orchestrator.
+[**Kevin's Package Manager (PKGMGR)**](https://s.veen.world/pkgmgr) is a *multi-distro* package manager and workflow orchestrator.
 It helps you **develop, package, release and manage projects across multiple Linux-based
 operating systems** (Arch, Debian, Ubuntu, Fedora, CentOS, …).
 
@@ -103,50 +104,75 @@ The following diagram gives a full overview of:
 
 ---
 
+Perfekt, dann hier die **noch kompaktere und korrekt differenzierte Version**, die **nur** zwischen
+**`make setup`** und **`make setup-venv`** unterscheidet und exakt deinem Verhalten entspricht.
+
+README-ready, ohne Over-Engineering.
+
+---
+
 ## Installation ⚙️
 
-### 1. Get the latest stable version
+PKGMGR can be installed using `make`.
+The setup mode defines **which runtime layers are prepared**.
 
-For a stable setup, use the **latest tagged release** (the tag pointed to by
+---
-`latest`):
+
+### Setup modes
+
+| Command             | Prepares                | Use case              |
+| ------------------- | ----------------------- | --------------------- |
+| **make setup**      | Python venv **and** Nix | Full development & CI |
+| **make setup-venv** | Python venv only        | Local user setup      |
+
+---
+
+### Install & setup
 
 ```bash
 git clone https://github.com/kevinveenbirkenbach/package-manager.git
 cd package-manager
-
-# Optional but recommended: checkout the latest stable tag
-git fetch --tags
-git checkout "$(git describe --tags --abbrev=0)"
-```
-
-### 2. Install via Make
-
-The project ships with a Makefile that encapsulates the typical installation
-flow. On most systems you only need:
-
-```bash
-# Ensure make, Python and pip are installed via your distro package manager
-# (e.g. pacman -S make python python-pip, apt install make python3-pip, ...)
-
 make install
 ```
 
-This will:
+#### Full setup (venv + Nix)
-
-* create or reuse a Python virtual environment,
-* install PKGMGR (and its Python dependencies) into that environment,
-* expose the `pkgmgr` executable on your PATH (usually via `~/.local/bin`),
-* prepare Nix-based integration where available so PKGMGR can build and manage
-  packages distribution-independently.
-
-For development use, you can also run:
 
 ```bash
 make setup
 ```
 
-which prepares the environment and leaves you with a fully wired development
+Use this for CI, servers, containers and full development workflows.
-workspace (including Nix, tests and scripts).
+
+#### Venv-only setup
+
+```bash
+make setup-venv
+source ~/.venvs/pkgmgr/bin/activate
+```
+
+Use this if you want PKGMGR isolated without Nix integration.
+
+---
+
+## Run without installation (Nix)
+
+Run PKGMGR directly via Nix Flakes.
+
+```bash
+nix run github:kevinveenbirkenbach/package-manager#pkgmgr -- --help
+```
+
+Example:
+
+```bash
+nix run github:kevinveenbirkenbach/package-manager#pkgmgr -- version pkgmgr
+```
+
+Notes:
+
+* full flake URL required
+* `--` separates Nix and PKGMGR arguments
+* can be used alongside any setup mode
 
 ---
 
@@ -158,21 +184,9 @@ After installation, the main entry point is:
 pkgmgr --help
 ```
 
-This prints a list of all available subcommands, for example:
+This prints a list of all available subcommands.
-
-* `pkgmgr list --all` – show all repositories in the config
-* `pkgmgr update --all --clone-mode https` – update every repository
-* `pkgmgr release patch --preview` – simulate a patch release
-* `pkgmgr version --all` – show version information for all repositories
-* `pkgmgr mirror setup --preview --all` – prepare Git mirrors (no changes in preview)
-* `pkgmgr make install --preview pkgmgr` – preview make install for the pkgmgr repo
-
 The help for each command is available via:
 
-```bash
-pkgmgr <command> --help
-```
-
 ---
 
 ## License 📄

flake.nix

@@ -36,7 +36,7 @@
         rec {
           pkgmgr = pyPkgs.buildPythonApplication {
             pname   = "package-manager";
-            version = "1.3.0";
+            version = "1.3.1";
 
             # Use the git repo as source
             src = ./.;

pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "package-manager"
-version = "1.3.0"
+version = "1.3.1"
 description = "Kevin's package-manager tool (pkgmgr)"
 readme = "README.md"
 requires-python = ">=3.9"

src/pkgmgr/cli/__init__.py

@@ -19,7 +19,7 @@ USER_CONFIG_PATH = os.path.expanduser("~/.config/pkgmgr/config.yaml")
 DESCRIPTION_TEXT = """\
 \033[1;32mPackage Manager 🤖📦\033[0m
 \033[3mKevin's multi-distro package and workflow manager.\033[0m
-  \033[1;34mKevin Veen-Birkenbach\033[0m – \033[4mhttps://www.veen.world/\033[0m
+\033[1;34mKevin Veen-Birkenbach\033[0m – \033[4mhttps://s.veen.world/pkgmgr\033[0m
 
 Built in \033[1;33mPython\033[0m on top of \033[1;33mNix flakes\033[0m to manage many
 repositories and packaging formats (pyproject.toml, flake.nix,