update: new CLI

.github/CONTRIBUTING.md

@@ -168,6 +168,15 @@ uv run python main.py config channel stable   # or: beta
 uv run python main.py update
 ```
 
+### Running the tests
+
+Unit tests live in `tests/`, mirroring `core/`, `services/` and `engines/`. They call
+the functions directly: no Docker, no network, no built binary.
+
+```bash
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
 ---
 
 ## Reporting Issues
@@ -237,4 +246,16 @@ If you encounter a bug or have a suggestion for improvement, follow these steps:
 
 Thank you for contributing! 🙌
 
----
+---
+## Releasing
+
+Releases are cut from GitHub Actions, never from a local machine.
+
+1. Open **Actions → Bump version → Run workflow**.
+2. Pick the branch (`main` for stable, any branch for a release candidate).
+3. Enter the version without a leading `v` (`26.09.0` for stable, `26.09.0rc1` for a candidate) and the matching channel.
+4. The workflow commits `chore(release): <version>`, creates the tag and pushes. The tag triggers the build, the GitHub release, the Discord notification and the template upload.
+
+Stable versions must match `X.Y.Z` and can only be cut from `main`.
+
+The workflow pushes with the `RELEASE_TOKEN` repository secret (a fine-grained PAT with *Contents: read and write*). A tag pushed with the default `GITHUB_TOKEN` would not trigger the release workflows.

.github/actions/build/action.yml

@@ -0,0 +1,45 @@
+name: Build the CLI binary
+description: >-
+  Build the standalone binary from portabase.spec and check that it can read
+  its own bundled metadata. A binary that reports no version cannot resolve
+  its templates either, so it is rejected here rather than shipped.
+
+inputs:
+  name:
+    description: Binary name, without extension.
+    required: false
+    default: portabase
+
+outputs:
+  path:
+    description: Path to the built binary.
+    value: ${{ steps.build.outputs.path }}
+
+runs:
+  using: composite
+  steps:
+    - id: build
+      shell: bash
+      env:
+        PORTABASE_BINARY_NAME: ${{ inputs.name }}
+      run: |
+        set -euo pipefail
+        rm -rf build dist
+        uv run pyinstaller portabase.spec
+
+        case "$(uname -s)" in
+          MINGW* | MSYS* | CYGWIN*) EXT=".exe" ;;
+          *) EXT="" ;;
+        esac
+        BINARY="dist/${PORTABASE_BINARY_NAME}${EXT}"
+        test -f "$BINARY"
+        echo "path=$BINARY" >> "$GITHUB_OUTPUT"
+
+    - shell: bash
+      run: |
+        set -euo pipefail
+        VERSION=$("${{ steps.build.outputs.path }}" --version | head -1)
+        echo "$VERSION"
+        case "$VERSION" in
+          *unknown*) echo "::error::binary cannot read its bundled version"; exit 1 ;;
+        esac

.github/actions/setup/action.yml

@@ -0,0 +1,13 @@
+name: Set up Python toolchain
+description: Install uv and sync the locked environment, including dev dependencies.
+
+runs:
+  using: composite
+  steps:
+    - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      shell: bash
+      run: uv sync --frozen --all-groups

.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+    commit-message:
+      prefix: "ci"
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]
+    commit-message:
+      prefix: "build"

.github/workflows/build.yml

@@ -0,0 +1,62 @@
+name: Build binaries
+
+on:
+  workflow_call:
+
+permissions: {}
+
+jobs:
+  build:
+    name: ${{ matrix.os }}-${{ matrix.arch }}
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: linux
+            arch: amd64
+            runner: ubuntu-latest
+          - os: linux
+            arch: arm64
+            runner: ubuntu-24.04-arm
+          - os: macos
+            arch: arm64
+            runner: macos-latest
+          - os: macos
+            arch: amd64
+            runner: macos-15-intel
+          - os: windows
+            arch: amd64
+            runner: windows-latest
+            ext: .exe
+    defaults:
+      run:
+        shell: bash
+    env:
+      NAME: portabase_${{ matrix.os }}_${{ matrix.arch }}
+      BINARY: portabase_${{ matrix.os }}_${{ matrix.arch }}${{ matrix.ext }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: ./.github/actions/setup
+
+      - name: Build
+        id: build
+        uses: ./.github/actions/build
+        with:
+          name: ${{ env.NAME }}
+
+      - name: Attest provenance
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2
+        with:
+          subject-path: ${{ steps.build.outputs.path }}
+
+      - name: Upload
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: ${{ env.BINARY }}
+          path: ${{ steps.build.outputs.path }}

.github/workflows/bump.yml

@@ -0,0 +1,85 @@
+name: Bump version
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version (e.g. 26.09.0 or 26.09.0rc1). No leading v."
+        required: true
+        type: string
+      channel:
+        description: "stable: only from main. rc: any branch."
+        required: true
+        type: choice
+        options: [stable, rc]
+        default: rc
+
+permissions: {}
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Validate version against channel
+        env:
+          VERSION: ${{ inputs.version }}
+          CHANNEL: ${{ inputs.channel }}
+          REF: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          if [[ "$VERSION" == v* ]]; then
+            echo "::error::Version must not start with 'v'"; exit 1
+          fi
+          if [[ "$CHANNEL" == "stable" ]]; then
+            if [[ "$REF" != "main" ]]; then
+              echo "::error::stable releases are only allowed from main (got $REF)"; exit 1
+            fi
+            if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+              echo "::error::stable version must match X.Y.Z"; exit 1
+            fi
+          else
+            if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+([-.]?(rc|alpha|beta|a|b)[0-9]*(\.[0-9]+)?)$ ]]; then
+              echo "::error::rc version must match X.Y.Z(rc|a|b|alpha|beta)N"; exit 1
+            fi
+          fi
+          if git rev-parse "$VERSION" >/dev/null 2>&1; then
+            echo "::error::Tag $VERSION already exists"; exit 1
+          fi
+
+      - name: Update version files
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+          DATE=$(date -u +%F)
+          sed -i "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
+          if [ -f CITATION.cff ]; then
+            sed -i "s/^version: .*/version: $VERSION/" CITATION.cff
+            sed -i "s/^date-released: .*/date-released: \"$DATE\"/" CITATION.cff
+          fi
+          git diff --stat
+
+      - name: Commit, tag, push
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml CITATION.cff
+          if git diff --cached --quiet; then
+            echo "No version change to commit"
+          else
+            git commit -m "chore(release): $VERSION"
+          fi
+          git tag -a "$VERSION" -m "Release $VERSION"
+          git push origin HEAD
+          git push origin "$VERSION"

.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions: {}
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: ${{ matrix.name }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: lint
+            run: uv run ruff check . --output-format=github
+          - name: format
+            run: uv run ruff format --check .
+          - name: types
+            run: uv run mypy
+          - name: tests
+            run: uv run pytest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: ./.github/actions/setup
+      - run: ${{ matrix.run }}
+
+  binary:
+    name: binary
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: ./.github/actions/setup
+
+      - name: Build
+        id: build
+        uses: ./.github/actions/build