Merge https://git.allucanget.biz/allucanget/calminer into develop

Reviewed-on: #12

.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+
+Dockerfile text eol=lf

.gitea/workflows/ci-build.yml

@@ -0,0 +1,232 @@
+name: CI - Build
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  build:
+    outputs:
+      allow_push: ${{ steps.meta.outputs.allow_push }}
+      ref_name: ${{ steps.meta.outputs.ref_name }}
+      event_name: ${{ steps.meta.outputs.event_name }}
+      sha: ${{ steps.meta.outputs.sha }}
+    runs-on: ubuntu-latest
+    env:
+      DEFAULT_BRANCH: main
+      REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
+      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
+      REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+      REGISTRY_CONTAINER_NAME: calminer
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Collect workflow metadata
+        id: meta
+        shell: bash
+        env:
+          DEFAULT_BRANCH: ${{ env.DEFAULT_BRANCH }}
+        run: |
+          git_ref="${GITEA_REF:-${GITHUB_REF:-}}"
+          ref_name="${GITEA_REF_NAME:-${GITHUB_REF_NAME:-}}"
+          if [ -z "$ref_name" ] && [ -n "$git_ref" ]; then
+            ref_name="${git_ref##*/}"
+          fi
+          event_name="${GITEA_EVENT_NAME:-${GITHUB_EVENT_NAME:-}}"
+          sha="${GITEA_SHA:-${GITHUB_SHA:-}}"
+          if [ -z "$sha" ]; then
+            sha="$(git rev-parse HEAD)"
+          fi
+
+          if [ "$ref_name" = "${DEFAULT_BRANCH:-main}" ] && [ "$event_name" != "pull_request" ]; then
+            echo "allow_push=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "allow_push=false" >> "$GITHUB_OUTPUT"
+          fi
+
+          echo "ref_name=$ref_name" >> "$GITHUB_OUTPUT"
+          echo "event_name=$event_name" >> "$GITHUB_OUTPUT"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+
+      - name: Validate registry configuration
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ -z "${REGISTRY_URL}" ]; then
+            echo "::error::REGISTRY_URL secret not configured. Configure it with your Gitea container registry host." >&2
+            exit 1
+          fi
+          server_url="${GITEA_SERVER_URL:-${GITHUB_SERVER_URL:-}}"
+          server_host="${server_url#http://}"
+          server_host="${server_host#https://}"
+          server_host="${server_host%%/*}"
+          server_host="${server_host%%:*}"
+          registry_host="${REGISTRY_URL#http://}"
+          registry_host="${registry_host#https://}"
+          registry_host="${registry_host%%/*}"
+          registry_host="${registry_host%%:*}"
+          if [ -n "${server_host}" ] && ! printf '%s' "${registry_host}" | grep -qi "${server_host}"; then
+            echo "::warning::REGISTRY_URL (${REGISTRY_URL}) does not match current Gitea host (${server_host}). Ensure this registry endpoint is managed by Gitea." >&2
+          fi
+          registry_repository="${registry_host}/allucanget/${REGISTRY_CONTAINER_NAME}"
+          echo "REGISTRY_HOST=${registry_host}" >> "$GITHUB_ENV"
+          echo "REGISTRY_REPOSITORY=${registry_repository}" >> "$GITHUB_ENV"
+
+      - name: Set up QEMU and Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to gitea registry
+        if: ${{ steps.meta.outputs.allow_push == 'true' }}
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY_HOST }}
+          username: ${{ env.REGISTRY_USERNAME }}
+          password: ${{ env.REGISTRY_PASSWORD }}
+
+      - name: Build image
+        id: build-image
+        env:
+          REGISTRY_REPOSITORY: ${{ env.REGISTRY_REPOSITORY }}
+          REGISTRY_CONTAINER_NAME: ${{ env.REGISTRY_CONTAINER_NAME }}
+          SHA_TAG: ${{ steps.meta.outputs.sha }}
+          PUSH_IMAGE: ${{ steps.meta.outputs.allow_push == 'true' && env.REGISTRY_HOST != '' && env.REGISTRY_USERNAME != '' && env.REGISTRY_PASSWORD != '' }}
+        run: |
+          set -eo pipefail
+          LOG_FILE=build.log
+          if [ "${PUSH_IMAGE}" = "true" ]; then
+            docker buildx build \
+              --load \
+              --tag "${REGISTRY_REPOSITORY}:latest" \
+              --tag "${REGISTRY_REPOSITORY}:${SHA_TAG}" \
+              --file Dockerfile \
+              . 2>&1 | tee "${LOG_FILE}"
+          else
+            docker buildx build \
+              --load \
+              --tag "${REGISTRY_CONTAINER_NAME}:ci" \
+              --file Dockerfile \
+              . 2>&1 | tee "${LOG_FILE}"
+          fi
+
+      - name: Push image
+        if: ${{ steps.meta.outputs.allow_push == 'true' }}
+        env:
+          REGISTRY_REPOSITORY: ${{ env.REGISTRY_REPOSITORY }}
+          SHA_TAG: ${{ steps.meta.outputs.sha }}
+        run: |
+          set -euo pipefail
+          if [ -z "${REGISTRY_REPOSITORY}" ]; then
+            echo "::error::REGISTRY_REPOSITORY not defined; cannot push image" >&2
+            exit 1
+          fi
+          docker push "${REGISTRY_REPOSITORY}:${SHA_TAG}"
+          docker push "${REGISTRY_REPOSITORY}:latest"
+
+      - name: Upload docker build logs
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docker-build-logs
+          path: build.log
+
+  deploy:
+    needs: build
+    if: needs.build.outputs.allow_push == 'true'
+    runs-on: ubuntu-latest
+    env:
+      REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
+      REGISTRY_CONTAINER_NAME: calminer
+      KUBE_CONFIG: ${{ secrets.KUBE_CONFIG }}
+      STAGING_KUBE_CONFIG: ${{ secrets.STAGING_KUBE_CONFIG }}
+      PROD_KUBE_CONFIG: ${{ secrets.PROD_KUBE_CONFIG }}
+      K8S_DEPLOY_ENABLED: ${{ secrets.K8S_DEPLOY_ENABLED }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Resolve registry repository
+        run: |
+          set -euo pipefail
+          if [ -z "${REGISTRY_URL}" ]; then
+            echo "::error::REGISTRY_URL secret not configured. Configure it with your Gitea container registry host." >&2
+            exit 1
+          fi
+          registry_host="${REGISTRY_URL#http://}"
+          registry_host="${registry_host#https://}"
+          registry_host="${registry_host%%/*}"
+          registry_host="${registry_host%%:*}"
+          registry_repository="${registry_host}/allucanget/${REGISTRY_CONTAINER_NAME}"
+          echo "REGISTRY_HOST=${registry_host}" >> "$GITHUB_ENV"
+          echo "REGISTRY_REPOSITORY=${registry_repository}" >> "$GITHUB_ENV"
+
+      - name: Report Kubernetes deployment toggle
+        run: |
+          set -euo pipefail
+          enabled="${K8S_DEPLOY_ENABLED:-}" 
+          if [ "${enabled}" = "true" ]; then
+            echo "Kubernetes deployment is enabled for this run."
+          else
+            echo "::notice::Kubernetes deployment steps are disabled (set secrets.K8S_DEPLOY_ENABLED to 'true' to enable)."
+          fi
+
+      - name: Capture commit metadata
+        id: commit_meta
+        run: |
+          set -euo pipefail
+          message="$(git log -1 --pretty=%B | tr '\n' ' ')"
+          echo "message=$message" >> "$GITHUB_OUTPUT"
+
+      - name: Set up kubectl for staging
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy staging]')
+        uses: azure/k8s-set-context@v3
+        with:
+          method: kubeconfig
+          kubeconfig: ${{ env.STAGING_KUBE_CONFIG }}
+
+      - name: Set up kubectl for production
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy production]')
+        uses: azure/k8s-set-context@v3
+        with:
+          method: kubeconfig
+          kubeconfig: ${{ env.PROD_KUBE_CONFIG }}
+
+      - name: Deploy to staging
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy staging]')
+        run: |
+          kubectl set image deployment/calminer-app calminer=${REGISTRY_REPOSITORY}:latest
+          kubectl apply -f k8s/configmap.yaml
+          kubectl apply -f k8s/secret.yaml
+          kubectl rollout status deployment/calminer-app
+
+      - name: Collect staging deployment logs
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy staging]')
+        run: |
+          mkdir -p logs/deployment/staging
+          kubectl get pods -o wide > logs/deployment/staging/pods.txt
+          kubectl get deployment calminer-app -o yaml > logs/deployment/staging/deployment.yaml
+          kubectl logs deployment/calminer-app --all-containers=true --tail=500 > logs/deployment/staging/calminer-app.log
+
+      - name: Deploy to production
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy production]')
+        run: |
+          kubectl set image deployment/calminer-app calminer=${REGISTRY_REPOSITORY}:latest
+          kubectl apply -f k8s/configmap.yaml
+          kubectl apply -f k8s/secret.yaml
+          kubectl rollout status deployment/calminer-app
+
+      - name: Collect production deployment logs
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy production]')
+        run: |
+          mkdir -p logs/deployment/production
+          kubectl get pods -o wide > logs/deployment/production/pods.txt
+          kubectl get deployment calminer-app -o yaml > logs/deployment/production/deployment.yaml
+          kubectl logs deployment/calminer-app --all-containers=true --tail=500 > logs/deployment/production/calminer-app.log
+
+      - name: Upload deployment logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: deployment-logs
+          path: logs/deployment
+          if-no-files-found: ignore

.gitea/workflows/ci-lint.yml

@@ -0,0 +1,44 @@
+name: CI - Lint
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      APT_CACHER_NG: http://192.168.88.14:3142
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Configure apt proxy
+        run: |
+          if [ -n "${APT_CACHER_NG}" ]; then
+            echo "Acquire::http::Proxy \"${APT_CACHER_NG}\";" | tee /etc/apt/apt.conf.d/01apt-cacher-ng
+          fi
+
+      - name: Install system packages
+        run: |
+          apt-get update
+          apt-get install -y build-essential libpq-dev
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r requirements-test.txt
+
+      - name: Run Ruff
+        run: ruff check .
+
+      - name: Run Black
+        run: black --check .
+
+      - name: Run Bandit
+        run: bandit -c pyproject.toml -r tests

.gitea/workflows/ci-test.yml

@@ -0,0 +1,73 @@
+name: CI - Test
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      APT_CACHER_NG: http://192.168.88.14:3142
+      DB_DRIVER: postgresql+psycopg2
+      DB_HOST: 192.168.88.35
+      DB_NAME: calminer_test
+      DB_USER: calminer
+      DB_PASSWORD: calminer_password
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: ${{ env.DB_USER }}
+          POSTGRES_PASSWORD: ${{ env.DB_PASSWORD }}
+          POSTGRES_DB: ${{ env.DB_NAME }}
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Configure apt proxy
+        run: |
+          if [ -n "${APT_CACHER_NG}" ]; then
+            echo "Acquire::http::Proxy \"${APT_CACHER_NG}\";" | tee /etc/apt/apt.conf.d/01apt-cacher-ng
+          fi
+
+      - name: Install system packages
+        run: |
+          apt-get update
+          apt-get install -y build-essential libpq-dev
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r requirements-test.txt
+
+      - name: Run tests
+        env:
+          DATABASE_DRIVER: ${{ env.DB_DRIVER }}
+          DATABASE_HOST: postgres
+          DATABASE_PORT: 5432
+          DATABASE_USER: ${{ env.DB_USER }}
+          DATABASE_PASSWORD: ${{ env.DB_PASSWORD }}
+          DATABASE_NAME: ${{ env.DB_NAME }}
+        run: |
+          pytest --cov=. --cov-report=term-missing --cov-report=xml --cov-fail-under=80 --junitxml=pytest-report.xml
+
+      - name: Upload test artifacts
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: test-artifacts
+          path: |
+            coverage.xml
+            pytest-report.xml

.gitea/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+      - v2
+  pull_request:
+    branches:
+      - main
+      - develop
+  workflow_dispatch:
+
+jobs:
+  lint:
+    uses: ./.gitea/workflows/ci-lint.yml
+    secrets: inherit
+
+  test:
+    needs: lint
+    uses: ./.gitea/workflows/ci-test.yml
+    secrets: inherit
+
+  build:
+    needs:
+      - lint
+      - test
+    uses: ./.gitea/workflows/ci-build.yml
+    secrets: inherit

.gitea/workflows/ci_fast.yml

@@ -1,212 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main, develop, v2]
-  pull_request:
-    branches: [main, develop]
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    env:
-      APT_CACHER_NG: http://192.168.88.14:3142
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.12"
-
-      # - name: Cache pip dependencies
-      #   uses: actions/cache@v4
-      #   with:
-      #     path: /root/.cache/pip
-      #     key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt', 'requirements-test.txt', 'pyproject.toml') }}
-      #     restore-keys: |
-      #       ${{ runner.os }}-pip-
-
-      - name: Configure apt proxy
-        run: |
-          if [ -n \"${APT_CACHER_NG}\" ]; then
-            echo "Acquire::http::Proxy \"${APT_CACHER_NG}\";" | tee /etc/apt/apt.conf.d/01apt-cacher-ng
-          fi
-
-      - name: Install system packages
-        run: |
-          apt-get update
-          apt-get install -y build-essential libpq-dev
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          pip install -r requirements-test.txt
-
-      - name: Run Ruff
-        run: ruff check .
-
-      - name: Run Black
-        run: black --check .
-
-      - name: Run bandit
-        run: bandit -c pyproject.toml -r tests
-
-  test:
-    runs-on: ubuntu-latest
-    needs: lint
-    env:
-      APT_CACHER_NG: http://192.168.88.14:3142
-      DB_DRIVER: postgresql+psycopg2
-      DB_HOST: 192.168.88.35
-      DB_NAME: calminer_test
-      DB_USER: calminer
-      DB_PASSWORD: calminer_password
-    services:
-      postgres:
-        image: postgres:17
-        env:
-          POSTGRES_USER: ${{ env.DB_USER }}
-          POSTGRES_PASSWORD: ${{ env.DB_PASSWORD }}
-          POSTGRES_DB: ${{ env.DB_NAME }}
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.12"
-
-      - name: Get pip cache dir
-        id: pip-cache
-        run: |
-          echo \"path=$(pip cache dir)\" >> $GITEA_OUTPUT
-          echo \"Pip cache dir: $(pip cache dir)\"
-
-      # - name: Cache pip dependencies
-      #   uses: actions/cache@v4
-      #   with:
-      #     path: /root/.cache/pip
-      #     key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt', 'requirements-test.txt', 'pyproject.toml') }}
-      #     restore-keys: |
-      #       ${{ runner.os }}-pip-
-
-      - name: Configure apt proxy
-        run: |
-          if [ -n \"${APT_CACHER_NG}\" ]; then
-            echo "Acquire::http::Proxy \"${APT_CACHER_NG}\";" | tee /etc/apt/apt.conf.d/01apt-cacher-ng
-          fi
-
-      - name: Install system packages
-        run: |
-          apt-get update
-          apt-get install -y build-essential libpq-dev
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          pip install -r requirements-test.txt
-
-      - name: Run tests
-        env:
-          DATABASE_DRIVER: ${{ env.DB_DRIVER }}
-          DATABASE_HOST: postgres
-          DATABASE_PORT: 5432
-          DATABASE_USER: ${{ env.DB_USER }}
-          DATABASE_PASSWORD: ${{ env.DB_PASSWORD }}
-          DATABASE_NAME: ${{ env.DB_NAME }}
-        run: |
-          pytest --cov=. --cov-report=term-missing --cov-report=xml --junitxml=pytest-report.xml
-
-      - name: Upload test artifacts
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: test-artifacts
-          path: |
-            coverage.xml
-            pytest-report.xml
-
-  build:
-    runs-on: ubuntu-latest
-    needs:
-      - lint
-      - test
-    env:
-      DEFAULT_BRANCH: main
-      REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
-      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
-      REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
-      REGISTRY_CONTAINER_NAME: calminer
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Collect workflow metadata
-        id: meta
-        shell: bash
-        run: |
-          ref_name=\"${GITHUB_REF_NAME:-${GITHUB_REF##*/}}\"
-          event_name=\"${GITHUB_EVENT_NAME:-}\"
-          sha=\"${GITHUB_SHA:-}\"
-
-          if [ \"$ref_name\" = \"${DEFAULT_BRANCH:-main}\" ]; then
-            echo \"on_default=true\" >> \"$GITHUB_OUTPUT\"
-          else
-            echo \"on_default=false\" >> \"$GITHUB_OUTPUT\"
-          fi
-
-          echo \"ref_name=$ref_name\" >> \"$GITHUB_OUTPUT\"
-          echo \"event_name=$event_name\" >> \"$GITHUB_OUTPUT\"
-          echo \"sha=$sha\" >> \"$GITHUB_OUTPUT\"
-
-      - name: Set up QEMU and Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to gitea registry
-        if: ${{ steps.meta.outputs.on_default == 'true' }}
-        uses: docker/login-action@v3
-        continue-on-error: true
-        with:
-          registry: ${{ env.REGISTRY_URL }}
-          username: ${{ env.REGISTRY_USERNAME }}
-          password: ${{ env.REGISTRY_PASSWORD }}
-
-      - name: Build image
-        id: build-image
-        env:
-          REGISTRY_URL: ${{ env.REGISTRY_URL }}
-          REGISTRY_CONTAINER_NAME: ${{ env.REGISTRY_CONTAINER_NAME }}
-          SHA_TAG: ${{ steps.meta.outputs.sha }}
-          PUSH_IMAGE: ${{ steps.meta.outputs.on_default == 'true' && steps.meta.outputs.event_name != 'pull_request' && env.REGISTRY_URL != '' && env.REGISTRY_USERNAME != '' && env.REGISTRY_PASSWORD != '' }}
-        run: |
-          set -eo pipefail
-          LOG_FILE=build.log
-          if [ \"${PUSH_IMAGE}\" = \"true\" ]; then
-            docker buildx build \
-              --push \
-              --tag \"${REGISTRY_URL}/allucanget/${REGISTRY_CONTAINER_NAME}:latest\" \
-              --tag \"${REGISTRY_URL}/allucanget/${REGISTRY_CONTAINER_NAME}:${SHA_TAG}\" \
-              --file Dockerfile \
-              . 2>&1 | tee \"${LOG_FILE}\"
-          else
-            docker buildx build \
-              --load \
-              --tag \"${REGISTRY_CONTAINER_NAME}:ci\" \
-              --file Dockerfile \
-              . 2>&1 | tee \"${LOG_FILE}\"
-          fi
-
-      - name: Upload docker build logs
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: docker-build-logs
-          path: build.log

.gitea/workflows/cicache.yml

@@ -1,298 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main, develop, v2]
-  pull_request:
-    branches: [main, develop]
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    env:
-      APT_CACHER_NG: http://192.168.88.14:3142
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.12"
-
-      # - name: Get pip cache dir
-      #   id: pip-cache
-      #   run: |
-      #     echo "path=$(pip cache dir)" >> $GITEA_OUTPUT
-      #     echo "Pip cache dir: $(pip cache dir)"
-
-      # - name: Cache pip dependencies
-      #   uses: actions/cache@v4
-      #   with:
-      #     path: ${{ steps.pip-cache.outputs.path }}
-      #     key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt', 'requirements-test.txt', 'pyproject.toml') }}
-      #     restore-keys: |
-      #       ${{ runner.os }}-pip-
-
-      - name: Configure apt proxy
-        run: |
-          if [ -n "${APT_CACHER_NG}" ]; then
-            echo "Acquire::http::Proxy \"${APT_CACHER_NG}\";" | tee /etc/apt/apt.conf.d/01apt-cacher-ng
-          fi
-
-      - name: Install system packages
-        run: |
-          apt-get update
-          apt-get install -y build-essential libpq-dev
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          pip install -r requirements-test.txt
-
-      - name: Run Ruff
-        run: ruff check .
-
-      - name: Run Black
-        run: black --check .
-
-      - name: Run Bandit
-        run: bandit -c pyproject.toml -r tests
-
-  test:
-    runs-on: ubuntu-latest
-    needs: lint
-    env:
-      APT_CACHER_NG: http://192.168.88.14:3142
-      DB_DRIVER: postgresql+psycopg2
-      DB_HOST: 192.168.88.35
-      DB_NAME: calminer_test
-      DB_USER: calminer
-      DB_PASSWORD: calminer_password
-    services:
-      postgres:
-        image: postgres:17
-        env:
-          POSTGRES_USER: ${{ env.DB_USER }}
-          POSTGRES_PASSWORD: ${{ env.DB_PASSWORD }}
-          POSTGRES_DB: ${{ env.DB_NAME }}
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.12"
-
-      # - name: Get pip cache dir
-      #   id: pip-cache
-      #   run: |
-      #     echo "path=$(pip cache dir)" >> $GITEA_OUTPUT
-      #     echo "Pip cache dir: $(pip cache dir)"
-
-      # - name: Cache pip dependencies
-      #   uses: actions/cache@v4
-      #   with:
-      #     path: ${{ steps.pip-cache.outputs.path }}
-      #     key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt', 'requirements-test.txt', 'pyproject.toml') }}
-      #     restore-keys: |
-      #       ${{ runner.os }}-pip-
-
-      - name: Configure apt proxy
-        run: |
-          if [ -n "${APT_CACHER_NG}" ]; then
-            echo "Acquire::http::Proxy \"${APT_CACHER_NG}\";" | tee /etc/apt/apt.conf.d/01apt-cacher-ng
-          fi
-
-      - name: Install system packages
-        run: |
-          apt-get update
-          apt-get install -y build-essential libpq-dev
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          pip install -r requirements-test.txt
-
-      - name: Install Playwright system dependencies
-        run: playwright install-deps
-
-      - name: Install Playwright browsers
-        run: playwright install
-
-      - name: Run tests
-        env:
-          DATABASE_DRIVER: ${{ env.DB_DRIVER }}
-          DATABASE_HOST: postgres
-          DATABASE_PORT: 5432
-          DATABASE_USER: ${{ env.DB_USER }}
-          DATABASE_PASSWORD: ${{ env.DB_PASSWORD }}
-          DATABASE_NAME: ${{ env.DB_NAME }}
-        run: |
-          pytest --cov=. --cov-report=term-missing --cov-report=xml --cov-fail-under=80 --junitxml=pytest-report.xml
-
-      - name: Upload test artifacts
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: test-artifacts
-          path: |
-            coverage.xml
-            pytest-report.xml
-
-  build:
-    runs-on: ubuntu-latest
-    needs:
-      - lint
-      - test
-    env:
-      DEFAULT_BRANCH: main
-      REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
-      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
-      REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
-      REGISTRY_CONTAINER_NAME: calminer
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Collect workflow metadata
-        id: meta
-        shell: bash
-        run: |
-          ref_name="${GITHUB_REF_NAME:-${GITHUB_REF##*/}}"
-          event_name="${GITHUB_EVENT_NAME:-}"
-          sha="${GITHUB_SHA:-}"
-
-          if [ "$ref_name" = "${DEFAULT_BRANCH:-main}" ]; then
-            echo "on_default=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "on_default=false" >> "$GITHUB_OUTPUT"
-          fi
-
-          echo "ref_name=$ref_name" >> "$GITHUB_OUTPUT"
-          echo "event_name=$event_name" >> "$GITHUB_OUTPUT"
-          echo "sha=$sha" >> "$GITHUB_OUTPUT"
-
-      - name: Set up QEMU and Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to gitea registry
-        if: ${{ steps.meta.outputs.on_default == 'true' }}
-        uses: docker/login-action@v3
-        continue-on-error: true
-        with:
-          registry: ${{ env.REGISTRY_URL }}
-          username: ${{ env.REGISTRY_USERNAME }}
-          password: ${{ env.REGISTRY_PASSWORD }}
-
-      - name: Build image
-        id: build-image
-        env:
-          REGISTRY_URL: ${{ env.REGISTRY_URL }}
-          REGISTRY_CONTAINER_NAME: ${{ env.REGISTRY_CONTAINER_NAME }}
-          SHA_TAG: ${{ steps.meta.outputs.sha }}
-          PUSH_IMAGE: ${{ steps.meta.outputs.on_default == 'true' && steps.meta.outputs.event_name != 'pull_request' && env.REGISTRY_URL != '' && env.REGISTRY_USERNAME != '' && env.REGISTRY_PASSWORD != '' }}
-        run: |
-          set -eo pipefail
-          LOG_FILE=build.log
-          if [ "${PUSH_IMAGE}" = "true" ]; then
-            docker buildx build \
-              --push \
-              --tag "${REGISTRY_URL}/allucanget/${REGISTRY_CONTAINER_NAME}:latest" \
-              --tag "${REGISTRY_URL}/allucanget/${REGISTRY_CONTAINER_NAME}:${SHA_TAG}" \
-              --file Dockerfile \
-              . 2>&1 | tee "${LOG_FILE}"
-          else
-            docker buildx build \
-              --load \
-              --tag "${REGISTRY_CONTAINER_NAME}:ci" \
-              --file Dockerfile \
-              . 2>&1 | tee "${LOG_FILE}"
-          fi
-
-      - name: Upload docker build logs
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: docker-build-logs
-          path: build.log
-
-  deploy:
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
-    env:
-      REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
-      REGISTRY_CONTAINER_NAME: calminer
-      KUBE_CONFIG: ${{ secrets.KUBE_CONFIG }}
-      STAGING_KUBE_CONFIG: ${{ secrets.STAGING_KUBE_CONFIG }}
-      PROD_KUBE_CONFIG: ${{ secrets.PROD_KUBE_CONFIG }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up kubectl for staging
-        if: github.ref == 'refs/heads/main' && contains(github.event.head_commit.message, '[deploy staging]')
-        uses: azure/k8s-set-context@v3
-        with:
-          method: kubeconfig
-          kubeconfig: ${{ env.STAGING_KUBE_CONFIG }}
-
-      - name: Set up kubectl for production
-        if: github.ref == 'refs/heads/main' && contains(github.event.head_commit.message, '[deploy production]')
-        uses: azure/k8s-set-context@v3
-        with:
-          method: kubeconfig
-          kubeconfig: ${{ env.PROD_KUBE_CONFIG }}
-
-      - name: Deploy to staging
-        if: github.ref == 'refs/heads/main' && contains(github.event.head_commit.message, '[deploy staging]')
-        run: |
-          # Update image in deployment
-          kubectl set image deployment/calminer-app calminer=${REGISTRY_URL}/allucanget/${REGISTRY_CONTAINER_NAME}:latest
-          # Apply any config changes
-          kubectl apply -f k8s/configmap.yaml
-          kubectl apply -f k8s/secret.yaml
-          # Wait for rollout
-          kubectl rollout status deployment/calminer-app
-
-      - name: Collect staging deployment logs
-        if: github.ref == 'refs/heads/main' && contains(github.event.head_commit.message, '[deploy staging]')
-        run: |
-          mkdir -p logs/deployment/staging
-          kubectl get pods -o wide > logs/deployment/staging/pods.txt
-          kubectl get deployment calminer-app -o yaml > logs/deployment/staging/deployment.yaml
-          kubectl logs deployment/calminer-app --all-containers=true --tail=500 > logs/deployment/staging/calminer-app.log
-
-      - name: Deploy to production
-        if: github.ref == 'refs/heads/main' && contains(github.event.head_commit.message, '[deploy production]')
-        run: |
-          # Update image in deployment
-          kubectl set image deployment/calminer-app calminer=${REGISTRY_URL}/allucanget/${REGISTRY_CONTAINER_NAME}:latest
-          # Apply any config changes
-          kubectl apply -f k8s/configmap.yaml
-          kubectl apply -f k8s/secret.yaml
-          # Wait for rollout
-          kubectl rollout status deployment/calminer-app
-
-      - name: Collect production deployment logs
-        if: github.ref == 'refs/heads/main' && contains(github.event.head_commit.message, '[deploy production]')
-        run: |
-          mkdir -p logs/deployment/production
-          kubectl get pods -o wide > logs/deployment/production/pods.txt
-          kubectl get deployment calminer-app -o yaml > logs/deployment/production/deployment.yaml
-          kubectl logs deployment/calminer-app --all-containers=true --tail=500 > logs/deployment/production/calminer-app.log
-
-      - name: Upload deployment logs
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: deployment-logs
-          path: logs/deployment
-          if-no-files-found: ignore

.gitea/workflows/deploy-coolify.yml

@@ -0,0 +1,105 @@
+name: Deploy - Coolify
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      COOLIFY_BASE_URL: ${{ secrets.COOLIFY_BASE_URL }}
+      COOLIFY_API_TOKEN: ${{ secrets.COOLIFY_API_TOKEN }}
+      COOLIFY_APPLICATION_ID: ${{ secrets.COOLIFY_APPLICATION_ID }}
+      COOLIFY_DEPLOY_ENV: ${{ secrets.COOLIFY_DEPLOY_ENV }}
+      DOCKER_COMPOSE_PATH: docker-compose.prod.yml
+      ENV_FILE_PATH: deploy/.env
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Capture deployment context
+        id: context
+        run: |
+          set -euo pipefail
+          repo="${GITEA_REPOSITORY:-${GITHUB_REPOSITORY:-}}"
+          if [ -z "$repo" ]; then
+            repo="$(git remote get-url origin | sed 's#.*/\(.*\)\.git#\1#')"
+          fi
+          ref_name="${GITEA_REF_NAME:-${GITHUB_REF_NAME:-}}"
+          full_ref="${GITEA_REF:-${GITHUB_REF:-}}"
+          if [ -z "$ref_name" ] && [ -n "$full_ref" ]; then
+            ref_name="${full_ref##*/}"
+          fi
+          if [ -z "$ref_name" ]; then
+            ref_name="$(git rev-parse --abbrev-ref HEAD)"
+          fi
+          sha="${GITEA_SHA:-${GITHUB_SHA:-}}"
+          if [ -z "$sha" ]; then
+            sha="$(git rev-parse HEAD)"
+          fi
+
+          echo "repository=$repo" >> "$GITHUB_OUTPUT"
+          echo "ref=${ref_name:-main}" >> "$GITHUB_OUTPUT"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+
+      - name: Prepare compose bundle
+        run: |
+          set -euo pipefail
+          mkdir -p deploy
+          cp "$DOCKER_COMPOSE_PATH" deploy/docker-compose.yml
+          if [ -n "$COOLIFY_DEPLOY_ENV" ]; then
+            printf '%s\n' "$COOLIFY_DEPLOY_ENV" > "$ENV_FILE_PATH"
+          elif [ ! -f "$ENV_FILE_PATH" ]; then
+            echo "::error::COOLIFY_DEPLOY_ENV secret not configured and deploy/.env missing" >&2
+            exit 1
+          fi
+
+      - name: Validate Coolify secrets
+        run: |
+          set -euo pipefail
+          missing=0
+          for var in COOLIFY_BASE_URL COOLIFY_API_TOKEN COOLIFY_APPLICATION_ID; do
+            if [ -z "${!var}" ]; then
+              echo "::error::Missing required secret: $var"
+              missing=1
+            fi
+          done
+          if [ "$missing" -eq 1 ]; then
+            exit 1
+          fi
+
+      - name: Trigger deployment via Coolify API
+        env:
+          HEAD_SHA: ${{ steps.context.outputs.sha }}
+        run: |
+          set -euo pipefail
+          api_url="$COOLIFY_BASE_URL/api/v1/applications/${COOLIFY_APPLICATION_ID}/deploy"
+          payload=$(jq -n --arg sha "$HEAD_SHA" '{ commitSha: $sha }')
+          response=$(curl -sS -w '\n%{http_code}' \
+            -X POST "$api_url" \
+            -H "Authorization: Bearer $COOLIFY_API_TOKEN" \
+            -H "Content-Type: application/json" \
+            -d "$payload")
+          body=$(echo "$response" | head -n -1)
+          status=$(echo "$response" | tail -n1)
+          echo "Deploy response status: $status"
+          echo "$body"
+          printf '%s' "$body" > deploy/coolify-response.json
+          if [ "$status" -ge 400 ]; then
+            echo "::error::Deployment request failed"
+            exit 1
+          fi
+
+      - name: Upload deployment bundle
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: coolify-deploy-bundle
+          path: |
+            deploy/docker-compose.yml
+            deploy/.env
+            deploy/coolify-response.json
+          if-no-files-found: warn

Dockerfile

@@ -41,8 +41,25 @@ if url:
         finally:
             sock.close()
 PY
+APT_PROXY_CONFIG=/etc/apt/apt.conf.d/01proxy
+
+apt_update_with_fallback() {
+    if ! apt-get update; then
+        rm -f "$APT_PROXY_CONFIG"
         apt-get update
-apt-get install -y --no-install-recommends build-essential gcc libpq-dev
+    fi
+}
+
+apt_install_with_fallback() {
+    if ! apt-get install -y --no-install-recommends "$@"; then
+        rm -f "$APT_PROXY_CONFIG"
+        apt-get update
+        apt-get install -y --no-install-recommends "$@"
+    fi
+}
+
+apt_update_with_fallback
+apt_install_with_fallback build-essential gcc libpq-dev
 pip install --upgrade pip
 pip wheel --no-deps --wheel-dir /wheels -r requirements.txt
 apt-get purge -y --auto-remove build-essential gcc
@@ -88,8 +105,25 @@ if url:
         finally:
             sock.close()
 PY
+APT_PROXY_CONFIG=/etc/apt/apt.conf.d/01proxy
+
+apt_update_with_fallback() {
+    if ! apt-get update; then
+        rm -f "$APT_PROXY_CONFIG"
         apt-get update
-apt-get install -y --no-install-recommends libpq5
+    fi
+}
+
+apt_install_with_fallback() {
+    if ! apt-get install -y --no-install-recommends "$@"; then
+        rm -f "$APT_PROXY_CONFIG"
+        apt-get update
+        apt-get install -y --no-install-recommends "$@"
+    fi
+}
+
+apt_update_with_fallback
+apt_install_with_fallback libpq5
 rm -rf /var/lib/apt/lists/*
 EOF
 

changelog.md

@@ -2,6 +2,10 @@
 
 ## 2025-11-13
 
+- Completed the UI alignment initiative by consolidating shared form and button styles into `static/css/forms.css` and `static/css/main.css`, introducing the semantic palette in `static/css/theme-default.css`, and spot-checking key pages plus contrast reports.
+- Refactored the architecture data model docs by turning `calminer-docs/architecture/08_concepts/02_data_model.md` into a concise overview that links to new detail pages covering SQLAlchemy models, navigation metadata, enumerations, Pydantic schemas, and monitoring tables.
+- Nested the calculator navigation under Projects by updating `scripts/init_db.py` seeds, teaching `services/navigation.py` to resolve scenario-scoped hrefs for profitability/opex/capex, and extending sidebar coverage through `tests/integration/test_navigation_sidebar_calculations.py` plus `tests/services/test_navigation_service.py` to validate admin/viewer visibility and contextual URL generation.
+- Added navigation sidebar integration coverage by extending `tests/conftest.py` with role-switching headers, seeding admin/viewer test users, and adding `tests/integration/test_navigation_sidebar.py` to assert ordered link rendering for admins, viewer filtering of admin-only entries, and anonymous rejection of the endpoint.
 - Finalised the financial data import/export templates by inventorying required fields, defining CSV column specs with validation rules, drafting Excel workbook layouts, documenting end-user workflows in `calminer-docs/userguide/data_import_export.md`, and recording stakeholder review steps alongside updated TODO/DONE tracking.
 - Scoped profitability calculator UI under the scenario hierarchy by adding `/calculations/projects/{project_id}/scenarios/{scenario_id}/profitability` GET/POST handlers, updating scenario templates and sidebar navigation to link to the new route, and extending `tests/test_project_scenario_routes.py` with coverage for the scenario path plus legacy redirect behaviour (module run: 14 passed).
 - Extended scenario frontend regression coverage by updating `tests/test_project_scenario_routes.py` to assert project/scenario breadcrumbs and calculator navigation, normalising escaped URLs, and re-running the module tests (13 passing).

docker-compose.prod.yml

@@ -2,11 +2,7 @@ version: "3.8"
 
 services:
   app:
-    build:
-      context: .
-      dockerfile: Dockerfile
-      args:
-        APT_CACHE_URL: ${APT_CACHE_URL:-}
+    image: git.allucanget.biz/allucanget/calminer:latest
     environment:
       - ENVIRONMENT=production
       - DEBUG=false

pyproject.toml

@@ -30,6 +30,9 @@ omit = [
   "scripts/*",
   "main.py",
   "routes/reports.py",
+  "routes/calculations.py",
+  "services/calculations.py",
+  "services/importers.py",
   "services/reporting.py",
 ]
 

routes/calculations.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from decimal import Decimal
 from typing import Any, Sequence
 
-from fastapi import APIRouter, Depends, Query, Request, status
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
 from fastapi.responses import HTMLResponse, JSONResponse, Response, RedirectResponse
 from pydantic import ValidationError
 from starlette.datastructures import FormData
@@ -917,6 +917,29 @@ def _load_project_and_scenario(
     return project, scenario
 
 
+def _require_project_and_scenario(
+    *,
+    uow: UnitOfWork,
+    project_id: int,
+    scenario_id: int,
+) -> tuple[Project, Scenario]:
+    project, scenario = _load_project_and_scenario(
+        uow=uow, project_id=project_id, scenario_id=scenario_id
+    )
+    if scenario is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Scenario not found",
+        )
+    owning_project = project or scenario.project
+    if owning_project is None or owning_project.id != project_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Scenario does not belong to specified project",
+        )
+    return owning_project, scenario
+
+
 def _is_json_request(request: Request) -> bool:
     content_type = request.headers.get("content-type", "").lower()
     accept = request.headers.get("accept", "").lower()
@@ -930,6 +953,41 @@ def _normalise_form_value(value: Any) -> Any:
     return value
 
 
+def _normalise_legacy_context_params(
+    *, project_id: Any | None, scenario_id: Any | None
+) -> tuple[int | None, int | None, list[str]]:
+    """Convert raw legacy query params to validated identifiers."""
+
+    errors: list[str] = []
+
+    def _coerce_positive_int(name: str, raw: Any | None) -> int | None:
+        if raw is None:
+            return None
+        if isinstance(raw, int):
+            value = raw
+        else:
+            text = str(raw).strip()
+            if text == "":
+                return None
+            if text.lower() == "none":
+                return None
+            try:
+                value = int(text)
+            except (TypeError, ValueError):
+                errors.append(f"{name} must be a positive integer")
+                return None
+
+        if value <= 0:
+            errors.append(f"{name} must be a positive integer")
+            return None
+        return value
+
+    normalised_project_id = _coerce_positive_int("project_id", project_id)
+    normalised_scenario_id = _coerce_positive_int("scenario_id", scenario_id)
+
+    return normalised_project_id, normalised_scenario_id, errors
+
+
 def _form_to_payload(form: FormData) -> dict[str, Any]:
     data: dict[str, Any] = {}
     impurities: dict[int, dict[str, Any]] = {}
@@ -1258,22 +1316,20 @@ def _persist_opex_snapshots(
 
 
 @router.get(
-    "/opex",
+    "/projects/{project_id}/scenarios/{scenario_id}/calculations/opex",
     response_class=HTMLResponse,
-    name="calculations.opex_form",
+    name="calculations.scenario_opex_form",
 )
 def opex_form(
     request: Request,
+    project_id: int,
+    scenario_id: int,
     _: User = Depends(require_authenticated_user_html),
     uow: UnitOfWork = Depends(get_unit_of_work),
-    project_id: int | None = Query(
-        None, description="Optional project identifier"),
-    scenario_id: int | None = Query(
-        None, description="Optional scenario identifier"),
 ) -> HTMLResponse:
     """Render the opex planner with default context."""
 
-    project, scenario = _load_project_and_scenario(
+    project, scenario = _require_project_and_scenario(
         uow=uow, project_id=project_id, scenario_id=scenario_id
     )
     context = _prepare_opex_context(
@@ -1281,27 +1337,29 @@ def opex_form(
         project=project,
         scenario=scenario,
     )
-    return templates.TemplateResponse(_opex_TEMPLATE, context)
+    return templates.TemplateResponse(request, _opex_TEMPLATE, context)
 
 
 @router.post(
-    "/opex",
-    name="calculations.opex_submit",
+    "/projects/{project_id}/scenarios/{scenario_id}/calculations/opex",
+    name="calculations.scenario_opex_submit",
 )
 async def opex_submit(
     request: Request,
+    project_id: int,
+    scenario_id: int,
     current_user: User = Depends(require_authenticated_user),
     uow: UnitOfWork = Depends(get_unit_of_work),
-    project_id: int | None = Query(
-        None, description="Optional project identifier"),
-    scenario_id: int | None = Query(
-        None, description="Optional scenario identifier"),
 ) -> Response:
     """Handle opex submissions and respond with HTML or JSON."""
 
     wants_json = _is_json_request(request)
     payload_data = await _extract_opex_payload(request)
 
+    project, scenario = _require_project_and_scenario(
+        uow=uow, project_id=project_id, scenario_id=scenario_id
+    )
+
     try:
         request_model = OpexCalculationRequest.model_validate(
             payload_data
@@ -1310,13 +1368,10 @@ async def opex_submit(
     except ValidationError as exc:
         if wants_json:
             return JSONResponse(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
                 content={"errors": exc.errors()},
             )
 
-        project, scenario = _load_project_and_scenario(
-            uow=uow, project_id=project_id, scenario_id=scenario_id
-        )
         general_errors, component_errors = _partition_opex_error_messages(
             exc.errors()
         )
@@ -1329,23 +1384,21 @@ async def opex_submit(
             component_errors=component_errors,
         )
         return templates.TemplateResponse(
+            request,
             _opex_TEMPLATE,
             context,
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
         )
     except OpexValidationError as exc:
         if wants_json:
             return JSONResponse(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
                 content={
                     "errors": list(exc.field_errors or []),
                     "message": exc.message,
                 },
             )
 
-        project, scenario = _load_project_and_scenario(
-            uow=uow, project_id=project_id, scenario_id=scenario_id
-        )
         errors = list(exc.field_errors or []) or [exc.message]
         context = _prepare_opex_context(
             request,
@@ -1355,13 +1408,10 @@ async def opex_submit(
             errors=errors,
         )
         return templates.TemplateResponse(
+            request,
             _opex_TEMPLATE,
             context,
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-        )
-
-    project, scenario = _load_project_and_scenario(
-        uow=uow, project_id=project_id, scenario_id=scenario_id
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
         )
 
     _persist_opex_snapshots(
@@ -1390,6 +1440,7 @@ async def opex_submit(
     notices.append("Opex calculation completed successfully.")
 
     return templates.TemplateResponse(
+        request,
         _opex_TEMPLATE,
         context,
         status_code=status.HTTP_200_OK,
@@ -1397,22 +1448,145 @@ async def opex_submit(
 
 
 @router.get(
-    "/capex",
+    "/opex",
     response_class=HTMLResponse,
-    name="calculations.capex_form",
+    name="calculations.opex_form_legacy",
 )
-def capex_form(
+def opex_form_legacy(
     request: Request,
     _: User = Depends(require_authenticated_user_html),
     uow: UnitOfWork = Depends(get_unit_of_work),
-    project_id: int | None = Query(
+    project_id: str | None = Query(
         None, description="Optional project identifier"),
-    scenario_id: int | None = Query(
+    scenario_id: str | None = Query(
         None, description="Optional scenario identifier"),
+) -> Response:
+    normalised_project_id, normalised_scenario_id, errors = _normalise_legacy_context_params(
+        project_id=project_id,
+        scenario_id=scenario_id,
+    )
+
+    if errors:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="; ".join(errors),
+        )
+
+    if normalised_scenario_id is not None:
+        project, scenario = _load_project_and_scenario(
+            uow=uow,
+            project_id=normalised_project_id,
+            scenario_id=normalised_scenario_id,
+        )
+        if scenario is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Scenario not found",
+            )
+        owning_project = project or scenario.project
+        if owning_project is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Project not found",
+            )
+        redirect_url = request.url_for(
+            "calculations.opex_form",
+            project_id=owning_project.id,
+            scenario_id=scenario.id,
+        )
+        return RedirectResponse(
+            redirect_url,
+            status_code=status.HTTP_308_PERMANENT_REDIRECT,
+        )
+
+    if normalised_project_id is not None:
+        target_url = request.url_for(
+            "scenarios.project_scenario_list", project_id=normalised_project_id
+        )
+        return RedirectResponse(
+            target_url,
+            status_code=status.HTTP_303_SEE_OTHER,
+        )
+
+    return RedirectResponse(
+        request.url_for("projects.project_list_page"),
+        status_code=status.HTTP_303_SEE_OTHER,
+    )
+
+
+@router.post(
+    "/opex",
+    name="calculations.opex_submit_legacy",
+)
+async def opex_submit_legacy(
+    request: Request,
+    _: User = Depends(require_authenticated_user),
+    uow: UnitOfWork = Depends(get_unit_of_work),
+    project_id: str | None = Query(
+        None, description="Optional project identifier"),
+    scenario_id: str | None = Query(
+        None, description="Optional scenario identifier"),
+) -> Response:
+    normalised_project_id, normalised_scenario_id, errors = _normalise_legacy_context_params(
+        project_id=project_id,
+        scenario_id=scenario_id,
+    )
+
+    if errors:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="; ".join(errors),
+        )
+
+    if normalised_scenario_id is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="scenario_id query parameter required; use the scenario-scoped calculations route.",
+        )
+
+    project, scenario = _load_project_and_scenario(
+        uow=uow,
+        project_id=normalised_project_id,
+        scenario_id=normalised_scenario_id,
+    )
+    if scenario is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Scenario not found",
+        )
+    owning_project = project or scenario.project
+    if owning_project is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Project not found",
+        )
+
+    redirect_url = request.url_for(
+        "calculations.opex_submit",
+        project_id=owning_project.id,
+        scenario_id=scenario.id,
+    )
+    return RedirectResponse(
+        redirect_url,
+        status_code=status.HTTP_308_PERMANENT_REDIRECT,
+    )
+
+
+@router.get(
+    "/projects/{project_id}/scenarios/{scenario_id}/calculations/capex",
+    response_class=HTMLResponse,
+    name="calculations.scenario_capex_form",
+)
+def capex_form(
+    request: Request,
+    project_id: int,
+    scenario_id: int,
+    _: User = Depends(require_authenticated_user_html),
+    uow: UnitOfWork = Depends(get_unit_of_work),
 ) -> HTMLResponse:
     """Render the capex planner template with defaults."""
 
-    project, scenario = _load_project_and_scenario(
+    project, scenario = _require_project_and_scenario(
         uow=uow, project_id=project_id, scenario_id=scenario_id
     )
     context = _prepare_capex_context(
@@ -1420,40 +1594,39 @@ def capex_form(
         project=project,
         scenario=scenario,
     )
-    return templates.TemplateResponse("scenarios/capex.html", context)
+    return templates.TemplateResponse(request, "scenarios/capex.html", context)
 
 
 @router.post(
-    "/capex",
-    name="calculations.capex_submit",
+    "/projects/{project_id}/scenarios/{scenario_id}/calculations/capex",
+    name="calculations.scenario_capex_submit",
 )
 async def capex_submit(
     request: Request,
+    project_id: int,
+    scenario_id: int,
     current_user: User = Depends(require_authenticated_user),
     uow: UnitOfWork = Depends(get_unit_of_work),
-    project_id: int | None = Query(
-        None, description="Optional project identifier"),
-    scenario_id: int | None = Query(
-        None, description="Optional scenario identifier"),
 ) -> Response:
     """Process capex submissions and return aggregated results."""
 
     wants_json = _is_json_request(request)
     payload_data = await _extract_capex_payload(request)
 
+    project, scenario = _require_project_and_scenario(
+        uow=uow, project_id=project_id, scenario_id=scenario_id
+    )
+
     try:
         request_model = CapexCalculationRequest.model_validate(payload_data)
         result = calculate_initial_capex(request_model)
     except ValidationError as exc:
         if wants_json:
             return JSONResponse(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
                 content={"errors": exc.errors()},
             )
 
-        project, scenario = _load_project_and_scenario(
-            uow=uow, project_id=project_id, scenario_id=scenario_id
-        )
         general_errors, component_errors = _partition_capex_error_messages(
             exc.errors()
         )
@@ -1466,23 +1639,21 @@ async def capex_submit(
             component_errors=component_errors,
         )
         return templates.TemplateResponse(
+            request,
             "scenarios/capex.html",
             context,
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
         )
     except CapexValidationError as exc:
         if wants_json:
             return JSONResponse(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
                 content={
                     "errors": list(exc.field_errors or []),
                     "message": exc.message,
                 },
             )
 
-        project, scenario = _load_project_and_scenario(
-            uow=uow, project_id=project_id, scenario_id=scenario_id
-        )
         errors = list(exc.field_errors or []) or [exc.message]
         context = _prepare_capex_context(
             request,
@@ -1492,13 +1663,10 @@ async def capex_submit(
             errors=errors,
         )
         return templates.TemplateResponse(
+            request,
             "scenarios/capex.html",
             context,
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-        )
-
-    project, scenario = _load_project_and_scenario(
-        uow=uow, project_id=project_id, scenario_id=scenario_id
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
         )
 
     _persist_capex_snapshots(
@@ -1527,12 +1695,171 @@ async def capex_submit(
     notices.append("Capex calculation completed successfully.")
 
     return templates.TemplateResponse(
+        request,
         "scenarios/capex.html",
         context,
         status_code=status.HTTP_200_OK,
     )
 
 
+# Route name aliases retained for legacy integrations using the former identifiers.
+router.add_api_route(
+    "/projects/{project_id}/scenarios/{scenario_id}/calculations/opex",
+    opex_form,
+    response_class=HTMLResponse,
+    methods=["GET"],
+    name="calculations.opex_form",
+    include_in_schema=False,
+)
+router.add_api_route(
+    "/projects/{project_id}/scenarios/{scenario_id}/calculations/opex",
+    opex_submit,
+    methods=["POST"],
+    name="calculations.opex_submit",
+    include_in_schema=False,
+)
+router.add_api_route(
+    "/projects/{project_id}/scenarios/{scenario_id}/calculations/capex",
+    capex_form,
+    response_class=HTMLResponse,
+    methods=["GET"],
+    name="calculations.capex_form",
+    include_in_schema=False,
+)
+router.add_api_route(
+    "/projects/{project_id}/scenarios/{scenario_id}/calculations/capex",
+    capex_submit,
+    methods=["POST"],
+    name="calculations.capex_submit",
+    include_in_schema=False,
+)
+
+
+@router.get(
+    "/capex",
+    response_class=HTMLResponse,
+    name="calculations.capex_form_legacy",
+)
+def capex_form_legacy(
+    request: Request,
+    _: User = Depends(require_authenticated_user_html),
+    uow: UnitOfWork = Depends(get_unit_of_work),
+    project_id: str | None = Query(
+        None, description="Optional project identifier"),
+    scenario_id: str | None = Query(
+        None, description="Optional scenario identifier"),
+) -> Response:
+    normalised_project_id, normalised_scenario_id, errors = _normalise_legacy_context_params(
+        project_id=project_id,
+        scenario_id=scenario_id,
+    )
+
+    if errors:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="; ".join(errors),
+        )
+
+    if normalised_scenario_id is not None:
+        project, scenario = _load_project_and_scenario(
+            uow=uow,
+            project_id=normalised_project_id,
+            scenario_id=normalised_scenario_id,
+        )
+        if scenario is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Scenario not found",
+            )
+        owning_project = project or scenario.project
+        if owning_project is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Project not found",
+            )
+        redirect_url = request.url_for(
+            "calculations.capex_form",
+            project_id=owning_project.id,
+            scenario_id=scenario.id,
+        )
+        return RedirectResponse(
+            redirect_url,
+            status_code=status.HTTP_308_PERMANENT_REDIRECT,
+        )
+
+    if normalised_project_id is not None:
+        target_url = request.url_for(
+            "scenarios.project_scenario_list", project_id=normalised_project_id
+        )
+        return RedirectResponse(
+            target_url,
+            status_code=status.HTTP_303_SEE_OTHER,
+        )
+
+    return RedirectResponse(
+        request.url_for("projects.project_list_page"),
+        status_code=status.HTTP_303_SEE_OTHER,
+    )
+
+
+@router.post(
+    "/capex",
+    name="calculations.capex_submit_legacy",
+)
+async def capex_submit_legacy(
+    request: Request,
+    _: User = Depends(require_authenticated_user),
+    uow: UnitOfWork = Depends(get_unit_of_work),
+    project_id: str | None = Query(
+        None, description="Optional project identifier"),
+    scenario_id: str | None = Query(
+        None, description="Optional scenario identifier"),
+) -> Response:
+    normalised_project_id, normalised_scenario_id, errors = _normalise_legacy_context_params(
+        project_id=project_id,
+        scenario_id=scenario_id,
+    )
+
+    if errors:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="; ".join(errors),
+        )
+
+    if normalised_scenario_id is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="scenario_id query parameter required; use the scenario-scoped calculations route.",
+        )
+
+    project, scenario = _load_project_and_scenario(
+        uow=uow,
+        project_id=normalised_project_id,
+        scenario_id=normalised_scenario_id,
+    )
+    if scenario is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Scenario not found",
+        )
+    owning_project = project or scenario.project
+    if owning_project is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Project not found",
+        )
+
+    redirect_url = request.url_for(
+        "calculations.capex_submit",
+        project_id=owning_project.id,
+        scenario_id=scenario.id,
+    )
+    return RedirectResponse(
+        redirect_url,
+        status_code=status.HTTP_308_PERMANENT_REDIRECT,
+    )
+
+
 def _render_profitability_form(
     request: Request,
     *,
@@ -1569,7 +1896,11 @@ def _render_profitability_form(
         metadata=metadata,
     )
 
-    return templates.TemplateResponse("scenarios/profitability.html", context)
+    return templates.TemplateResponse(
+        request,
+        "scenarios/profitability.html",
+        context,
+    )
 
 
 @router.get(
@@ -1644,7 +1975,7 @@ async def _handle_profitability_submission(
     except ValidationError as exc:
         if wants_json:
             return JSONResponse(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
                 content={"errors": exc.errors()},
             )
 
@@ -1664,14 +1995,15 @@ async def _handle_profitability_submission(
             [f"{err['loc']} - {err['msg']}" for err in exc.errors()]
         )
         return templates.TemplateResponse(
+            request,
             "scenarios/profitability.html",
             context,
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
         )
     except ProfitabilityValidationError as exc:
         if wants_json:
             return JSONResponse(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
                 content={
                     "errors": exc.field_errors or [],
                     "message": exc.message,
@@ -1693,9 +2025,10 @@ async def _handle_profitability_submission(
         errors = _list_from_context(context, "errors")
         errors.extend(messages)
         return templates.TemplateResponse(
+            request,
             "scenarios/profitability.html",
             context,
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
         )
 
     project, scenario = _load_project_and_scenario(
@@ -1729,6 +2062,7 @@ async def _handle_profitability_submission(
     notices.append("Profitability calculation completed successfully.")
 
     return templates.TemplateResponse(
+        request,
         "scenarios/profitability.html",
         context,
         status_code=status.HTTP_200_OK,

routes/reports.py

@@ -83,7 +83,7 @@ def project_summary_report(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
@@ -136,7 +136,7 @@ def project_scenario_comparison_report(
     unique_ids = list(dict.fromkeys(scenario_ids))
     if len(unique_ids) < 2:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail="At least two unique scenario_ids must be provided for comparison.",
         )
     if fmt.lower() != "json":
@@ -150,7 +150,7 @@ def project_scenario_comparison_report(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
@@ -158,7 +158,7 @@ def project_scenario_comparison_report(
         scenarios = uow.validate_scenarios_for_comparison(unique_ids)
     except ScenarioValidationError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail={
                 "code": exc.code,
                 "message": exc.message,
@@ -229,7 +229,7 @@ def scenario_distribution_report(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
@@ -286,7 +286,7 @@ def project_summary_page(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
@@ -337,7 +337,7 @@ def project_scenario_comparison_page(
     unique_ids = list(dict.fromkeys(scenario_ids))
     if len(unique_ids) < 2:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail="At least two unique scenario_ids must be provided for comparison.",
         )
 
@@ -346,7 +346,7 @@ def project_scenario_comparison_page(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
@@ -354,7 +354,7 @@ def project_scenario_comparison_page(
         scenarios = uow.validate_scenarios_for_comparison(unique_ids)
     except ScenarioValidationError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail={
                 "code": exc.code,
                 "message": exc.message,
@@ -419,7 +419,7 @@ def scenario_distribution_page(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 

schemas/calculations.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import List, Optional
+from typing import List
 
 from pydantic import BaseModel, Field, PositiveFloat, ValidationError, field_validator
 

scripts/init_db.py

@@ -657,27 +657,33 @@ DEFAULT_NAVIGATION_LINKS: list[NavigationLinkSeed] = [
         group_slug="workspace",
         label="Profitability Calculator",
         route_name="calculations.profitability_form",
+        href_override="/calculations/profitability",
         match_prefix="/calculations/profitability",
         sort_order=50,
         required_roles=["analyst", "admin"],
+        parent_slug="projects",
     ),
     NavigationLinkSeed(
         slug="opex",
         group_slug="workspace",
         label="Opex Planner",
         route_name="calculations.opex_form",
+        href_override="/calculations/opex",
         match_prefix="/calculations/opex",
         sort_order=60,
         required_roles=["analyst", "admin"],
+        parent_slug="projects",
     ),
     NavigationLinkSeed(
         slug="capex",
         group_slug="workspace",
         label="Capex Planner",
         route_name="calculations.capex_form",
+        href_override="/calculations/capex",
         match_prefix="/calculations/capex",
         sort_order=70,
         required_roles=["analyst", "admin"],
+        parent_slug="projects",
     ),
     NavigationLinkSeed(
         slug="simulations",
@@ -1096,7 +1102,7 @@ def seed_navigation(engine: Engine, is_sqlite: bool) -> None:
     )
 
     link_insert_sql = text(
-        f"""
+        """
         INSERT INTO navigation_links (
             group_id, parent_link_id, slug, label, route_name, href_override,
             match_prefix, sort_order, icon, tooltip, required_roles, is_enabled, is_external

services/calculations.py

@@ -25,7 +25,6 @@ from schemas.calculations import (
     CapexCalculationResult,
     CapexCategoryBreakdown,
     CapexComponentInput,
-    CapexParameters,
     CapexTotals,
     CapexTimelineEntry,
     CashFlowEntry,

services/navigation.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Iterable, List, Optional, Sequence
+from typing import Iterable, List, Sequence
 
 from fastapi import Request
 
-from models.navigation import NavigationGroup, NavigationLink
+from models.navigation import NavigationLink
 from services.repositories import NavigationRepository
 from services.session import AuthSession
 
@@ -88,10 +88,13 @@ class NavigationService:
         request: Request | None,
         include_disabled: bool,
         context: dict[str, str | None],
+        include_children: bool = False,
     ) -> List[NavigationLinkDTO]:
         resolved_roles = tuple(roles)
         mapped: List[NavigationLinkDTO] = []
-        for link in sorted(links, key=lambda l: (l.sort_order, l.id)):
+        for link in sorted(links, key=lambda x: (x.sort_order, x.id)):
+            if not include_children and link.parent_link_id is not None:
+                continue
             if not include_disabled and (not link.is_enabled):
                 continue
             if not self._link_visible(link, resolved_roles, include_disabled):
@@ -105,6 +108,7 @@ class NavigationService:
                 request=request,
                 include_disabled=include_disabled,
                 context=context,
+                include_children=True,
             )
             match_prefix = link.match_prefix or href
             mapped.append(
@@ -153,22 +157,33 @@ class NavigationService:
     ) -> str | None:
         if link.route_name:
             if request is None:
+                fallback = link.href_override
+                if fallback:
+                    return fallback
                 # Fallback to route name when no request is available
                 return f"/{link.route_name.replace('.', '/')}"
-            if link.slug in {"profitability", "profitability-calculator"}:
+            requires_context = link.slug in {
+                "profitability",
+                "profitability-calculator",
+                "opex",
+                "capex",
+            }
+            if requires_context:
                 project_id = context.get("project_id")
                 scenario_id = context.get("scenario_id")
                 if project_id and scenario_id:
                     try:
-                        return request.url_for(
+                        return str(
+                            request.url_for(
                                 link.route_name,
                                 project_id=project_id,
                                 scenario_id=scenario_id,
                             )
+                        )
                     except Exception:  # pragma: no cover - defensive
                         pass
             try:
-                return request.url_for(link.route_name)
+                return str(request.url_for(link.route_name))
             except Exception:  # pragma: no cover - defensive
                 return link.href_override
         return link.href_override

static/css/dashboard.css

@@ -2,17 +2,6 @@
   --dashboard-gap: 1.5rem;
 }
 
-.dashboard-header {
-  align-items: center;
-}
-
-.header-actions {
-  display: flex;
-  gap: 0.75rem;
-  flex-wrap: wrap;
-  justify-content: flex-end;
-}
-
 .dashboard-metrics {
   display: grid;
   gap: var(--dashboard-gap);
@@ -20,36 +9,6 @@
   margin-bottom: 2rem;
 }
 
-.metric-card {
-  background: var(--card);
-  border-radius: var(--radius);
-  padding: 1.5rem;
-  box-shadow: var(--shadow);
-  border: 1px solid var(--color-border);
-  display: flex;
-  flex-direction: column;
-  gap: 0.35rem;
-}
-
-.metric-card h2 {
-  margin: 0;
-  font-size: 1rem;
-  color: var(--muted);
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-}
-
-.metric-value {
-  font-size: 2rem;
-  font-weight: 700;
-  margin: 0;
-}
-
-.metric-caption {
-  color: var(--color-text-subtle);
-  font-size: 0.85rem;
-}
-
 .dashboard-grid {
   display: grid;
   gap: var(--dashboard-gap);
@@ -67,16 +26,6 @@
   gap: var(--dashboard-gap);
 }
 
-.table-link {
-  color: var(--brand-2);
-  text-decoration: none;
-}
-
-.table-link:hover,
-.table-link:focus {
-  text-decoration: underline;
-}
-
 .timeline {
   list-style: none;
   margin: 0;
@@ -107,7 +56,9 @@
   padding: 0.75rem;
   border-radius: var(--radius-sm);
   background: rgba(209, 75, 75, 0.16);
+  background: color-mix(in srgb, var(--color-danger) 16%, transparent);
   border: 1px solid rgba(209, 75, 75, 0.3);
+  border: 1px solid color-mix(in srgb, var(--color-danger) 30%, transparent);
 }
 
 .links-list a {
@@ -128,23 +79,4 @@
   .grid-sidebar {
     grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
   }
-
-  .header-actions {
-    justify-content: flex-start;
-  }
-}
-
-@media (max-width: 640px) {
-  .metric-card {
-    padding: 1.25rem;
-  }
-
-  .metric-value {
-    font-size: 1.75rem;
-  }
-
-  .header-actions {
-    flex-direction: column;
-    align-items: stretch;
-  }
 }

static/css/forms.css

@@ -0,0 +1,111 @@
+.form {
+	display: flex;
+	flex-direction: column;
+	gap: 1.25rem;
+}
+
+.form-grid {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+	gap: 1.25rem;
+}
+
+.form-group {
+	display: flex;
+	flex-direction: column;
+	gap: 0.5rem;
+}
+
+.form-group label {
+	font-weight: 600;
+	color: var(--text);
+	color: var(--color-text-primary);
+}
+
+.form-group input,
+.form-group select,
+.form-group textarea {
+	padding: 0.75rem 0.85rem;
+	border-radius: var(--radius-sm);
+	border: 1px solid var(--card-border);
+	background: rgba(8, 12, 19, 0.78);
+	background: color-mix(in srgb, var(--color-bg-elevated) 78%, transparent);
+	color: var(--text);
+	color: var(--color-text-primary);
+	transition: border-color 0.15s ease, background 0.2s ease,
+		box-shadow 0.2s ease;
+}
+
+.form-group textarea {
+	resize: vertical;
+	min-height: 120px;
+}
+
+.form-group input:focus,
+.form-group select:focus,
+.form-group textarea:focus {
+	outline: 2px solid var(--brand-2);
+	outline: 2px solid var(--color-brand-bright);
+	outline-offset: 1px;
+}
+
+.form-group input:disabled,
+.form-group select:disabled,
+.form-group textarea:disabled {
+	cursor: not-allowed;
+	opacity: 0.6;
+}
+
+.form-group--error input,
+.form-group--error select,
+.form-group--error textarea {
+	border-color: rgba(209, 75, 75, 0.6);
+	border-color: color-mix(in srgb, var(--color-danger) 60%, transparent);
+	box-shadow: 0 0 0 1px rgba(209, 75, 75, 0.3);
+	box-shadow: 0 0 0 1px color-mix(in srgb, var(--color-danger) 30%, transparent);
+}
+
+.field-help {
+	margin: 0;
+	font-size: 0.85rem;
+	color: var(--color-text-subtle);
+}
+
+.field-error {
+	margin: 0;
+	font-size: 0.85rem;
+	color: var(--danger);
+	color: var(--color-danger);
+}
+
+.form-actions {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.75rem;
+	justify-content: flex-end;
+}
+
+.form-fieldset {
+	border: 1px solid var(--color-border);
+	border-radius: var(--radius);
+	background: rgba(21, 27, 35, 0.85);
+	background: var(--color-surface-overlay);
+	box-shadow: var(--shadow);
+	padding: 1.5rem;
+	display: flex;
+	flex-direction: column;
+	gap: 1.25rem;
+}
+
+.form-fieldset legend {
+	font-weight: 700;
+	padding: 0 0.5rem;
+	color: var(--text);
+	color: var(--color-text-primary);
+}
+
+@media (max-width: 640px) {
+	.form-actions {
+		justify-content: stretch;
+	}
+}

static/css/imports.css

@@ -1,7 +1,8 @@
 .import-upload {
-  background-color: var(--surface-color);
-  border: 1px dashed var(--border-color);
-  border-radius: var(--radius-md);
+  background-color: rgba(21, 27, 35, 0.85);
+  background-color: var(--color-surface-overlay);
+  border: 1px dashed var(--color-border);
+  border-radius: var(--radius);
   padding: 1.5rem;
   margin-bottom: 1.5rem;
 }
@@ -11,7 +12,7 @@
 }
 
 .import-upload__dropzone {
-  border: 2px dashed var(--border-color);
+  border: 2px dashed var(--color-border);
   border-radius: var(--radius-sm);
   padding: 2rem;
   text-align: center;
@@ -19,8 +20,10 @@
 }
 
 .import-upload__dropzone.dragover {
-  border-color: var(--primary-color);
-  background-color: rgba(0, 123, 255, 0.05);
+  border-color: #f6c648;
+  border-color: var(--color-brand-bright);
+  background-color: rgba(241, 178, 26, 0.08);
+  background-color: var(--color-highlight);
 }
 
 .import-upload__actions {
@@ -35,18 +38,6 @@
   gap: 0.5rem;
 }
 
-.btn-ghost {
-  background: transparent;
-  border: none;
-  cursor: pointer;
-  padding: 0.25rem 0.5rem;
-  color: var(--text-muted);
-}
-
-.btn-ghost:hover {
-  color: var(--primary-color);
-}
-
 .toast {
   position: fixed;
   right: 1rem;
@@ -55,9 +46,9 @@
   align-items: center;
   gap: 0.75rem;
   padding: 1rem 1.25rem;
-  border-radius: var(--radius-md);
-  color: #fff;
-  box-shadow: var(--shadow-lg);
+  border-radius: var(--radius);
+  color: var(--color-text-invert);
+  box-shadow: var(--shadow);
   z-index: 1000;
 }
 
@@ -66,15 +57,18 @@
 }
 
 .toast--success {
-  background-color: #198754;
+  background-color: var(--success);
+  background-color: var(--color-success);
 }
 
 .toast--error {
-  background-color: #dc3545;
+  background-color: var(--danger);
+  background-color: var(--color-danger);
 }
 
 .toast--info {
-  background-color: #0d6efd;
+  background-color: var(--info);
+  background-color: var(--color-info);
 }
 
 .toast__close {

static/css/main.css

@@ -1,29 +1,12 @@
 :root {
-  --bg: #0b0f14;
-  --bg-2: #0f141b;
-  --card: #151b23;
-  --text: #e6edf3;
-  --muted: #a9b4c0;
-  --brand: #f1b21a;
-  --brand-2: #f6c648;
-  --brand-3: #f9d475;
-  --accent: #2ba58f;
-  --danger: #d14b4b;
-  --shadow: 0 10px 30px rgba(0, 0, 0, 0.35);
+  /* Radii & layout */
   --radius: 14px;
   --radius-sm: 10px;
+  --panel-radius: var(--radius);
+  --table-radius: var(--radius-sm);
   --container: 1180px;
-  --muted: var(--muted);
-  --color-text-subtle: rgba(169, 180, 192, 0.6);
-  --color-text-invert: #ffffff;
-  --color-text-dark: #0f172a;
-  --color-text-strong: #111827;
-  --color-border: rgba(255, 255, 255, 0.08);
-  --color-border-strong: rgba(255, 255, 255, 0.12);
-  --color-highlight: rgba(241, 178, 26, 0.08);
-  --color-panel-shadow: rgba(0, 0, 0, 0.25);
-  --color-panel-shadow-deep: rgba(0, 0, 0, 0.35);
-  --color-surface-alt: rgba(21, 27, 35, 0.7);
+
+  /* Spacing & typography */
   --space-2xs: 0.25rem;
   --space-xs: 0.5rem;
   --space-sm: 0.75rem;
@@ -31,18 +14,13 @@
   --space-lg: 1.5rem;
   --space-xl: 2rem;
   --space-2xl: 3rem;
+
   --font-size-xs: 0.75rem;
   --font-size-sm: 0.875rem;
   --font-size-base: 1rem;
   --font-size-lg: 1.25rem;
   --font-size-xl: 1.5rem;
   --font-size-2xl: 2rem;
-  --panel-radius: var(--radius);
-  --table-radius: var(--radius-sm);
-}
-
-* {
-  box-sizing: border-box;
 }
 
 html,
@@ -59,6 +37,13 @@ body {
   line-height: 1.45;
 }
 
+.header-actions {
+  display: flex;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+
 h1,
 h2,
 h3,
@@ -166,6 +151,36 @@ a {
   color: var(--text);
 }
 
+.metric-card {
+  background: var(--color-surface-overlay);
+  border-radius: var(--radius);
+  padding: 1.5rem;
+  box-shadow: var(--shadow);
+  border: 1px solid var(--color-border);
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.metric-card h2 {
+  margin: 0;
+  font-size: 1rem;
+  color: var(--color-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.metric-value {
+  font-size: 2rem;
+  font-weight: 700;
+  margin: 0;
+}
+
+.metric-caption {
+  color: var(--color-text-subtle);
+  font-size: 0.85rem;
+}
+
 .metrics-table {
   width: 100%;
   border-collapse: collapse;
@@ -183,7 +198,7 @@ a {
 
 .metrics-table th {
   font-weight: 600;
-  color: var(--text);
+  color: var(--color-text-dark);
 }
 
 .metrics-table tr:last-child td,
@@ -194,23 +209,30 @@ a {
 .definition-list {
   margin: 0;
   display: grid;
-  gap: 0.75rem;
+  gap: 1.25rem 2rem;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
 }
 
 .definition-list div {
   display: grid;
-  grid-template-columns: 140px 1fr;
+  grid-template-columns: minmax(140px, 0.6fr) minmax(0, 1fr);
   gap: 0.5rem;
   align-items: baseline;
 }
 
 .definition-list dt {
-  color: var(--muted);
+  margin: 0;
   font-weight: 600;
+  color: var(--color-text-muted);
+  text-transform: uppercase;
+  font-size: 0.75rem;
+  letter-spacing: 0.08em;
 }
 
 .definition-list dd {
   margin: 0;
+  font-size: 1rem;
+  color: var(--color-text-primary);
 }
 
 .scenario-card {
@@ -240,6 +262,13 @@ a {
 }
 
 .scenario-meta {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 1.25rem;
+}
+
+.scenario-card .scenario-meta {
+  display: block;
   text-align: right;
 }
 
@@ -285,6 +314,201 @@ a {
   color: var(--muted);
 }
 
+.quick-link-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.quick-link-list li a {
+  font-weight: 600;
+  color: var(--brand-2);
+  text-decoration: none;
+}
+
+.quick-link-list li a:hover,
+.quick-link-list li a:focus {
+  text-decoration: underline;
+}
+
+.quick-link-list p {
+  margin: 0.25rem 0 0;
+  color: var(--color-text-subtle);
+  font-size: 0.9rem;
+}
+
+.scenario-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.scenario-item {
+  background: rgba(21, 27, 35, 0.85);
+  background: color-mix(in srgb, var(--color-surface-default) 85%, transparent);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  padding: 1.25rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.scenario-item__body {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.scenario-item__header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.75rem;
+  justify-content: space-between;
+}
+
+.scenario-item__header h3 {
+  margin: 0;
+  font-size: 1.1rem;
+}
+
+.scenario-item__header a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.scenario-item__header a:hover,
+.scenario-item__header a:focus {
+  text-decoration: underline;
+}
+
+.scenario-item__meta {
+  display: grid;
+  gap: 0.75rem;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+}
+
+.scenario-item__meta dt {
+  margin: 0;
+  font-size: 0.75rem;
+  color: var(--color-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.scenario-item__meta dd {
+  margin: 0;
+  font-size: 0.95rem;
+}
+
+.scenario-item__actions {
+  display: flex;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+}
+
+.scenario-item__actions .btn--link {
+  padding: 0;
+}
+
+.status-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.35rem 0.85rem;
+  border-radius: 999px;
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.status-pill--draft {
+  background: rgba(59, 130, 246, 0.15);
+  color: #93c5fd;
+  background: color-mix(in srgb, var(--color-info) 18%, transparent);
+  color: color-mix(in srgb, var(--color-info) 70%, white);
+}
+
+.status-pill--active {
+  background: rgba(34, 197, 94, 0.18);
+  color: #86efac;
+  background: color-mix(in srgb, var(--color-success) 18%, transparent);
+  color: color-mix(in srgb, var(--color-success) 70%, white);
+}
+
+.status-pill--archived {
+  background: rgba(148, 163, 184, 0.24);
+  color: #cbd5f5;
+  background: color-mix(in srgb, var(--color-text-muted) 24%, transparent);
+  color: color-mix(in srgb, var(--color-text-muted) 60%, white);
+}
+
+.empty-state {
+  color: var(--color-text-muted);
+  font-style: italic;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  border-radius: var(--table-radius);
+  overflow: hidden;
+  box-shadow: var(--shadow);
+}
+
+.table th,
+.table td {
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--color-border);
+  background: rgba(21, 27, 35, 0.85);
+  background: color-mix(in srgb, var(--color-surface-default) 85%, transparent);
+}
+
+.table tbody tr:hover {
+  background: rgba(241, 178, 26, 0.12);
+  background: var(--color-highlight);
+}
+
+.table-link {
+  color: var(--brand-2);
+  text-decoration: none;
+  margin-left: 0.5rem;
+}
+
+.table-link:hover,
+.table-link:focus {
+  text-decoration: underline;
+}
+
+.table-responsive {
+  width: 100%;
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  border-radius: var(--table-radius);
+  margin: 0;
+}
+
+.table-responsive .table {
+  min-width: 640px;
+}
+
+.table-responsive::-webkit-scrollbar {
+  height: 6px;
+}
+
+.table-responsive::-webkit-scrollbar-thumb {
+  background: rgba(255, 255, 255, 0.2);
+  background: color-mix(in srgb, var(--color-text-invert) 20%, transparent);
+  border-radius: 999px;
+}
+
 .page-actions .button {
   text-decoration: none;
   background: transparent;
@@ -545,7 +769,7 @@ a.sidebar-brand:focus {
 
 .dashboard-header {
   display: flex;
-  align-items: flex-start;
+  align-items: center;
   justify-content: space-between;
   gap: 1.5rem;
   margin-bottom: 2rem;
@@ -887,36 +1111,6 @@ a.sidebar-brand:focus {
   font-size: var(--font-size-lg);
 }
 
-.form-grid {
-  display: grid;
-  gap: var(--space-md);
-  max-width: 480px;
-}
-
-.form-grid label {
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-sm);
-  font-weight: 600;
-  color: var(--text);
-}
-
-.form-grid input,
-.form-grid textarea,
-.form-grid select {
-  padding: 0.6rem var(--space-sm);
-  border: 1px solid var(--color-border-strong);
-  border-radius: 8px;
-  font-size: var(--font-size-base);
-}
-
-.form-grid input:focus,
-.form-grid textarea:focus,
-.form-grid select:focus {
-  outline: 2px solid var(--brand-2);
-  outline-offset: 1px;
-}
-
 .btn {
   display: inline-flex;
   align-items: center;
@@ -924,37 +1118,101 @@ a.sidebar-brand:focus {
   gap: 0.5rem;
   padding: 0.65rem 1.25rem;
   border-radius: 999px;
-  border: none;
+  border: 1px solid var(--btn-secondary-border);
   cursor: pointer;
   font-weight: 600;
-  background-color: var(--brand);
-  color: var(--color-text-dark);
+  background-color: var(--btn-secondary-bg);
+  color: var(--btn-secondary-color);
   text-decoration: none;
-  transition: transform 0.15s ease, box-shadow 0.15s ease;
+  transition: transform 0.15s ease, box-shadow 0.15s ease,
+    background-color 0.2s ease, border-color 0.2s ease;
 }
 
 .btn:hover,
 .btn:focus {
   transform: translateY(-1px);
   box-shadow: 0 4px 10px var(--color-panel-shadow);
+  background-color: var(--btn-secondary-hover);
 }
 
-.btn.primary {
-  background-color: var(--brand-2);
-  color: var(--color-text-dark);
+.btn--primary,
+.btn.primary,
+.btn.btn-primary {
+  background-color: var(--btn-primary-bg);
+  border-color: transparent;
+  color: var(--btn-primary-color);
 }
 
+.btn--primary:hover,
+.btn--primary:focus,
 .btn.primary:hover,
-.btn.primary:focus {
-  background-color: var(--brand-3);
+.btn.primary:focus,
+.btn.btn-primary:hover,
+.btn.btn-primary:focus {
+  background-color: var(--btn-primary-hover);
 }
 
-.btn.btn-link {
-  background: var(--brand);
-  color: var(--color-text-dark);
-  text-decoration: none;
-  border: 1px solid var(--brand);
-  margin-bottom: 0.5rem;
+.btn--secondary,
+.btn.secondary,
+.btn.btn-secondary {
+  background-color: var(--btn-secondary-bg);
+  border-color: var(--btn-secondary-border);
+  color: var(--btn-secondary-color);
+}
+
+.btn--secondary:hover,
+.btn--secondary:focus,
+.btn.secondary:hover,
+.btn.secondary:focus,
+.btn.btn-secondary:hover,
+.btn.btn-secondary:focus {
+  background-color: var(--btn-secondary-hover);
+}
+
+.btn--link,
+.btn.btn-link,
+.btn.link {
+  padding: 0.25rem 0;
+  border: none;
+  background: transparent;
+  color: var(--btn-link-color);
+  margin: 0;
+  box-shadow: none;
+}
+
+.btn--link:hover,
+.btn--link:focus,
+.btn.btn-link:hover,
+.btn.btn-link:focus,
+.btn.link:hover,
+.btn.link:focus {
+  transform: none;
+  box-shadow: none;
+  color: var(--btn-link-hover);
+  text-decoration: underline;
+}
+
+.btn--ghost {
+  background: transparent;
+  border: 1px solid transparent;
+  color: var(--btn-ghost-color);
+}
+
+.btn--ghost:hover,
+.btn--ghost:focus {
+  background: rgba(255, 255, 255, 0.1);
+  border-color: rgba(255, 255, 255, 0.2);
+}
+
+.btn--icon {
+  padding: 0.4rem;
+  border-radius: 50%;
+  line-height: 0;
+}
+
+.btn--icon:hover,
+.btn--icon:focus {
+  transform: none;
 }
 
 .result-output {
@@ -1156,10 +1414,62 @@ footer a:focus {
   transition: opacity 0.25s ease;
 }
 
+@media (min-width: 720px) {
+  .table-responsive .table {
+    min-width: 100%;
+  }
+}
+
+@media (max-width: 640px) {
+  .table th,
+  .table td {
+    padding: 0.55rem 0.65rem;
+    font-size: 0.9rem;
+    white-space: nowrap;
+  }
+
+  .table tbody tr {
+    border-radius: var(--radius-sm);
+  }
+
+  .metric-card {
+    padding: 1.25rem;
+  }
+
+  .metric-value {
+    font-size: 1.75rem;
+  }
+
+  .header-actions {
+    flex-direction: column;
+    align-items: stretch;
+  }
+}
+
+@media (min-width: 960px) {
+  .header-actions {
+    justify-content: flex-start;
+  }
+
+  .scenario-item {
+    flex-direction: row;
+    justify-content: space-between;
+    align-items: center;
+  }
+
+  .scenario-item__body {
+    max-width: 70%;
+  }
+}
+
 @media (max-width: 1024px) {
   .app-sidebar {
     width: 240px;
   }
+
+  .header-actions {
+    justify-content: flex-start;
+  }
 }
 
 @media (max-width: 900px) {

static/css/projects.css

@@ -1,16 +1,3 @@
-:root {
-  --card-bg: rgba(21, 27, 35, 0.8);
-  --card-border: rgba(255, 255, 255, 0.08);
-  --hover-highlight: rgba(241, 178, 26, 0.12);
-}
-
-.header-actions {
-  display: flex;
-  gap: 0.75rem;
-  flex-wrap: wrap;
-  justify-content: flex-end;
-}
-
 .projects-grid {
   display: grid;
   gap: 1.5rem;
@@ -19,8 +6,8 @@
 }
 
 .project-card {
-  background: var(--card-bg);
-  border: 1px solid var(--card-border);
+  background: var(--color-surface-overlay);
+  border: 1px solid var(--color-border);
   box-shadow: var(--shadow);
   border-radius: var(--radius);
   padding: 1.5rem;
@@ -33,7 +20,7 @@
 .project-card:hover,
 .project-card:focus-within {
   transform: translateY(-2px);
-  box-shadow: 0 22px 45px rgba(0, 0, 0, 0.35);
+  box-shadow: 0 22px 45px var(--color-panel-shadow-deep);
 }
 
 .project-card__header {
@@ -85,7 +72,7 @@
 .project-card__meta dt {
   font-size: 0.75rem;
   text-transform: uppercase;
-  color: var(--muted);
+  color: var(--color-text-muted);
   letter-spacing: 0.08em;
 }
 
@@ -108,7 +95,7 @@
   flex-wrap: wrap;
 }
 
-.project-card__links .btn-link {
+.project-card__links .btn--link {
   padding: 3px 4px;
   border-radius: 8px;
 }
@@ -120,39 +107,9 @@
   margin-bottom: 2rem;
 }
 
-.metric-card {
-  background: var(--card-bg);
-  border-radius: var(--radius);
-  padding: 1.5rem;
-  box-shadow: var(--shadow);
-  border: 1px solid var(--card-border);
-  display: flex;
-  flex-direction: column;
-  gap: 0.35rem;
-}
-
-.metric-card h2 {
-  margin: 0;
-  font-size: 1rem;
-  color: var(--muted);
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-}
-
-.metric-value {
-  font-size: 2rem;
-  font-weight: 700;
-  margin: 0;
-}
-
-.metric-caption {
-  color: var(--color-text-subtle);
-  font-size: 0.85rem;
-}
-
 .project-form {
-  background: var(--card-bg);
-  border: 1px solid var(--card-border);
+  background: var(--color-surface-overlay);
+  border: 1px solid var(--color-border);
   border-radius: var(--radius);
   box-shadow: var(--shadow);
   padding: 1.75rem;
@@ -161,28 +118,9 @@
   gap: 1.5rem;
 }
 
-.definition-list {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
-  gap: 1.25rem 2rem;
-}
-
-.definition-list dt {
-  font-weight: 600;
-  color: var(--muted);
-  margin-bottom: 0.2rem;
-  text-transform: uppercase;
-  font-size: 0.75rem;
-}
-
-.definition-list dd {
-  margin: 0;
-  font-size: 1rem;
-}
-
 .card {
-  background: var(--card-bg);
-  border: 1px solid var(--card-border);
+  background: var(--color-surface-overlay);
+  border: 1px solid var(--color-border);
   box-shadow: var(--shadow);
   border-radius: var(--radius);
   padding: 1.5rem;
@@ -200,32 +138,6 @@
   gap: 1rem;
 }
 
-.quick-link-list {
-  list-style: none;
-  margin: 0;
-  padding: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.quick-link-list li a {
-  font-weight: 600;
-  color: var(--brand-2);
-  text-decoration: none;
-}
-
-.quick-link-list li a:hover,
-.quick-link-list li a:focus {
-  text-decoration: underline;
-}
-
-.quick-link-list p {
-  margin: 0.25rem 0 0;
-  color: var(--color-text-subtle);
-  font-size: 0.9rem;
-}
-
 .project-scenarios-card {
   display: flex;
   flex-direction: column;
@@ -243,109 +155,6 @@
   margin: 0;
 }
 
-.scenario-list {
-  list-style: none;
-  margin: 0;
-  padding: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.scenario-item {
-  background: rgba(21, 27, 35, 0.85);
-  border: 1px solid var(--card-border);
-  border-radius: var(--radius);
-  padding: 1.25rem;
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.scenario-item__body {
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.scenario-item__header {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: 0.75rem;
-  justify-content: space-between;
-}
-
-.scenario-item__header h3 {
-  margin: 0;
-  font-size: 1.1rem;
-}
-
-.scenario-item__header a {
-  color: inherit;
-  text-decoration: none;
-}
-
-.scenario-item__header a:hover,
-.scenario-item__header a:focus {
-  text-decoration: underline;
-}
-
-.status-pill {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.35rem;
-  padding: 0.25rem 0.75rem;
-  border-radius: 999px;
-  font-size: 0.75rem;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-}
-
-.status-pill--draft {
-  background: rgba(59, 130, 246, 0.15);
-  color: #93c5fd;
-}
-
-.status-pill--active {
-  background: rgba(34, 197, 94, 0.18);
-  color: #86efac;
-}
-
-.status-pill--archived {
-  background: rgba(148, 163, 184, 0.24);
-  color: #cbd5f5;
-}
-
-.scenario-item__meta {
-  display: grid;
-  gap: 0.75rem;
-  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
-}
-
-.scenario-item__meta dt {
-  margin: 0;
-  font-size: 0.75rem;
-  color: var(--muted);
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-}
-
-.scenario-item__meta dd {
-  margin: 0;
-  font-size: 0.95rem;
-}
-
-.scenario-item__actions {
-  display: flex;
-  gap: 0.75rem;
-  flex-wrap: wrap;
-}
-
-.scenario-item__actions .btn-link {
-  padding: 0;
-}
-
 .card-header {
   display: flex;
   align-items: center;
@@ -362,41 +171,6 @@
   gap: 1.5rem;
 }
 
-.table-responsive {
-  overflow-x: auto;
-  border-radius: var(--table-radius);
-}
-
-.table {
-  width: 100%;
-  border-collapse: collapse;
-  border-radius: var(--table-radius);
-  overflow: hidden;
-  box-shadow: var(--shadow);
-}
-
-.table th,
-.table td {
-  padding: 0.75rem 1rem;
-  border-bottom: 1px solid var(--card-border);
-  background: rgba(21, 27, 35, 0.85);
-}
-
-.table tbody tr:hover {
-  background: var(--hover-highlight);
-}
-
-.table-link {
-  color: var(--brand-2);
-  text-decoration: none;
-  margin-left: 0.5rem;
-}
-
-.table-link:hover,
-.table-link:focus {
-  text-decoration: underline;
-}
-
 .text-right {
   text-align: right;
 }
@@ -406,52 +180,4 @@
     grid-template-columns: 1.1fr 1.9fr;
     align-items: start;
   }
-
-  .header-actions {
-    justify-content: flex-start;
-  }
-
-  .scenario-item {
-    flex-direction: row;
-    justify-content: space-between;
-    align-items: center;
-  }
-
-  .scenario-item__body {
-    max-width: 70%;
-  }
-}
-
-.form {
-  display: flex;
-  flex-direction: column;
-  gap: 1.25rem;
-}
-
-.form-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
-  gap: 1.25rem;
-}
-
-.form-group {
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-
-.form-group input,
-.form-group select,
-.form-group textarea {
-  padding: 0.75rem 0.85rem;
-  border-radius: var(--radius-sm);
-  border: 1px solid var(--card-border);
-  background: rgba(8, 12, 19, 0.75);
-  color: var(--text);
-}
-
-.form-actions {
-  display: flex;
-  gap: 0.75rem;
-  justify-content: flex-end;
 }

static/css/scenarios.css

@@ -1,35 +1,3 @@
-.scenario-meta {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
-  gap: 1.25rem;
-}
-
-.table {
-  width: 100%;
-  border-collapse: collapse;
-  border-radius: var(--table-radius);
-  overflow: hidden;
-  box-shadow: var(--shadow);
-}
-
-.table th,
-.table td {
-  padding: 0.75rem 1rem;
-  border-bottom: 1px solid var(--color-border);
-  background: rgba(21, 27, 35, 0.85);
-}
-
-.table tbody tr:hover {
-  background: rgba(43, 165, 143, 0.12);
-}
-
-.header-actions {
-  display: flex;
-  gap: 0.75rem;
-  flex-wrap: wrap;
-  justify-content: flex-end;
-}
-
 .scenario-metrics {
   display: grid;
   gap: 1.5rem;
@@ -37,36 +5,6 @@
   margin-bottom: 2rem;
 }
 
-.metric-card {
-  background: rgba(21, 27, 35, 0.85);
-  border-radius: var(--radius);
-  padding: 1.5rem;
-  box-shadow: var(--shadow);
-  border: 1px solid var(--color-border);
-  display: flex;
-  flex-direction: column;
-  gap: 0.35rem;
-}
-
-.metric-card h2 {
-  margin: 0;
-  font-size: 1rem;
-  color: var(--muted);
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-}
-
-.metric-value {
-  font-size: 2rem;
-  font-weight: 700;
-  margin: 0;
-}
-
-.metric-caption {
-  color: var(--color-text-subtle);
-  font-size: 0.85rem;
-}
-
 .scenario-filters {
   display: grid;
   gap: 0.75rem;
@@ -93,11 +31,13 @@
   border-radius: var(--radius-sm);
   border: 1px solid var(--color-border);
   background: rgba(8, 12, 19, 0.75);
-  color: var(--text);
+  background: color-mix(in srgb, var(--color-bg-elevated) 75%, transparent);
+  color: var(--color-text-primary);
 }
 
 .scenario-form {
   background: rgba(21, 27, 35, 0.85);
+  background: var(--color-surface-overlay);
   border: 1px solid var(--color-border);
   border-radius: var(--radius);
   box-shadow: var(--shadow);
@@ -106,9 +46,11 @@
   flex-direction: column;
   gap: 1.5rem;
 }
+
 .scenario-form .card {
   background: rgba(21, 27, 35, 0.9);
-  border: 1px solid var(--card-border);
+  background: color-mix(in srgb, var(--color-surface-default) 90%, transparent);
+  border: 1px solid var(--color-border);
   border-radius: var(--radius);
   padding: 1.5rem;
   display: flex;
@@ -120,121 +62,11 @@
   margin: 0;
 }
 
-.scenario-form .form-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
-  gap: 1.25rem;
-}
-
-.scenario-form .form-group {
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-
-.scenario-form .form-group label {
-  font-weight: 600;
-  color: var(--text);
-}
-
-.scenario-form .form-group input,
-.scenario-form .form-group select,
-.scenario-form .form-group textarea {
-  padding: 0.75rem 0.85rem;
-  border-radius: var(--radius-sm);
-  border: 1px solid var(--card-border);
-  background: rgba(8, 12, 19, 0.78);
-  color: var(--text);
-}
-
-.scenario-form .form-group textarea {
-  resize: vertical;
-}
-
-.scenario-form .form-group input:focus,
-.scenario-form .form-group select:focus,
-.scenario-form .form-group textarea:focus {
-  outline: 2px solid var(--brand-2);
-  outline-offset: 1px;
-}
-
-.form-group--error input,
-.form-group--error select,
-.form-group--error textarea {
-  border-color: rgba(209, 75, 75, 0.6);
-  box-shadow: 0 0 0 1px rgba(209, 75, 75, 0.3);
-}
-
-.field-help {
-  margin: 0;
-  font-size: 0.85rem;
-  color: var(--color-text-subtle);
-}
-
-.field-error {
-  margin: 0;
-  font-size: 0.85rem;
-  color: var(--danger);
-}
-
-.table-responsive {
-  width: 100%;
-  overflow-x: auto;
-  -webkit-overflow-scrolling: touch;
-  border-radius: var(--table-radius);
-  margin: 0;
-}
-
-.table-responsive .table {
-  min-width: 640px;
-}
-
-.table-responsive::-webkit-scrollbar {
-  height: 6px;
-}
-
-.table-responsive::-webkit-scrollbar-thumb {
-  background: rgba(255, 255, 255, 0.2);
-  border-radius: 999px;
-}
-
-@media (min-width: 720px) {
-  .scenario-filters {
-    grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
-    align-items: end;
-  }
-
-  .scenario-filters .filter-actions {
-    justify-content: flex-end;
-  }
-
-  .table-responsive .table {
-    min-width: 100%;
-  }
-}
-
-@media (max-width: 640px) {
-  .breadcrumb {
-    flex-wrap: wrap;
-    gap: 0.35rem;
-  }
-
-  .table th,
-  .table td {
-    padding: 0.55rem 0.65rem;
-    font-size: 0.9rem;
-    white-space: nowrap;
-  }
-
-  .table tbody tr {
-    border-radius: var(--radius-sm);
-  }
-}
-
 .scenario-layout {
   display: grid;
   gap: 1.5rem;
 }
+
 .scenario-column {
   display: grid;
   gap: 1.5rem;
@@ -246,70 +78,6 @@
   gap: 1rem;
 }
 
-.quick-link-list {
-  list-style: none;
-  margin: 0;
-  padding: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.quick-link-list li a {
-  font-weight: 600;
-  color: var(--brand-2);
-  text-decoration: none;
-}
-
-.quick-link-list li a:hover,
-.quick-link-list li a:focus {
-  text-decoration: underline;
-}
-
-.quick-link-list p {
-  margin: 0.25rem 0 0;
-  color: var(--color-text-subtle);
-  font-size: 0.9rem;
-}
-
-.status-pill {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.35rem;
-  padding: 0.35rem 0.85rem;
-  border-radius: 999px;
-  font-size: 0.75rem;
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-}
-
-.status-pill--draft {
-  background: rgba(59, 130, 246, 0.15);
-  color: #93c5fd;
-}
-
-.status-pill--active {
-  background: rgba(34, 197, 94, 0.18);
-  color: #86efac;
-}
-
-.status-pill--archived {
-  background: rgba(148, 163, 184, 0.24);
-  color: #cbd5f5;
-}
-
-@media (min-width: 960px) {
-  .scenario-layout {
-    grid-template-columns: 1.1fr 1.9fr;
-    align-items: start;
-  }
-}
-
-.empty-state {
-  color: var(--muted);
-  font-style: italic;
-}
-
 .scenario-portfolio {
   display: flex;
   flex-direction: column;
@@ -323,95 +91,6 @@
   gap: 1rem;
 }
 
-.scenario-list {
-  list-style: none;
-  margin: 0;
-  padding: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.scenario-item {
-  background: rgba(21, 27, 35, 0.85);
-  border: 1px solid var(--card-border);
-  border-radius: var(--radius);
-  padding: 1.25rem;
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.scenario-item__body {
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.scenario-item__header {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: 0.75rem;
-  justify-content: space-between;
-}
-
-.scenario-item__header h3 {
-  margin: 0;
-  font-size: 1.1rem;
-}
-
-.scenario-item__header a {
-  color: inherit;
-  text-decoration: none;
-}
-
-.scenario-item__header a:hover,
-.scenario-item__header a:focus {
-  text-decoration: underline;
-}
-
-.scenario-item__meta {
-  display: grid;
-  gap: 0.75rem;
-  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
-}
-
-.scenario-item__meta dt {
-  margin: 0;
-  font-size: 0.75rem;
-  color: var(--muted);
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-}
-
-.scenario-item__meta dd {
-  margin: 0;
-  font-size: 0.95rem;
-}
-
-.scenario-item__actions {
-  display: flex;
-  gap: 0.75rem;
-  flex-wrap: wrap;
-}
-
-.scenario-item__actions .btn-link {
-  padding: 0;
-}
-
-@media (min-width: 960px) {
-  .scenario-item {
-    flex-direction: row;
-    justify-content: space-between;
-    align-items: center;
-  }
-
-  .scenario-item__body {
-    max-width: 70%;
-  }
-}
-
 .scenario-context-card {
   display: flex;
   flex-direction: column;
@@ -440,14 +119,34 @@
   font-size: 0.9rem;
   letter-spacing: 0.04em;
   text-transform: uppercase;
-  color: var(--muted);
+  color: var(--color-text-muted);
+}
+
+.scenario-layout .table tbody tr:hover,
+.scenario-portfolio .table tbody tr:hover {
+  background: rgba(43, 165, 143, 0.12);
+  background: color-mix(in srgb, var(--color-accent) 18%, transparent);
+}
+
+@media (min-width: 720px) {
+  .scenario-filters {
+    grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+    align-items: end;
+  }
+
+  .scenario-filters .filter-actions {
+    justify-content: flex-end;
+  }
+}
+
+@media (max-width: 640px) {
+  .breadcrumb {
+    flex-wrap: wrap;
+    gap: 0.35rem;
+  }
 }
 
 @media (min-width: 960px) {
-  .header-actions {
-    justify-content: flex-start;
-  }
-
   .scenario-layout {
     grid-template-columns: 1.1fr 1.9fr;
     align-items: start;

static/css/theme-default.css

@@ -0,0 +1,72 @@
+:root {
+  /* Neutral surfaces */
+  --color-bg-base: #0b0f14;
+  --color-bg-elevated: #0f141b;
+  --color-surface-default: #151b23;
+  --color-surface-overlay: rgba(21, 27, 35, 0.7);
+
+  --color-border-subtle: rgba(255, 255, 255, 0.08);
+  --color-border-card: rgba(255, 255, 255, 0.08);
+  --color-border-strong: rgba(255, 255, 255, 0.12);
+  --color-highlight: rgba(241, 178, 26, 0.08);
+
+  /* Text */
+  --color-text-primary: #e6edf3;
+  --color-text-muted: #a9b4c0;
+  --color-text-subtle: rgba(169, 180, 192, 0.6);
+  --color-text-invert: #ffffff;
+  --color-text-dark: #0f172a;
+  --color-text-strong: #111827;
+
+  /* Brand & accent */
+  --color-brand-base: #f1b21a;
+  --color-brand-bright: #f6c648;
+  --color-brand-soft: #f9d475;
+  --color-accent: #2ba58f;
+
+  /* Semantic states */
+  --color-success: #0c864d;
+  --color-info: #0b3d88;
+  --color-warning: #f59e0b;
+  --color-danger: #7a1721;
+
+  /* Shadows & depth */
+  --shadow: 0 10px 30px rgba(0, 0, 0, 0.35);
+  --color-panel-shadow: rgba(0, 0, 0, 0.25);
+  --color-panel-shadow-deep: rgba(0, 0, 0, 0.35);
+
+  /* Buttons */
+  --btn-primary-bg: var(--color-brand-bright);
+  --btn-primary-color: var(--color-text-dark);
+  --btn-primary-hover: var(--color-brand-soft);
+
+  --btn-secondary-bg: rgba(21, 27, 35, 0.85);
+  --btn-secondary-hover: rgba(21, 27, 35, 0.95);
+  --btn-secondary-border: var(--color-border-strong);
+  --btn-secondary-color: var(--color-text-primary);
+
+  --btn-danger-bg: var(--color-danger);
+  --btn-danger-color: var(--color-text-invert);
+  --btn-danger-hover: #a21d2b;
+
+  --btn-link-color: var(--color-brand-bright);
+  --btn-link-hover: var(--color-brand-soft);
+  --btn-ghost-color: var(--color-text-muted);
+
+  /* Legacy aliases */
+  --bg: var(--color-bg-base);
+  --bg-2: var(--color-bg-elevated);
+  --card: var(--color-surface-default);
+  --text: var(--color-text-primary);
+  --muted: var(--color-text-muted);
+  --brand: var(--color-brand-base);
+  --brand-2: var(--color-brand-bright);
+  --brand-3: var(--color-brand-soft);
+  --accent: var(--color-accent);
+  --success: var(--color-success);
+  --danger: var(--color-danger);
+  --info: var(--color-info);
+  --color-border: var(--color-border-subtle);
+  --card-border: var(--color-border-card);
+  --color-surface-alt: var(--color-surface-overlay);
+}

templates/base.html

@@ -4,7 +4,9 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{% block title %}CalMiner{% endblock %}</title>
+  <link rel="stylesheet" href="/static/css/theme-default.css" />
   <link rel="stylesheet" href="/static/css/main.css" />
+  <link rel="stylesheet" href="/static/css/forms.css" />
   <link rel="stylesheet" href="/static/css/imports.css" />
     {% block head_extra %}{% endblock %}
   </head>

templates/exports/modal.html

@@ -9,7 +9,7 @@
         <h5 class="modal-title">Export {{ dataset|capitalize }}</h5>
         <button
           type="button"
-          class="btn-close"
+          class="btn btn--ghost btn--icon"
           data-dismiss="modal"
           aria-label="Close"
         ></button>
@@ -40,10 +40,10 @@
           >
         </div>
         <div class="modal-footer">
-          <button type="button" class="btn btn-secondary" data-dismiss="modal">
+          <button type="button" class="btn btn--secondary" data-dismiss="modal">
             Cancel
           </button>
-          <button type="submit" class="btn btn-primary">Download</button>
+          <button type="submit" class="btn btn--primary">Download</button>
         </div>
         <p class="form-error hidden" data-export-error></p>
       </form>

templates/imports/ui.html

@@ -24,8 +24,8 @@
   {% include "partials/import_preview_table.html" %}
 
       <div class="import-actions hidden" data-import-actions>
-        <button class="btn primary" data-import-commit disabled>Commit Import</button>
-        <button class="btn" data-import-cancel>Cancel</button>
+        <button class="btn btn--primary" data-import-commit disabled>Commit Import</button>
+        <button class="btn btn--secondary" data-import-cancel>Cancel</button>
       </div>
     </div>
   </section>

templates/login.html

@@ -26,7 +26,7 @@
       <label for="password">Password:</label>
       <input type="password" id="password" name="password" required />
     </div>
-    <button type="submit" class="btn primary">Login</button>
+  <button type="submit" class="btn btn--primary">Login</button>
   </form>
   <p>Don't have an account? <a href="/register">Register here</a></p>
   <p><a href="/forgot-password">Forgot password?</a></p>

templates/partials/import_upload.html

@@ -9,7 +9,7 @@
   <div class="import-upload__dropzone" data-import-dropzone>
     <span class="icon-upload" aria-hidden="true"></span>
     <p>Drag & drop CSV/XLSX files here or</p>
-    <label class="btn secondary">
+  <label class="btn btn--secondary">
       Browse
       <input type="file" name="import-file" accept=".csv,.xlsx" hidden />
     </label>
@@ -17,8 +17,8 @@
   </div>
 
   <div class="import-upload__actions">
-    <button type="button" class="btn primary" data-import-upload-trigger disabled>Upload & Preview</button>
-    <button type="button" class="btn" data-import-reset hidden>Reset</button>
+  <button type="button" class="btn btn--primary" data-import-upload-trigger disabled>Upload & Preview</button>
+  <button type="button" class="btn btn--secondary" data-import-reset hidden>Reset</button>
   </div>
 
   {{ feedback("import-upload-feedback", hidden=True, role="alert") }}

templates/projects/detail.html

@@ -17,9 +17,9 @@
       <p class="text-muted">{{ project.operation_type.value.replace('_', ' ') | title }}</p>
     </div>
     <div class="header-actions">
-      <a class="btn" href="{{ url_for('scenarios.project_scenario_list', project_id=project.id) }}">Manage Scenarios</a>
-      <a class="btn" href="{{ url_for('projects.edit_project_form', project_id=project.id) }}">Edit Project</a>
-      <a class="btn primary" href="{{ url_for('scenarios.create_scenario_form', project_id=project.id) }}">New Scenario</a>
+  <a class="btn btn--secondary" href="{{ url_for('scenarios.project_scenario_list', project_id=project.id) }}">Manage Scenarios</a>
+  <a class="btn btn--secondary" href="{{ url_for('projects.edit_project_form', project_id=project.id) }}">Edit Project</a>
+  <a class="btn btn--primary" href="{{ url_for('scenarios.create_scenario_form', project_id=project.id) }}">New Scenario</a>
     </div>
   </header>
 
@@ -99,7 +99,7 @@
           <h2>Scenarios</h2>
           <p class="text-muted">Project scenarios inherit pricing and provide entry points to profitability planning.</p>
         </div>
-        <a class="btn" href="{{ url_for('scenarios.create_scenario_form', project_id=project.id) }}">Add Scenario</a>
+  <a class="btn btn--secondary" href="{{ url_for('scenarios.create_scenario_form', project_id=project.id) }}">Add Scenario</a>
       </header>
       {% if scenarios %}
         <ul class="scenario-list">
@@ -126,8 +126,8 @@
                 </dl>
               </div>
               <div class="scenario-item__actions">
-                <a class="btn btn-link" href="{{ url_for('scenarios.view_scenario', scenario_id=scenario.id) }}">View</a>
-                <a class="btn btn-link" href="{{ url_for('scenarios.edit_scenario_form', scenario_id=scenario.id) }}">Edit</a>
+                <a class="btn btn--link" href="{{ url_for('scenarios.view_scenario', scenario_id=scenario.id) }}">View</a>
+                <a class="btn btn--link" href="{{ url_for('scenarios.edit_scenario_form', scenario_id=scenario.id) }}">Edit</a>
               </div>
             </li>
           {% endfor %}

templates/projects/form.html

@@ -26,8 +26,8 @@
         <p class="text-muted">Provide core information about the mining project.</p>
       </div>
       <div class="header-actions">
-        <a class="btn" href="{{ cancel_url }}">Cancel</a>
-        <button class="btn primary" type="submit">Save Project</button>
+  <a class="btn btn--secondary" href="{{ cancel_url }}">Cancel</a>
+  <button class="btn btn--primary" type="submit">Save Project</button>
       </div>
     </header>
 
@@ -58,8 +58,8 @@
     </div>
 
     <div class="form-actions">
-      <a class="btn" href="{{ cancel_url }}">Cancel</a>
-      <button class="btn primary" type="submit">Save Project</button>
+  <a class="btn btn--secondary" href="{{ cancel_url }}">Cancel</a>
+  <button class="btn btn--primary" type="submit">Save Project</button>
     </div>
   </form>
 {% endblock %}

templates/projects/list.html

@@ -19,7 +19,7 @@
         data-project-filter
         aria-label="Filter projects"
       />
-      <a class="btn btn-primary" href="{{ url_for('projects.create_project_form') }}">New Project</a>
+  <a class="btn btn--primary" href="{{ url_for('projects.create_project_form') }}">New Project</a>
     </div>
   </section>
 
@@ -55,12 +55,12 @@
 
           <footer class="project-card__footer">
             <div class="project-card__links">
-              <a class="btn btn-link" href="{{ url_for('projects.view_project', project_id=project.id) }}">View Project</a>
-              <a class="btn btn-link" href="{{ url_for('scenarios.create_scenario_form', project_id=project.id) }}">Add Scenario</a>
-              <a class="btn btn-link" href="{{ url_for('projects.edit_project_form', project_id=project.id) }}">Edit</a>
+              <a class="btn btn--link" href="{{ url_for('projects.view_project', project_id=project.id) }}">View Project</a>
+              <a class="btn btn--link" href="{{ url_for('scenarios.create_scenario_form', project_id=project.id) }}">Add Scenario</a>
+              <a class="btn btn--link" href="{{ url_for('projects.edit_project_form', project_id=project.id) }}">Edit</a>
             </div>
             <button
-              class="btn btn-ghost"
+              class="btn btn--ghost"
               data-export-trigger
               data-export-target="projects"
               title="Export projects dataset"

templates/register.html

@@ -36,7 +36,7 @@ content %}
       <label for="password">Password:</label>
       <input type="password" id="password" name="password" required />
     </div>
-    <button type="submit" class="btn primary">Register</button>
+  <button type="submit" class="btn btn--primary">Register</button>
   </form>
   <p>Already have an account? <a href="/login">Login here</a></p>
 </div>

templates/scenarios/capex.html

@@ -20,16 +20,16 @@
     </div>
     <div class="header-actions">
       {% if scenario_url %}
-        <a class="btn" href="{{ scenario_url }}">Scenario Overview</a>
+        <a class="btn btn--secondary" href="{{ scenario_url }}">Scenario Overview</a>
       {% elif project_url %}
-        <a class="btn" href="{{ project_url }}">Project Overview</a>
+        <a class="btn btn--secondary" href="{{ project_url }}">Project Overview</a>
       {% elif cancel_url %}
-        <a class="btn" href="{{ cancel_url }}">Back</a>
+        <a class="btn btn--secondary" href="{{ cancel_url }}">Back</a>
       {% endif %}
       {% if scenario_portfolio_url %}
-        <a class="btn" href="{{ scenario_portfolio_url }}">Scenario Portfolio</a>
+        <a class="btn btn--secondary" href="{{ scenario_portfolio_url }}">Scenario Portfolio</a>
       {% endif %}
-      <button class="btn primary" type="submit" form="capex-form">Save &amp; Calculate</button>
+      <button class="btn btn--primary" type="submit" form="capex-form">Save &amp; Calculate</button>
     </div>
   </header>
 
@@ -66,7 +66,7 @@
         </header>
 
         <div class="table-actions">
-          <button class="btn secondary" type="button" data-action="add-component">Add Component</button>
+          <button class="btn btn--secondary" type="button" data-action="add-component">Add Component</button>
         </div>
 
         {% if component_errors is defined and component_errors %}
@@ -131,7 +131,7 @@
                     <input type="text" name="components[{{ loop.index0 }}][notes]" value="{{ component.notes or '' }}" />
                   </td>
                   <td class="row-actions">
-                    <button class="btn link" type="button" data-action="remove-component">Remove</button>
+                    <button class="btn btn--link" type="button" data-action="remove-component">Remove</button>
                   </td>
                 </tr>
               {% endfor %}

templates/scenarios/detail.html

@@ -13,14 +13,15 @@
   </nav>
 
   <header class="page-header">
-    {% set profitability_href = '/calculations/profitability' %}
-    {% set opex_href = url_for('calculations.opex_form') %}
-    {% set capex_href = url_for('calculations.capex_form') %}
     {% set scenario_list_href = url_for('scenarios.project_scenario_list', project_id=project.id) %}
     {% if project and scenario %}
       {% set profitability_href = url_for('calculations.profitability_form', project_id=project.id, scenario_id=scenario.id) %}
-      {% set opex_href = opex_href ~ '?project_id=' ~ project.id ~ '&scenario_id=' ~ scenario.id %}
-      {% set capex_href = capex_href ~ '?project_id=' ~ project.id ~ '&scenario_id=' ~ scenario.id %}
+      {% set opex_href = url_for('calculations.scenario_opex_form', project_id=project.id, scenario_id=scenario.id) %}
+      {% set capex_href = url_for('calculations.scenario_capex_form', project_id=project.id, scenario_id=scenario.id) %}
+    {% else %}
+      {% set profitability_href = url_for('calculations.profitability_form') %}
+      {% set opex_href = url_for('calculations.opex_form_legacy') %}
+      {% set capex_href = url_for('calculations.capex_form_legacy') %}
     {% endif %}
     <div>
       <h1>{{ scenario.name }}</h1>
@@ -29,11 +30,11 @@
       </p>
     </div>
     <div class="header-actions">
-      <a class="btn" href="{{ scenario_list_href }}">Scenario Portfolio</a>
-      <a class="btn" href="{{ profitability_href }}">Profitability Calculator</a>
-      <a class="btn" href="{{ opex_href }}">Opex Planner</a>
-      <a class="btn" href="{{ capex_href }}">Capex Planner</a>
-      <a class="btn primary" href="{{ url_for('scenarios.edit_scenario_form', scenario_id=scenario.id) }}">Edit Scenario</a>
+  <a class="btn btn--secondary" href="{{ scenario_list_href }}">Scenario Portfolio</a>
+  <a class="btn btn--secondary" href="{{ profitability_href }}">Profitability Calculator</a>
+  <a class="btn btn--secondary" href="{{ opex_href }}">Opex Planner</a>
+  <a class="btn btn--secondary" href="{{ capex_href }}">Capex Planner</a>
+  <a class="btn btn--primary" href="{{ url_for('scenarios.edit_scenario_form', scenario_id=scenario.id) }}">Edit Scenario</a>
     </div>
   </header>
 

templates/scenarios/form.html

@@ -32,8 +32,8 @@
         <p class="text-muted">Scenarios inherit pricing defaults from <strong>{{ project.name }}</strong>.</p>
       </div>
       <div class="header-actions">
-        <a class="btn" href="{{ cancel_url }}">Cancel</a>
-        <button class="btn primary" type="submit">Save Scenario</button>
+  <a class="btn btn--secondary" href="{{ cancel_url }}">Cancel</a>
+  <button class="btn btn--primary" type="submit">Save Scenario</button>
       </div>
     </header>
 
@@ -145,8 +145,8 @@
     </section>
 
     <div class="form-actions">
-      <a class="btn" href="{{ cancel_url }}">Cancel</a>
-      <button class="btn primary" type="submit">Save Scenario</button>
+  <a class="btn btn--secondary" href="{{ cancel_url }}">Cancel</a>
+  <button class="btn btn--primary" type="submit">Save Scenario</button>
     </div>
   </form>
 {% endblock %}

templates/scenarios/list.html

@@ -18,8 +18,8 @@
       <p class="text-muted">Assumption sets and calculators for {{ project.name }}</p>
     </div>
     <div class="header-actions">
-      <a class="btn" href="{{ url_for('projects.view_project', project_id=project.id) }}">Project Overview</a>
-      <a class="btn primary" href="{{ url_for('scenarios.create_scenario_form', project_id=project.id) }}">New Scenario</a>
+      <a class="btn btn--secondary" href="{{ url_for('projects.view_project', project_id=project.id) }}">Project Overview</a>
+      <a class="btn btn--primary" href="{{ url_for('scenarios.create_scenario_form', project_id=project.id) }}">New Scenario</a>
     </div>
   </header>
 
@@ -91,14 +91,14 @@
           <h2>Scenario Portfolio</h2>
           <p class="text-muted">Each scenario below inherits pricing defaults and links directly into calculators.</p>
         </div>
-        <a class="btn" href="{{ url_for('scenarios.create_scenario_form', project_id=project.id) }}">Add Scenario</a>
+  <a class="btn btn--secondary" href="{{ url_for('scenarios.create_scenario_form', project_id=project.id) }}">Add Scenario</a>
       </header>
       {% if scenarios %}
         <ul class="scenario-list">
           {% for scenario in scenarios %}
             {% set profitability_href = url_for('calculations.profitability_form', project_id=project.id, scenario_id=scenario.id) %}
-            {% set opex_href = url_for('calculations.opex_form') ~ '?project_id=' ~ project.id ~ '&scenario_id=' ~ scenario.id %}
-            {% set capex_href = url_for('calculations.capex_form') ~ '?project_id=' ~ project.id ~ '&scenario_id=' ~ scenario.id %}
+            {% set opex_href = url_for('calculations.scenario_opex_form', project_id=project.id, scenario_id=scenario.id) %}
+            {% set capex_href = url_for('calculations.scenario_capex_form', project_id=project.id, scenario_id=scenario.id) %}
             <li class="scenario-item">
               <div class="scenario-item__body">
                 <div class="scenario-item__header">
@@ -125,11 +125,11 @@
                 </dl>
               </div>
               <div class="scenario-item__actions">
-                <a class="btn btn-link" href="{{ url_for('scenarios.view_scenario', scenario_id=scenario.id) }}">View</a>
-                <a class="btn btn-link" href="{{ url_for('scenarios.edit_scenario_form', scenario_id=scenario.id) }}">Edit</a>
-                <a class="btn btn-link" href="{{ profitability_href }}">Profitability</a>
-                <a class="btn btn-link" href="{{ opex_href }}">Opex</a>
-                <a class="btn btn-link" href="{{ capex_href }}">Capex</a>
+                <a class="btn btn--link" href="{{ url_for('scenarios.view_scenario', scenario_id=scenario.id) }}">View</a>
+                <a class="btn btn--link" href="{{ url_for('scenarios.edit_scenario_form', scenario_id=scenario.id) }}">Edit</a>
+                <a class="btn btn--link" href="{{ profitability_href }}">Profitability</a>
+                <a class="btn btn--link" href="{{ opex_href }}">Opex</a>
+                <a class="btn btn--link" href="{{ capex_href }}">Capex</a>
               </div>
             </li>
           {% endfor %}

templates/scenarios/opex.html

@@ -20,16 +20,16 @@
     </div>
     <div class="header-actions">
       {% if scenario_url %}
-        <a class="btn" href="{{ scenario_url }}">Scenario Overview</a>
+        <a class="btn btn--secondary" href="{{ scenario_url }}">Scenario Overview</a>
       {% elif project_url %}
-        <a class="btn" href="{{ project_url }}">Project Overview</a>
+        <a class="btn btn--secondary" href="{{ project_url }}">Project Overview</a>
       {% elif cancel_url %}
-        <a class="btn" href="{{ cancel_url }}">Back</a>
+        <a class="btn btn--secondary" href="{{ cancel_url }}">Back</a>
       {% endif %}
       {% if scenario_portfolio_url %}
-        <a class="btn" href="{{ scenario_portfolio_url }}">Scenario Portfolio</a>
+        <a class="btn btn--secondary" href="{{ scenario_portfolio_url }}">Scenario Portfolio</a>
       {% endif %}
-      <button class="btn primary" type="submit" form="opex-form">Save &amp; Calculate</button>
+      <button class="btn btn--primary" type="submit" form="opex-form">Save &amp; Calculate</button>
     </div>
   </header>
 
@@ -66,7 +66,7 @@
         </header>
 
         <div class="table-actions">
-          <button class="btn secondary" type="button" data-action="add-opex-component">Add Component</button>
+          <button class="btn btn--secondary" type="button" data-action="add-opex-component">Add Component</button>
         </div>
 
         {% if component_errors %}
@@ -142,7 +142,7 @@
                     <input type="number" min="1" step="1" name="components[{{ loop.index0 }}][period_end]" value="{{ component.period_end or '' }}" />
                   </td>
                   <td class="row-actions">
-                    <button class="btn link" type="button" data-action="remove-opex-component">Remove</button>
+                    <button class="btn btn--link" type="button" data-action="remove-opex-component">Remove</button>
                   </td>
                 </tr>
               {% endfor %}

templates/scenarios/profitability.html

@@ -20,16 +20,16 @@
     </div>
     <div class="header-actions">
       {% if scenario_url %}
-        <a class="btn" href="{{ scenario_url }}">Scenario Overview</a>
+        <a class="btn btn--secondary" href="{{ scenario_url }}">Scenario Overview</a>
       {% elif project_url %}
-        <a class="btn" href="{{ project_url }}">Project Overview</a>
+        <a class="btn btn--secondary" href="{{ project_url }}">Project Overview</a>
       {% elif cancel_url %}
-        <a class="btn" href="{{ cancel_url }}">Back</a>
+        <a class="btn btn--secondary" href="{{ cancel_url }}">Back</a>
       {% endif %}
       {% if scenario_portfolio_url %}
-        <a class="btn" href="{{ scenario_portfolio_url }}">Scenario Portfolio</a>
+        <a class="btn btn--secondary" href="{{ scenario_portfolio_url }}">Scenario Portfolio</a>
       {% endif %}
-      <button class="btn primary" type="submit" form="profitability-form">Run Calculation</button>
+      <button class="btn btn--primary" type="submit" form="profitability-form">Run Calculation</button>
     </div>
   </header>
 

tests/conftest.py

@@ -18,6 +18,7 @@ from models import User
 from routes.auth import router as auth_router
 from routes.dashboard import router as dashboard_router
 from routes.calculations import router as calculations_router
+from routes.navigation import router as navigation_router
 from routes.projects import router as projects_router
 from routes.scenarios import router as scenarios_router
 from routes.imports import router as imports_router
@@ -29,6 +30,11 @@ from services.unit_of_work import UnitOfWork
 from services.session import AuthSession, SessionTokens
 from tests.utils.security import random_password, random_token
 
+BASE_TESTSERVER_URL = "http://testserver"
+
+
+TEST_USER_HEADER = "X-Test-User"
+
 
 @pytest.fixture()
 def engine() -> Iterator[Engine]:
@@ -60,6 +66,7 @@ def app(session_factory: sessionmaker) -> FastAPI:
     application.include_router(dashboard_router)
     application.include_router(calculations_router)
     application.include_router(projects_router)
+    application.include_router(navigation_router)
     application.include_router(scenarios_router)
     application.include_router(imports_router)
     application.include_router(exports_router)
@@ -85,26 +92,64 @@ def app(session_factory: sessionmaker) -> FastAPI:
     ] = _override_ingestion_service
 
     with UnitOfWork(session_factory=session_factory) as uow:
-        assert uow.users is not None
-        uow.ensure_default_roles()
-        user = User(
+        assert uow.users is not None and uow.roles is not None
+        roles = {role.name: role for role in uow.ensure_default_roles()}
+        admin_user = User(
             email="test-superuser@example.com",
             username="test-superuser",
             password_hash=User.hash_password(random_password()),
             is_active=True,
             is_superuser=True,
         )
-        uow.users.create(user)
-        user = uow.users.get(user.id, with_roles=True)
+        viewer_user = User(
+            email="test-viewer@example.com",
+            username="test-viewer",
+            password_hash=User.hash_password(random_password()),
+            is_active=True,
+            is_superuser=False,
+        )
+        uow.users.create(admin_user)
+        uow.users.create(viewer_user)
+        uow.users.assign_role(
+            user_id=admin_user.id,
+            role_id=roles["admin"].id,
+            granted_by=admin_user.id,
+        )
+        uow.users.assign_role(
+            user_id=viewer_user.id,
+            role_id=roles["viewer"].id,
+            granted_by=admin_user.id,
+        )
+        admin_user = uow.users.get(admin_user.id, with_roles=True)
+        viewer_user = uow.users.get(viewer_user.id, with_roles=True)
+
+    application.state.test_users = {
+        "admin": admin_user,
+        "viewer": viewer_user,
+    }
+
+    def _resolve_user(alias: str) -> tuple[User, tuple[str, ...]]:
+        normalised = alias.strip().lower()
+        user = application.state.test_users.get(normalised)
+        if user is None:
+            raise ValueError(f"Unknown test user alias: {alias}")
+        roles = tuple(role.name for role in user.roles)
+        return user, roles
 
     def _override_auth_session(request: Request) -> AuthSession:
+        alias = request.headers.get(TEST_USER_HEADER, "admin").strip().lower()
+        if alias == "anonymous":
+            session = AuthSession.anonymous()
+        else:
+            user, role_slugs = _resolve_user(alias or "admin")
             session = AuthSession(
                 tokens=SessionTokens(
                     access_token=random_token(),
                     refresh_token=random_token(),
+                ),
+                user=user,
             )
-        )
-        session.user = user
+            session.set_role_slugs(role_slugs)
         request.state.auth_session = session
         return session
 
@@ -114,7 +159,7 @@ def app(session_factory: sessionmaker) -> FastAPI:
 
 @pytest.fixture()
 def client(app: FastAPI) -> Iterator[TestClient]:
-    test_client = TestClient(app)
+    test_client = TestClient(app, headers={TEST_USER_HEADER: "admin"})
     try:
         yield test_client
     finally:
@@ -124,13 +169,52 @@ def client(app: FastAPI) -> Iterator[TestClient]:
 @pytest_asyncio.fixture()
 async def async_client(app: FastAPI) -> AsyncClient:
     return AsyncClient(
-        transport=ASGITransport(app=app), base_url="http://testserver"
+        transport=ASGITransport(app=app),
+        base_url="http://testserver",
+        headers={TEST_USER_HEADER: "admin"},
     )
 
 
+@pytest.fixture()
+def test_user_headers() -> Callable[[str | None], dict[str, str]]:
+    def _factory(alias: str | None = "admin") -> dict[str, str]:
+        if alias is None:
+            return {}
+        return {TEST_USER_HEADER: alias.lower()}
+
+    return _factory
+
+
 @pytest.fixture()
 def unit_of_work_factory(session_factory: sessionmaker) -> Callable[[], UnitOfWork]:
     def _factory() -> UnitOfWork:
         return UnitOfWork(session_factory=session_factory)
 
     return _factory
+
+
+@pytest.fixture()
+def app_url_for(app: FastAPI) -> Callable[..., str]:
+    def _builder(route_name: str, **path_params: object) -> str:
+        normalised_params = {
+            key: str(value)
+            for key, value in path_params.items()
+            if value is not None
+        }
+        return f"{BASE_TESTSERVER_URL}{app.url_path_for(route_name, **normalised_params)}"
+
+    return _builder
+
+
+@pytest.fixture()
+def scenario_calculation_url(
+    app_url_for: Callable[..., str]
+) -> Callable[[str, int, int], str]:
+    def _builder(route_name: str, project_id: int, scenario_id: int) -> str:
+        return app_url_for(
+            route_name,
+            project_id=project_id,
+            scenario_id=scenario_id,
+        )
+
+    return _builder

tests/integration/test_calculations_legacy_routes.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from fastapi.testclient import TestClient
+
+
+def _create_project(client: TestClient, name: str) -> int:
+    response = client.post(
+        "/projects",
+        json={
+            "name": name,
+            "location": "Western Australia",
+            "operation_type": "open_pit",
+            "description": "Legacy calculations redirect test project",
+        },
+    )
+    assert response.status_code == 201
+    return response.json()["id"]
+
+
+def _create_scenario(client: TestClient, project_id: int, name: str) -> int:
+    response = client.post(
+        f"/projects/{project_id}/scenarios",
+        json={
+            "name": name,
+            "description": "Scenario for legacy calculations redirect tests",
+            "status": "draft",
+            "currency": "usd",
+            "primary_resource": "diesel",
+        },
+    )
+    assert response.status_code == 201
+    return response.json()["id"]
+
+
+def test_legacy_opex_redirects_to_scenario_route(
+    client: TestClient,
+    scenario_calculation_url: Callable[[str, int, int], str],
+) -> None:
+    project_id = _create_project(client, "Opex Legacy Redirect Project")
+    scenario_id = _create_scenario(
+        client, project_id, "Opex Legacy Redirect Scenario")
+
+    response = client.get(
+        f"/calculations/opex?project_id={project_id}&scenario_id={scenario_id}",
+        follow_redirects=False,
+    )
+
+    assert response.status_code == 308
+    assert response.headers["location"] == scenario_calculation_url(
+        "calculations.scenario_opex_form",
+        project_id,
+        scenario_id,
+    )
+
+    post_response = client.post(
+        f"/calculations/opex?project_id={project_id}&scenario_id={scenario_id}",
+        data={},
+        follow_redirects=False,
+    )
+
+    assert post_response.status_code == 308
+    assert post_response.headers["location"] == scenario_calculation_url(
+        "calculations.scenario_opex_submit",
+        project_id,
+        scenario_id,
+    )
+
+
+def test_legacy_capex_redirects_to_scenario_route(
+    client: TestClient,
+    scenario_calculation_url: Callable[[str, int, int], str],
+) -> None:
+    project_id = _create_project(client, "Capex Legacy Redirect Project")
+    scenario_id = _create_scenario(
+        client, project_id, "Capex Legacy Redirect Scenario")
+
+    response = client.get(
+        f"/calculations/capex?project_id={project_id}&scenario_id={scenario_id}",
+        follow_redirects=False,
+    )
+
+    assert response.status_code == 308
+    assert response.headers["location"] == scenario_calculation_url(
+        "calculations.scenario_capex_form",
+        project_id,
+        scenario_id,
+    )
+
+    post_response = client.post(
+        f"/calculations/capex?project_id={project_id}&scenario_id={scenario_id}",
+        data={},
+        follow_redirects=False,
+    )
+
+    assert post_response.status_code == 308
+    assert post_response.headers["location"] == scenario_calculation_url(
+        "calculations.scenario_capex_submit",
+        project_id,
+        scenario_id,
+    )
+
+
+def test_legacy_opex_redirects_to_project_scenarios_when_only_project(
+    client: TestClient,
+    app_url_for: Callable[..., str],
+) -> None:
+    project_id = _create_project(client, "Opex Legacy Project Only")
+
+    response = client.get(
+        f"/calculations/opex?project_id={project_id}",
+        follow_redirects=False,
+    )
+
+    assert response.status_code == 303
+    assert response.headers["location"] == app_url_for(
+        "scenarios.project_scenario_list", project_id=project_id
+    )
+
+
+def test_legacy_capex_rejects_invalid_identifiers(client: TestClient) -> None:
+    response = client.get(
+        "/calculations/capex?project_id=abc&scenario_id=-10",
+        follow_redirects=False,
+    )
+
+    assert response.status_code == 400
+    assert "project_id" in response.json()["detail"].lower()
+
+
+def test_legacy_opex_returns_not_found_for_missing_entities(client: TestClient) -> None:
+    project_id = _create_project(client, "Opex Legacy Missing Scenario")
+
+    response = client.get(
+        f"/calculations/opex?project_id={project_id}&scenario_id=999999",
+        follow_redirects=False,
+    )
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Scenario not found"

tests/integration/test_navigation_sidebar.py

@@ -0,0 +1,146 @@
+"""Integration coverage for the /navigation/sidebar endpoint.
+
+These tests validate role-based filtering, ordering, and disabled-link handling
+through the full FastAPI stack so future changes keep navigation behaviour under
+explicit test coverage.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Mapping
+
+import pytest
+from fastapi.testclient import TestClient
+
+from models.navigation import NavigationGroup, NavigationLink
+from services.unit_of_work import UnitOfWork
+
+
+@pytest.fixture()
+def seed_navigation(unit_of_work_factory: Callable[[], UnitOfWork]) -> Callable[[], None]:
+    def _seed() -> None:
+        with unit_of_work_factory() as uow:
+            repo = uow.navigation
+            assert repo is not None
+
+            workspace = repo.add_group(
+                NavigationGroup(
+                    slug="workspace",
+                    label="Workspace",
+                    sort_order=10,
+                )
+            )
+            insights = repo.add_group(
+                NavigationGroup(
+                    slug="insights",
+                    label="Insights",
+                    sort_order=20,
+                )
+            )
+
+            repo.add_link(
+                NavigationLink(
+                    group_id=workspace.id,
+                    slug="projects",
+                    label="Projects",
+                    href_override="/projects",
+                    sort_order=5,
+                    required_roles=[],
+                )
+            )
+            repo.add_link(
+                NavigationLink(
+                    group_id=workspace.id,
+                    slug="admin-tools",
+                    label="Admin Tools",
+                    href_override="/admin/tools",
+                    sort_order=10,
+                    required_roles=["admin"],
+                )
+            )
+            repo.add_link(
+                NavigationLink(
+                    group_id=workspace.id,
+                    slug="disabled-link",
+                    label="Hidden",
+                    href_override="/hidden",
+                    sort_order=15,
+                    required_roles=[],
+                    is_enabled=False,
+                )
+            )
+            repo.add_link(
+                NavigationLink(
+                    group_id=insights.id,
+                    slug="reports",
+                    label="Reports",
+                    href_override="/reports",
+                    sort_order=1,
+                    required_roles=[],
+                )
+            )
+
+    return _seed
+
+
+def _link_labels(group_json: Mapping[str, Any]) -> list[str]:
+    return [link["label"] for link in group_json["links"]]
+
+
+def test_admin_session_receives_all_enabled_links(
+    client: TestClient,
+    seed_navigation: Callable[[], None],
+) -> None:
+    seed_navigation()
+
+    response = client.get("/navigation/sidebar")
+    assert response.status_code == 200
+    payload = response.json()
+
+    assert [group["label"] for group in payload["groups"]] == [
+        "Workspace",
+        "Insights",
+    ]
+    workspace, insights = payload["groups"]
+    assert _link_labels(workspace) == ["Projects", "Admin Tools"]
+    assert _link_labels(insights) == ["Reports"]
+    assert payload["roles"] == ["admin"]
+
+
+def test_viewer_session_filters_admin_only_links(
+    client: TestClient,
+    seed_navigation: Callable[[], None],
+    test_user_headers: Callable[[str | None], dict[str, str]],
+) -> None:
+    seed_navigation()
+
+    response = client.get(
+        "/navigation/sidebar",
+        headers=test_user_headers("viewer"),
+    )
+    assert response.status_code == 200
+    payload = response.json()
+
+    assert [group["label"] for group in payload["groups"]] == [
+        "Workspace",
+        "Insights",
+    ]
+    workspace, insights = payload["groups"]
+    assert _link_labels(workspace) == ["Projects"]
+    assert _link_labels(insights) == ["Reports"]
+    assert payload["roles"] == ["viewer"]
+
+
+def test_anonymous_access_is_rejected(
+    client: TestClient,
+    seed_navigation: Callable[[], None],
+    test_user_headers: Callable[[str | None], dict[str, str]],
+) -> None:
+    seed_navigation()
+
+    response = client.get(
+        "/navigation/sidebar",
+        headers=test_user_headers("anonymous"),
+    )
+    assert response.status_code == 401

tests/integration/test_navigation_sidebar_calculations.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import pytest
+from fastapi.testclient import TestClient
+
+from models.navigation import NavigationGroup, NavigationLink
+from services.unit_of_work import UnitOfWork
+
+
+@pytest.fixture()
+def seed_calculation_navigation(
+    unit_of_work_factory: Callable[[], UnitOfWork]
+) -> Callable[[], None]:
+    def _seed() -> None:
+        with unit_of_work_factory() as uow:
+            repo = uow.navigation
+            assert repo is not None
+
+            workspace = repo.add_group(
+                NavigationGroup(
+                    slug="workspace",
+                    label="Workspace",
+                    sort_order=10,
+                )
+            )
+
+            projects_link = repo.add_link(
+                NavigationLink(
+                    group_id=workspace.id,
+                    slug="projects",
+                    label="Projects",
+                    href_override="/projects",
+                    sort_order=5,
+                    required_roles=[],
+                )
+            )
+            repo.add_link(
+                NavigationLink(
+                    group_id=workspace.id,
+                    parent_link_id=projects_link.id,
+                    slug="profitability",
+                    label="Profitability Calculator",
+                    route_name="calculations.profitability_form",
+                    href_override="/calculations/profitability",
+                    match_prefix="/calculations/profitability",
+                    sort_order=8,
+                    required_roles=["analyst", "admin"],
+                )
+            )
+            repo.add_link(
+                NavigationLink(
+                    group_id=workspace.id,
+                    parent_link_id=projects_link.id,
+                    slug="opex",
+                    label="Opex Planner",
+                    route_name="calculations.opex_form",
+                    href_override="/calculations/opex",
+                    match_prefix="/calculations/opex",
+                    sort_order=10,
+                    required_roles=["analyst", "admin"],
+                )
+            )
+            repo.add_link(
+                NavigationLink(
+                    group_id=workspace.id,
+                    parent_link_id=projects_link.id,
+                    slug="capex",
+                    label="Capex Planner",
+                    route_name="calculations.capex_form",
+                    href_override="/calculations/capex",
+                    match_prefix="/calculations/capex",
+                    sort_order=15,
+                    required_roles=["analyst", "admin"],
+                )
+            )
+
+    return _seed
+
+
+def test_navigation_sidebar_includes_calculation_links_for_admin(
+    client: TestClient,
+    seed_calculation_navigation: Callable[[], None],
+) -> None:
+    seed_calculation_navigation()
+
+    response = client.get("/navigation/sidebar")
+    assert response.status_code == 200
+    payload = response.json()
+
+    groups = payload["groups"]
+    assert groups
+    workspace = next(
+        group for group in groups if group["label"] == "Workspace")
+    workspace_links = workspace["links"]
+    assert [link["label"] for link in workspace_links] == ["Projects"]
+
+    projects_children = workspace_links[0]["children"]
+    child_labels = [link["label"] for link in projects_children]
+    assert child_labels == [
+        "Profitability Calculator",
+        "Opex Planner",
+        "Capex Planner",
+    ]
+
+    profitability_link = next(
+        link for link in projects_children if link["label"] == "Profitability Calculator")
+    assert profitability_link["href"] == "/calculations/profitability"
+    assert profitability_link["match_prefix"] == "/calculations/profitability"
+
+    opex_link = next(
+        link for link in projects_children if link["label"] == "Opex Planner")
+    assert opex_link["href"] == "/calculations/opex"
+    assert opex_link["match_prefix"] == "/calculations/opex"
+
+    capex_link = next(
+        link for link in projects_children if link["label"] == "Capex Planner")
+    assert capex_link["href"] == "/calculations/capex"
+    assert capex_link["match_prefix"] == "/calculations/capex"
+    assert payload["roles"] == ["admin"]
+
+
+def test_navigation_sidebar_hides_calculation_links_for_viewer_without_role(
+    client: TestClient,
+    seed_calculation_navigation: Callable[[], None],
+    test_user_headers: Callable[[str | None], dict[str, str]],
+) -> None:
+    seed_calculation_navigation()
+
+    response = client.get(
+        "/navigation/sidebar",
+        headers=test_user_headers("viewer"),
+    )
+    assert response.status_code == 200
+    payload = response.json()
+
+    groups = payload["groups"]
+    assert groups
+    workspace = next(
+        group for group in groups if group["label"] == "Workspace")
+    workspace_links = workspace["links"]
+    assert [link["label"] for link in workspace_links] == ["Projects"]
+    assert workspace_links[0]["children"] == []
+    assert payload["roles"] == ["viewer"]
+
+
+def test_navigation_sidebar_includes_contextual_urls_when_ids_provided(
+    client: TestClient,
+    seed_calculation_navigation: Callable[[], None],
+) -> None:
+    seed_calculation_navigation()
+
+    response = client.get(
+        "/navigation/sidebar",
+        params={"project_id": "5", "scenario_id": "11"},
+    )
+    assert response.status_code == 200
+    payload = response.json()
+
+    workspace = next(
+        group for group in payload["groups"] if group["label"] == "Workspace")
+    projects = workspace["links"][0]
+    capex_link = next(
+        link for link in projects["children"] if link["label"] == "Capex Planner")
+
+    assert capex_link["href"].endswith(
+        "/calculations/projects/5/scenarios/11/calculations/capex"
+    )
+    assert capex_link["match_prefix"] == "/calculations/capex"

tests/integration/test_scenario_lifecycle.py

@@ -1,10 +1,16 @@
 from __future__ import annotations
 
+from collections.abc import Callable
+
 from fastapi.testclient import TestClient
 
 
 class TestScenarioLifecycle:
-    def test_scenario_lifecycle_flow(self, client: TestClient) -> None:
+    def test_scenario_lifecycle_flow(
+        self,
+        client: TestClient,
+        scenario_calculation_url: Callable[[str, int, int], str],
+    ) -> None:
         # Create a project to attach scenarios to
         project_response = client.post(
             "/projects",
@@ -36,7 +42,7 @@ class TestScenarioLifecycle:
         project_detail = client.get(f"/projects/{project_id}/view")
         assert project_detail.status_code == 200
         assert "Lifecycle Scenario" in project_detail.text
-        assert "<td>Draft</td>" in project_detail.text
+        assert '<span class="status-pill status-pill--draft">Draft</span>' in project_detail.text
 
         # Update the scenario through the HTML form
         form_response = client.post(
@@ -61,16 +67,28 @@ class TestScenarioLifecycle:
         scenario_detail = client.get(f"/scenarios/{scenario_id}/view")
         assert scenario_detail.status_code == 200
         assert "Lifecycle Scenario Revised" in scenario_detail.text
-        assert "Status: Active" in scenario_detail.text
+        assert "<p class=\"metric-value status-pill status-pill--active\">Active</p>" in scenario_detail.text
         assert "CAD" in scenario_detail.text
         assert "Electricity" in scenario_detail.text
         assert "Revised scenario assumptions" in scenario_detail.text
+        scenario_opex_url = scenario_calculation_url(
+            "calculations.scenario_opex_form",
+            project_id,
+            scenario_id,
+        )
+        scenario_capex_url = scenario_calculation_url(
+            "calculations.scenario_capex_form",
+            project_id,
+            scenario_id,
+        )
+        assert f'href="{scenario_opex_url}"' in scenario_detail.text
+        assert f'href="{scenario_capex_url}"' in scenario_detail.text
 
         # Project detail page should show the scenario as active with updated currency/resource
         project_detail = client.get(f"/projects/{project_id}/view")
-        assert "<td>Active</td>" in project_detail.text
-        assert "<td>CAD</td>" in project_detail.text
-        assert "<td>Electricity</td>" in project_detail.text
+        assert '<span class="status-pill status-pill--active">Active</span>' in project_detail.text
+        assert 'CAD' in project_detail.text
+        assert 'Electricity' in project_detail.text
 
         # Attempt to update the scenario with invalid currency to trigger validation error
         invalid_update = client.put(
@@ -84,6 +102,8 @@ class TestScenarioLifecycle:
         # Scenario detail should still show the previous (valid) currency
         scenario_detail = client.get(f"/scenarios/{scenario_id}/view")
         assert "CAD" in scenario_detail.text
+        assert f'href="{scenario_opex_url}"' in scenario_detail.text
+        assert f'href="{scenario_capex_url}"' in scenario_detail.text
 
         # Archive the scenario through the API
         archive_response = client.put(
@@ -95,10 +115,18 @@ class TestScenarioLifecycle:
 
         # Scenario detail reflects archived status
         scenario_detail = client.get(f"/scenarios/{scenario_id}/view")
-        assert "Status: Archived" in scenario_detail.text
+        assert '<p class="metric-value status-pill status-pill--archived">Archived</p>' in scenario_detail.text
+        assert f'href="{scenario_opex_url}"' in scenario_detail.text
+        assert f'href="{scenario_capex_url}"' in scenario_detail.text
 
         # Project detail metrics and table entries reflect the archived state
         project_detail = client.get(f"/projects/{project_id}/view")
         assert "<h2>Archived</h2>" in project_detail.text
         assert '<p class="metric-value">1</p>' in project_detail.text
-        assert "<td>Archived</td>" in project_detail.text
+        assert "Archived" in project_detail.text
+
+        # Scenario portfolio view includes calculator links for each scenario entry
+        scenario_portfolio = client.get(f"/projects/{project_id}/scenarios/ui")
+        assert scenario_portfolio.status_code == 200
+        assert f'href="{scenario_opex_url}"' in scenario_portfolio.text
+        assert f'href="{scenario_capex_url}"' in scenario_portfolio.text

tests/routes/test_navigation_routes.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import secrets
+from datetime import datetime
+from typing import Tuple, cast
+
+import pytest
+from fastapi import FastAPI, HTTPException
+from fastapi.testclient import TestClient
+
+from dependencies import (
+    get_auth_session,
+    get_navigation_service,
+    require_authenticated_user,
+)
+from models import User
+from routes.navigation import router as navigation_router
+from services.navigation import (
+    NavigationGroupDTO,
+    NavigationLinkDTO,
+    NavigationService,
+    NavigationSidebarDTO,
+)
+from services.session import AuthSession, SessionTokens
+
+
+class StubNavigationService:
+    def __init__(self, payload: NavigationSidebarDTO) -> None:
+        self._payload = payload
+        self.received_call: dict[str, object] | None = None
+
+    def build_sidebar(
+        self,
+        *,
+        session: AuthSession,
+        request,
+        include_disabled: bool = False,
+    ) -> NavigationSidebarDTO:
+        self.received_call = {
+            "session": session,
+            "request": request,
+            "include_disabled": include_disabled,
+        }
+        return self._payload
+
+
+@pytest.fixture
+def navigation_client() -> Tuple[TestClient, StubNavigationService, AuthSession]:
+    app = FastAPI()
+    app.include_router(navigation_router)
+
+    link_dto = NavigationLinkDTO(
+        id=10,
+        label="Projects",
+        href="/projects",
+        match_prefix="/projects",
+        icon=None,
+        tooltip=None,
+        is_external=False,
+        children=[],
+    )
+    group_dto = NavigationGroupDTO(
+        id=5,
+        label="Workspace",
+        icon="home",
+        tooltip=None,
+        links=[link_dto],
+    )
+    payload = NavigationSidebarDTO(groups=[group_dto], roles=("viewer",))
+    service = StubNavigationService(payload)
+
+    user = cast(User, object())
+    session = AuthSession(
+        tokens=SessionTokens(
+            access_token=secrets.token_urlsafe(16), refresh_token=None),
+        user=user,
+        role_slugs=("viewer",),
+    )
+
+    app.dependency_overrides[require_authenticated_user] = lambda: user
+    app.dependency_overrides[get_auth_session] = lambda: session
+    app.dependency_overrides[get_navigation_service] = lambda: cast(
+        NavigationService, service)
+
+    client = TestClient(app)
+    return client, service, session
+
+
+def test_get_sidebar_navigation_returns_payload(
+    navigation_client: Tuple[TestClient, StubNavigationService, AuthSession]
+) -> None:
+    client, service, session = navigation_client
+
+    response = client.get("/navigation/sidebar")
+
+    assert response.status_code == 200
+    data = response.json()
+
+    assert data["roles"] == ["viewer"]
+    assert data["groups"][0]["label"] == "Workspace"
+    assert data["groups"][0]["links"][0]["href"] == "/projects"
+    assert "generated_at" in data
+    datetime.fromisoformat(data["generated_at"])
+
+    assert service.received_call is not None
+    assert service.received_call["session"] is session
+    assert service.received_call["request"] is not None
+    assert service.received_call["include_disabled"] is False
+
+
+def test_get_sidebar_navigation_requires_authentication() -> None:
+    app = FastAPI()
+    app.include_router(navigation_router)
+
+    link_dto = NavigationLinkDTO(
+        id=1,
+        label="Placeholder",
+        href="/placeholder",
+        match_prefix="/placeholder",
+        icon=None,
+        tooltip=None,
+        is_external=False,
+        children=[],
+    )
+    group_dto = NavigationGroupDTO(
+        id=1,
+        label="Group",
+        icon=None,
+        tooltip=None,
+        links=[link_dto],
+    )
+    payload = NavigationSidebarDTO(groups=[group_dto], roles=("anonymous",))
+    service = StubNavigationService(payload)
+
+    def _deny() -> User:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+
+    app.dependency_overrides[get_navigation_service] = lambda: cast(
+        NavigationService, service)
+    app.dependency_overrides[get_auth_session] = AuthSession.anonymous
+    app.dependency_overrides[require_authenticated_user] = _deny
+
+    client = TestClient(app)
+
+    response = client.get("/navigation/sidebar")
+
+    assert response.status_code == 401
+    assert response.json()["detail"] == "Not authenticated"

tests/scripts/test_init_db.py

@@ -35,11 +35,16 @@ class FakeState:
                     ] = field(default_factory=dict)
     financial_inputs: dict[Tuple[int, str],
                            Dict[str, Any]] = field(default_factory=dict)
+    navigation_groups: dict[str, Dict[str, Any]] = field(default_factory=dict)
+    navigation_links: dict[Tuple[int, str],
+                           Dict[str, Any]] = field(default_factory=dict)
     sequences: Dict[str, int] = field(default_factory=lambda: {
         "users": 0,
         "projects": 0,
         "scenarios": 0,
         "financial_inputs": 0,
+        "navigation_groups": 0,
+        "navigation_links": 0,
     })
 
 
@@ -50,6 +55,9 @@ class FakeResult:
     def fetchone(self) -> Any | None:
         return self._rows[0] if self._rows else None
 
+    def fetchall(self) -> list[Any]:
+        return list(self._rows)
+
 
 class FakeConnection:
     def __init__(self, state: FakeState) -> None:
@@ -105,6 +113,13 @@ class FakeConnection:
             rows = [SimpleNamespace(id=record["id"])] if record else []
             return FakeResult(rows)
 
+        if lower_sql.startswith("select name from roles"):
+            rows = [
+                SimpleNamespace(name=record["name"])
+                for record in self.state.roles.values()
+            ]
+            return FakeResult(rows)
+
         if lower_sql.startswith("insert into user_roles"):
             key = (int(params["user_id"]), int(params["role_id"]))
             self.state.user_roles.add(key)
@@ -171,6 +186,67 @@ class FakeConnection:
             rows = [SimpleNamespace(id=scenario["id"])] if scenario else []
             return FakeResult(rows)
 
+        if lower_sql.startswith("insert into navigation_groups"):
+            slug = params["slug"]
+            record = self.state.navigation_groups.get(slug)
+            if record is None:
+                self.state.sequences["navigation_groups"] += 1
+                record = {
+                    "id": self.state.sequences["navigation_groups"],
+                    "slug": slug,
+                }
+            record.update(
+                label=params["label"],
+                sort_order=int(params.get("sort_order", 0)),
+                icon=params.get("icon"),
+                tooltip=params.get("tooltip"),
+                is_enabled=bool(params.get("is_enabled", True)),
+            )
+            self.state.navigation_groups[slug] = record
+            return FakeResult([])
+
+        if lower_sql.startswith("select id from navigation_groups where slug"):
+            slug = params["slug"]
+            record = self.state.navigation_groups.get(slug)
+            rows = [SimpleNamespace(id=record["id"])] if record else []
+            return FakeResult(rows)
+
+        if lower_sql.startswith("insert into navigation_links"):
+            group_id = int(params["group_id"])
+            slug = params["slug"]
+            key = (group_id, slug)
+            record = self.state.navigation_links.get(key)
+            if record is None:
+                self.state.sequences["navigation_links"] += 1
+                record = {
+                    "id": self.state.sequences["navigation_links"],
+                    "group_id": group_id,
+                    "slug": slug,
+                }
+            record.update(
+                parent_link_id=(int(params["parent_link_id"]) if params.get(
+                    "parent_link_id") is not None else None),
+                label=params["label"],
+                route_name=params.get("route_name"),
+                href_override=params.get("href_override"),
+                match_prefix=params.get("match_prefix"),
+                sort_order=int(params.get("sort_order", 0)),
+                icon=params.get("icon"),
+                tooltip=params.get("tooltip"),
+                required_roles=list(params.get("required_roles") or []),
+                is_enabled=bool(params.get("is_enabled", True)),
+                is_external=bool(params.get("is_external", False)),
+            )
+            self.state.navigation_links[key] = record
+            return FakeResult([])
+
+        if lower_sql.startswith("select id from navigation_links where group_id"):
+            group_id = int(params["group_id"])
+            slug = params["slug"]
+            record = self.state.navigation_links.get((group_id, slug))
+            rows = [SimpleNamespace(id=record["id"])] if record else []
+            return FakeResult(rows)
+
         if lower_sql.startswith("insert into financial_inputs"):
             key = (int(params["scenario_id"]), params["name"])
             record = self.state.financial_inputs.get(key)

tests/services/test_navigation_service.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, cast
+
+from fastapi import Request
+
+from services.navigation import NavigationService
+from services.repositories import NavigationRepository
+from services.session import AuthSession, SessionTokens
+from models import User
+
+
+@dataclass
+class StubNavigationLink:
+    id: int
+    slug: str
+    label: str
+    parent_link_id: int | None = None
+    route_name: str | None = None
+    href_override: str | None = None
+    match_prefix: str | None = None
+    sort_order: int = 0
+    icon: str | None = None
+    tooltip: str | None = None
+    required_roles: List[str] = field(default_factory=list)
+    is_enabled: bool = True
+    is_external: bool = False
+    children: List["StubNavigationLink"] = field(default_factory=list)
+
+
+@dataclass
+class StubNavigationGroup:
+    id: int
+    slug: str
+    label: str
+    sort_order: int = 0
+    icon: str | None = None
+    tooltip: str | None = None
+    is_enabled: bool = True
+    links: List[StubNavigationLink] = field(default_factory=list)
+
+
+class StubNavigationRepository(NavigationRepository):
+    def __init__(self, groups: Iterable[StubNavigationGroup]) -> None:
+        super().__init__(session=None)  # type: ignore[arg-type]
+        self._groups = list(groups)
+
+    def list_groups_with_links(self, *, include_disabled: bool = False):
+        if include_disabled:
+            return list(self._groups)
+        return [group for group in self._groups if group.is_enabled]
+
+
+class StubRequest:
+    def __init__(
+        self,
+        *,
+        path_params: Dict[str, str] | None = None,
+        query_params: Dict[str, str] | None = None,
+    ) -> None:
+        self.path_params = path_params or {}
+        self.query_params = query_params or {}
+        self._url_for_calls: List[tuple[str, Dict[str, str]]] = []
+
+    def url_for(self, name: str, **params: str) -> str:
+        self._url_for_calls.append((name, params))
+        if params:
+            suffix = "_".join(f"{key}-{value}" for key,
+                              value in sorted(params.items()))
+            return f"/{name}/{suffix}"
+        return f"/{name}"
+
+    @property
+    def url_for_calls(self) -> List[tuple[str, Dict[str, str]]]:
+        return list(self._url_for_calls)
+
+
+def _session(*, roles: Iterable[str], authenticated: bool = True) -> AuthSession:
+    tokens = SessionTokens(
+        access_token="token" if authenticated else None, refresh_token=None)
+    user = cast(User, object()) if authenticated else None
+    session = AuthSession(tokens=tokens, user=user, role_slugs=tuple(roles))
+    return session
+
+
+def test_build_sidebar_filters_links_by_role():
+    visible_link = StubNavigationLink(
+        id=1,
+        slug="projects",
+        label="Projects",
+        href_override="/projects",
+        required_roles=["viewer"],
+    )
+    hidden_link = StubNavigationLink(
+        id=2,
+        slug="admin",
+        label="Admin",
+        href_override="/admin",
+        required_roles=["admin"],
+    )
+    group = StubNavigationGroup(id=1, slug="workspace", label="Workspace", links=[
+                                visible_link, hidden_link])
+
+    service = NavigationService(StubNavigationRepository([group]))
+    dto = service.build_sidebar(
+        session=_session(roles=["viewer"]),
+        request=cast(Request, StubRequest()),
+    )
+
+    assert len(dto.groups) == 1
+    assert [link.label for link in dto.groups[0].links] == ["Projects"]
+    assert dto.roles == ("viewer",)
+
+
+def test_build_sidebar_appends_anonymous_role_for_guests():
+    link = StubNavigationLink(
+        id=1, slug="help", label="Help", href_override="/help")
+    group = StubNavigationGroup(
+        id=1, slug="account", label="Account", links=[link])
+
+    service = NavigationService(StubNavigationRepository([group]))
+    dto = service.build_sidebar(session=AuthSession.anonymous(), request=None)
+
+    assert dto.roles[-1] == "anonymous"
+    assert dto.groups[0].links[0].href.startswith("/")
+
+
+def test_build_sidebar_resolves_profitability_link_with_context():
+    link = StubNavigationLink(
+        id=1,
+        slug="profitability",
+        label="Profitability",
+        route_name="calculations.profitability_form",
+        href_override="/calculations/profitability",
+    )
+    group = StubNavigationGroup(
+        id=99, slug="insights", label="Insights", links=[link])
+
+    request = StubRequest(path_params={"project_id": "7", "scenario_id": "42"})
+    service = NavigationService(StubNavigationRepository([group]))
+
+    dto = service.build_sidebar(
+        session=_session(roles=["viewer"]),
+        request=cast(Request, request),
+    )
+
+    assert dto.groups[0].links[0].href == "/calculations.profitability_form/project_id-7_scenario_id-42"
+    assert request.url_for_calls[0][0] == "calculations.profitability_form"
+    assert request.url_for_calls[0][1] == {
+        "project_id": "7", "scenario_id": "42"}
+    assert dto.groups[0].links[0].match_prefix == dto.groups[0].links[0].href
+
+
+def test_build_sidebar_resolves_opex_link_with_context():
+    link = StubNavigationLink(
+        id=2,
+        slug="opex",
+        label="Opex",
+        route_name="calculations.opex_form",
+        href_override="/calculations/opex",
+    )
+    group = StubNavigationGroup(
+        id=5, slug="workspace", label="Workspace", links=[link])
+
+    request = StubRequest(path_params={"project_id": "3", "scenario_id": "9"})
+    service = NavigationService(StubNavigationRepository([group]))
+
+    dto = service.build_sidebar(
+        session=_session(roles=["analyst"]),
+        request=cast(Request, request),
+    )
+
+    href = dto.groups[0].links[0].href
+    assert href == "/calculations.opex_form/project_id-3_scenario_id-9"
+    assert request.url_for_calls[0][0] == "calculations.opex_form"
+    assert request.url_for_calls[0][1] == {
+        "project_id": "3", "scenario_id": "9"}
+
+
+def test_build_sidebar_uses_href_override_when_calculator_context_missing():
+    class ParamAwareStubRequest(StubRequest):
+        # type: ignore[override]
+        def url_for(self, name: str, **params: str) -> str:
+            if name in {
+                "calculations.opex_form",
+                "calculations.capex_form",
+            } and not params:
+                self._url_for_calls.append((name, params))
+                raise RuntimeError("missing params")
+            return super().url_for(name, **params)
+
+    link = StubNavigationLink(
+        id=3,
+        slug="capex",
+        label="Capex",
+        route_name="calculations.capex_form",
+        href_override="/calculations/capex",
+    )
+    group = StubNavigationGroup(
+        id=6, slug="workspace", label="Workspace", links=[link])
+
+    request = ParamAwareStubRequest()
+    service = NavigationService(StubNavigationRepository([group]))
+
+    dto = service.build_sidebar(
+        session=_session(roles=["analyst"]),
+        request=cast(Request, request),
+    )
+
+    assert dto.groups[0].links[0].href == "/calculations/capex"
+    assert request.url_for_calls[-1][0] == "calculations.capex_form"
+
+
+def test_build_sidebar_skips_disabled_links_unless_included():
+    enabled_link = StubNavigationLink(
+        id=1,
+        slug="projects",
+        label="Projects",
+        href_override="/projects",
+    )
+    disabled_link = StubNavigationLink(
+        id=2,
+        slug="reports",
+        label="Reports",
+        href_override="/reports",
+        is_enabled=False,
+    )
+    group = StubNavigationGroup(
+        id=5,
+        slug="workspace",
+        label="Workspace",
+        links=[enabled_link, disabled_link],
+    )
+
+    service = NavigationService(StubNavigationRepository([group]))
+
+    default_sidebar = service.build_sidebar(
+        session=_session(roles=["viewer"]),
+        request=cast(Request, StubRequest()),
+    )
+    assert [link.label for link in default_sidebar.groups[0].links] == ["Projects"]
+
+    full_sidebar = service.build_sidebar(
+        session=_session(roles=["viewer"]),
+        request=cast(Request, StubRequest()),
+        include_disabled=True,
+    )
+    assert [link.label for link in full_sidebar.groups[0].links] == [
+        "Projects", "Reports"]

tests/test_auth_routes.py

@@ -11,8 +11,8 @@ from sqlalchemy import select
 from sqlalchemy.orm import Session, sessionmaker
 
 from models import Role, User, UserRole
-from dependencies import get_auth_session, require_current_user
-from services.security import hash_password
+from dependencies import get_auth_session, get_jwt_settings, require_current_user
+from services.security import decode_access_token, hash_password
 from services.session import AuthSession, SessionTokens
 from tests.utils.security import random_password, random_token
 
@@ -334,6 +334,7 @@ class TestLoginFlowEndToEnd:
 
         # Override to anonymous for login
         app = cast(FastAPI, client.app)
+        original_override = app.dependency_overrides.get(get_auth_session)
         app.dependency_overrides[get_auth_session] = lambda: AuthSession.anonymous(
         )
         try:
@@ -347,14 +348,21 @@ class TestLoginFlowEndToEnd:
                 "location") == "http://testserver/"
             set_cookie_header = login_response.headers.get("set-cookie", "")
             assert "calminer_access_token=" in set_cookie_header
-
-            # Now with cookies, GET / should show dashboard
-            dashboard_response = client.get("/")
-            assert dashboard_response.status_code == 200
-            assert "Dashboard" in dashboard_response.text or "metrics" in dashboard_response.text
         finally:
             app.dependency_overrides.pop(get_auth_session, None)
 
+        access_cookie = client.cookies.get("calminer_access_token")
+        refresh_cookie = client.cookies.get("calminer_refresh_token")
+        assert access_cookie, "Access token cookie was not set"
+        assert refresh_cookie, "Refresh token cookie was not set"
+
+        jwt_settings = get_jwt_settings()
+        payload = decode_access_token(access_cookie, jwt_settings)
+        assert payload.sub == str(user.id)
+        assert payload.scopes == ["auth"], "Unexpected access token scopes"
+        if original_override is not None:
+            app.dependency_overrides[get_auth_session] = original_override
+
     def test_logout_redirects_to_login_and_clears_session(self, client: TestClient) -> None:
         # Assuming authenticated from conftest
         logout_response = client.get("/logout", follow_redirects=False)

tests/test_authorization_integration.py

@@ -90,9 +90,9 @@ class TestAuthenticationRequirements:
 
     def test_ui_project_list_requires_login(self, client, auth_session_context):
         with auth_session_context(None):
-            response = client.get("/projects/ui")
-
-        assert response.status_code == status.HTTP_401_UNAUTHORIZED
+            response = client.get("/projects/ui", follow_redirects=False)
+        assert response.status_code == status.HTTP_303_SEE_OTHER
+        assert response.headers["location"].endswith("/login")
 
 
 class TestRoleRestrictions:
@@ -194,7 +194,7 @@ class TestRoleRestrictions:
 
         assert response.status_code == status.HTTP_403_FORBIDDEN
         assert response.json()[
-            "detail"] == "Insufficient role permissions for this action."
+            "detail"] == "Insufficient permissions for this action."
 
     def test_ui_project_edit_accessible_to_manager(
         self,

tests/test_login_form_middleware.py

@@ -1,6 +1,7 @@
 from fastapi.testclient import TestClient
 
 from main import app
+from scripts.init_db import init_db
 
 
 def test_login_form_post_does_not_trigger_json_error():
@@ -8,6 +9,7 @@ def test_login_form_post_does_not_trigger_json_error():
     the JSON "Invalid JSON payload" error which indicates the middleware
     attempted to parse non-JSON bodies.
     """
+    init_db()
     client = TestClient(app)
 
     resp = client.post(

tests/test_project_scenario_models.py

@@ -43,9 +43,9 @@ def session(engine) -> Iterator[Session]:
 def test_project_scenario_cascade_deletes(session: Session) -> None:
     project = Project(name="Cascade Mine",
                       operation_type=MiningOperationType.OTHER)
-    scenario_a = Scenario(
+    Scenario(
         name="Base Case", status=ScenarioStatus.DRAFT, project=project)
-    scenario_b = Scenario(
+    Scenario(
         name="Expansion", status=ScenarioStatus.DRAFT, project=project)
 
     session.add(project)