BentBr · BentBr · Apr 20, 2026 · Apr 20, 2026 · Apr 20, 2026 · Apr 20, 2026
diff --git a/.githooks/pre-push b/.githooks/pre-push
@@ -24,12 +24,18 @@ GIT_HOOK_RUN_LINT="${GIT_HOOK_RUN_LINT:-1}"
 GIT_HOOK_LINT_CMD="${GIT_HOOK_LINT_CMD:-rdt lint}"
 GIT_HOOK_LINT_MAX_ERR_LINES="${GIT_HOOK_LINT_MAX_ERR_LINES:-50}"
 
+GIT_HOOK_RUN_KNIP="${GIT_HOOK_RUN_KNIP:-1}"
+GIT_HOOK_KNIP_CMD="${GIT_HOOK_KNIP_CMD:-rdt knip}"
+GIT_HOOK_KNIP_MAX_ERR_LINES="${GIT_HOOK_KNIP_MAX_ERR_LINES:-50}"
+
 GIT_HOOK_RUN_TS_BINDINGS="${GIT_HOOK_RUN_TS_BINDINGS:-1}"
 GIT_HOOK_TS_BINDINGS_CMD="${GIT_HOOK_TS_BINDINGS_CMD:-rdt generate-ts-check}"
 GIT_HOOK_TS_BINDINGS_MAX_ERR_LINES="${GIT_HOOK_TS_BINDINGS_MAX_ERR_LINES:-50}"
 
 GIT_HOOK_RUN_COMMIT_LINT="${GIT_HOOK_RUN_COMMIT_LINT:-1}"
 
+GIT_HOOK_RUN_BRANCH_NAME="${GIT_HOOK_RUN_BRANCH_NAME:-1}"
+
 log() {
     printf "[%s] %s\n" "$(date +%H:%M:%S)" "$*"
 }
@@ -130,8 +136,8 @@ normalize_bool_10() {
 load_env_overrides_all() {
     local root; root="$(repo_root)"
     local files=(".env.docker" ".env.local" ".env.docker.local")
-    local allowed=" GIT_HOOK_REMOTE GIT_HOOK_LOCK_FILE GIT_HOOK_RUN_FMT GIT_HOOK_FMT_CMD GIT_HOOK_FMT_MAX_ERR_LINES GIT_HOOK_RUN_CLIPPY GIT_HOOK_CLIPPY_CMD GIT_HOOK_CLIPPY_MAX_ERR_LINES GIT_HOOK_RUN_TEST GIT_HOOK_TEST_CMD GIT_HOOK_TEST_MAX_ERR_LINES GIT_HOOK_RUN_TEST_FE GIT_HOOK_TEST_FE_CMD GIT_HOOK_TEST_FE_MAX_ERR_LINES GIT_HOOK_RUN_LINT GIT_HOOK_LINT_CMD GIT_HOOK_LINT_MAX_ERR_LINES GIT_HOOK_RUN_TS_BINDINGS GIT_HOOK_TS_BINDINGS_CMD GIT_HOOK_TS_BINDINGS_MAX_ERR_LINES GIT_HOOK_RUN_COMMIT_LINT GIT_HOOK_SKIP "
-    local booleans=" GIT_HOOK_RUN_FMT GIT_HOOK_RUN_CLIPPY GIT_HOOK_RUN_TEST GIT_HOOK_RUN_TEST_FE GIT_HOOK_RUN_LINT GIT_HOOK_RUN_TS_BINDINGS GIT_HOOK_RUN_COMMIT_LINT GIT_HOOK_SKIP "
+    local allowed=" GIT_HOOK_REMOTE GIT_HOOK_LOCK_FILE GIT_HOOK_RUN_FMT GIT_HOOK_FMT_CMD GIT_HOOK_FMT_MAX_ERR_LINES GIT_HOOK_RUN_CLIPPY GIT_HOOK_CLIPPY_CMD GIT_HOOK_CLIPPY_MAX_ERR_LINES GIT_HOOK_RUN_TEST GIT_HOOK_TEST_CMD GIT_HOOK_TEST_MAX_ERR_LINES GIT_HOOK_RUN_TEST_FE GIT_HOOK_TEST_FE_CMD GIT_HOOK_TEST_FE_MAX_ERR_LINES GIT_HOOK_RUN_LINT GIT_HOOK_LINT_CMD GIT_HOOK_LINT_MAX_ERR_LINES GIT_HOOK_RUN_KNIP GIT_HOOK_KNIP_CMD GIT_HOOK_KNIP_MAX_ERR_LINES GIT_HOOK_RUN_TS_BINDINGS GIT_HOOK_TS_BINDINGS_CMD GIT_HOOK_TS_BINDINGS_MAX_ERR_LINES GIT_HOOK_RUN_COMMIT_LINT GIT_HOOK_RUN_BRANCH_NAME GIT_HOOK_SKIP "
+    local booleans=" GIT_HOOK_RUN_FMT GIT_HOOK_RUN_CLIPPY GIT_HOOK_RUN_TEST GIT_HOOK_RUN_TEST_FE GIT_HOOK_RUN_LINT GIT_HOOK_RUN_KNIP GIT_HOOK_RUN_TS_BINDINGS GIT_HOOK_RUN_COMMIT_LINT GIT_HOOK_RUN_BRANCH_NAME GIT_HOOK_SKIP "
 
     for f in "${files[@]}"; do
         local path="${root}/${f}"
@@ -208,6 +214,35 @@ ensure_clean_working_tree() {
     fi
 }
 
+validate_branch_name() {
+    local branch="$1"
+
+    if [[ "${GIT_HOOK_RUN_BRANCH_NAME}" != "1" ]]; then
+        return 0
+    fi
+
+    log "Validating branch name"
+
+    local regex='^(main|master|develop|(release-please|dependabot|renovate)(--|/).+|(feat|fix|hotfix|chore|docs|refactor|perf|test|build|ci|style|revert|release)/[a-z0-9][a-z0-9._-]*)$'
+
+    if [[ ! "$branch" =~ $regex ]]; then
+        log "Branch '${branch}' does not follow the naming convention."
+        log ""
+        log "Expected: <type>/<description>"
+        log "Types: feat, fix, hotfix, chore, docs, refactor, perf, test, build, ci, style, revert, release"
+        log "Description: lowercase alphanumeric + . _ - (must start alphanumeric; no uppercase)"
+        log "Examples:"
+        log "   feat/user-authentication"
+        log "   fix/token-expiration"
+        log "   hotfix/prod-crash-2026-04"
+        log ""
+        log "Exempt branches: main, master, develop, release-please--*, dependabot/*, renovate/*"
+        fail "Branch name validation failed"
+    fi
+
+    log "Branch name '${branch}' is valid"
+}
+
 validate_conventional_commits() {
     local base_branch="$1"
     local current_branch="$2"
@@ -390,6 +425,30 @@ run_lint() {
     log "ESLint (admin) passed"
 }
 
+run_knip() {
+    local tmp_file
+    tmp_file="$(mktemp)"
+
+    log "Running knip (unused-export / dead-code gate)"
+
+    set +e
+    ${GIT_HOOK_KNIP_CMD} 2>&1 | tee "${tmp_file}"
+    local knip_status=$?
+    set -e
+
+    if (( knip_status != 0 )); then
+        local total_lines
+        total_lines="$(wc -l < "${tmp_file}" | tr -d ' ')"
+        log "Knip errors (showing first ${GIT_HOOK_KNIP_MAX_ERR_LINES} of ${total_lines}):"
+        head -n "${GIT_HOOK_KNIP_MAX_ERR_LINES}" "${tmp_file}"
+        rm -f "${tmp_file}"
+        fail "Knip failed. Remove the unused exports/files it reported, or add a justified entry to fe/knip.json."
+    fi
+
+    rm -f "${tmp_file}"
+    log "Knip passed"
+}
+
 run_ts_bindings() {
     local tmp_file
     tmp_file="$(mktemp)"
@@ -435,6 +494,10 @@ run_quality_checks() {
         run_lint
     fi
 
+    if [[ "${GIT_HOOK_RUN_KNIP}" == "1" ]]; then
+        run_knip
+    fi
+
     if [[ "${GIT_HOOK_RUN_TS_BINDINGS}" == "1" ]]; then
         run_ts_bindings
     fi
@@ -452,6 +515,8 @@ main() {
     start_branch="$(get_current_branch_name)"
     log "Current branch: ${start_branch}"
 
+    validate_branch_name "${start_branch}"
+
     ensure_clean_working_tree
     fetch_remote_all
 

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -47,6 +47,83 @@ jobs:
           echo "backend=true" >> $GITHUB_OUTPUT
           echo "frontend=true" >> $GITHUB_OUTPUT
 
+  # ============================================================================
+  # Commit Lint - Validates Conventional Commits on every PR
+  # ============================================================================
+  commit-lint:
+    if: ${{ github.event_name == 'pull_request' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate Conventional Commits
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          conventional_pattern='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?(!)?: .+'
+          merge_pattern='^Merge '
+          invalid_commits=()
+          while IFS= read -r commit_sha; do
+            [[ -z "$commit_sha" ]] && continue
+            subject="$(git log -1 --format='%s' "$commit_sha")"
+            if [[ "$subject" =~ $merge_pattern ]]; then
+              continue
+            fi
+            if ! [[ "$subject" =~ $conventional_pattern ]]; then
+              invalid_commits+=("$commit_sha: $subject")
+            fi
+          done < <(git rev-list "$BASE_SHA..$HEAD_SHA")
+
+          if [[ ${#invalid_commits[@]} -gt 0 ]]; then
+            echo "::error::The following commits do not follow Conventional Commits format:"
+            for msg in "${invalid_commits[@]}"; do
+              echo "  - $msg"
+            done
+            echo ""
+            echo "Expected format: <type>[optional scope][!]: <description>"
+            echo "Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert"
+            echo "Examples:"
+            echo "  feat: add user authentication"
+            echo "  fix(auth): resolve token expiration issue"
+            echo "  feat!: breaking change to API"
+            exit 1
+          fi
+
+          echo "All commits follow Conventional Commits format"
+
+  # ============================================================================
+  # Branch Name Validation - Runs on every PR
+  # ============================================================================
+  branch-name:
+    if: ${{ github.event_name == 'pull_request' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate branch name
+        env:
+          BRANCH_NAME: ${{ github.head_ref }}
+        run: |
+          regex='^(main|master|develop|(release-please|dependabot|renovate)(--|/).+|(feat|fix|hotfix|chore|docs|refactor|perf|test|build|ci|style|revert|release)/[a-z0-9][a-z0-9._-]*)$'
+          if [[ ! "$BRANCH_NAME" =~ $regex ]]; then
+            echo "::error::Branch name '$BRANCH_NAME' does not follow the naming convention."
+            echo ""
+            echo "Expected: <type>/<description>"
+            echo "Types: feat, fix, hotfix, chore, docs, refactor, perf, test, build, ci, style, revert, release"
+            echo "Description: lowercase alphanumeric + . _ - (must start alphanumeric; no uppercase)"
+            echo ""
+            echo "Examples:"
+            echo "  feat/user-authentication"
+            echo "  fix/token-expiration"
+            echo "  hotfix/prod-crash-2026-04"
+            echo ""
+            echo "Exempt branches: main, master, develop, release-please--*, dependabot/*, renovate/*"
+            exit 1
+          fi
+          echo "Branch name '$BRANCH_NAME' is valid"
+
   # ============================================================================
   # Backend Jobs - Only run when backend files change
   # ============================================================================
@@ -304,13 +381,38 @@ jobs:
         with:
           workspaces: .
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: fe/package-lock.json
+
+      - name: Cache fe/node_modules
+        id: cache-node-modules
+        uses: actions/cache@v4
+        with:
+          path: fe/node_modules
+          key: ${{ runner.os }}-node-modules-${{ hashFiles('fe/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-modules-
+
+      - name: Install fe dependencies
+        if: steps.cache-node-modules.outputs.cache-hit != 'true'
+        working-directory: fe
+        run: npm ci
+
       - name: Generate TS bindings
         env:
           SQLX_OFFLINE: true
         run: |
           TS_RS_EXPORT_DIR=${{ github.workspace }}/fe/src/types/generated cargo test --workspace export_bindings 2>&1
           cargo run -p r_data_core_core --bin export_validation_constants > ./fe/src/types/generated/validation.ts
 
+      - name: Format generated bindings (prettier)
+        working-directory: fe
+        run: npx prettier --write --log-level warn 'src/types/generated/**/*.ts'
+
       - name: Check for stale bindings
         run: |
           if ! git diff --exit-code fe/src/types/generated/; then
@@ -381,6 +483,10 @@ jobs:
         working-directory: fe
         run: npm run lint
 
+      - name: Knip
+        working-directory: fe
+        run: npm run knip
+
   frontend-tests:
     needs: [changes, frontend-prepare]
     if: ${{ needs.changes.outputs.frontend == 'true' }}
@@ -647,6 +753,8 @@ jobs:
   ci-gate:
     needs:
       - changes
+      - branch-name
+      - commit-lint
       - backend-clippy
       - backend-format
       - backend-audit
@@ -661,6 +769,24 @@ jobs:
     if: ${{ always() }}
     runs-on: ubuntu-latest
     steps:
+      - name: Check branch name result
+        if: ${{ github.event_name == 'pull_request' }}
+        run: |
+          if [[ "${{ needs.branch-name.result }}" != "success" ]]; then
+            echo "Branch name check failed"
+            exit 1
+          fi
+          echo "Branch name check passed"
+
+      - name: Check commit lint result
+        if: ${{ github.event_name == 'pull_request' }}
+        run: |
+          if [[ "${{ needs.commit-lint.result }}" != "success" ]]; then
+            echo "Commit lint check failed"
+            exit 1
+          fi
+          echo "Commit lint check passed"
+
       - name: Check backend results
         if: ${{ needs.changes.outputs.backend == 'true' }}
         run: |

diff --git a/.rusty_dev_tool/config.toml b/.rusty_dev_tool/config.toml
@@ -37,11 +37,15 @@ no_docker_compose = true
         "description" = "Removes all E2E test data (e2e_* users, keys, roles, workflows, entity definitions, and dynamic tables) from the local database"
     [commands.generate-ts]
         "alias" = "generate-ts"
-        "execution" = "TS_RS_EXPORT_DIR=$(pwd)/fe/src/types/generated cargo test --workspace export_bindings 2>&1 && cargo run -p r_data_core_core --bin export_validation_constants > ./fe/src/types/generated/validation.ts"
+        "execution" = "TS_RS_EXPORT_DIR=$(pwd)/fe/src/types/generated cargo test --workspace export_bindings 2>&1 && cargo run -p r_data_core_core --bin export_validation_constants > ./fe/src/types/generated/validation.ts && docker compose exec -T node npx prettier --write --log-level warn 'src/types/generated/**/*.ts'"
         "description" = "Generates TypeScript type bindings and validation constants from Rust structs"
     [commands.generate-ts-check]
         "alias" = "generate-ts-check"
-        "execution" = "TS_RS_EXPORT_DIR=$(pwd)/fe/src/types/generated cargo test --workspace export_bindings 2>&1 && cargo run -p r_data_core_core --bin export_validation_constants > ./fe/src/types/generated/validation.ts && git diff --exit-code fe/src/types/generated/"
+        "execution" = "TS_RS_EXPORT_DIR=$(pwd)/fe/src/types/generated cargo test --workspace export_bindings 2>&1 && cargo run -p r_data_core_core --bin export_validation_constants > ./fe/src/types/generated/validation.ts && docker compose exec -T node npx prettier --write --log-level warn 'src/types/generated/**/*.ts' && git diff --exit-code fe/src/types/generated/"
         "description" = "Generates TS bindings and fails if any generated files differ from committed versions"
+    [commands.knip]
+        "alias" = "knip"
+        "execution" = "docker compose exec -T node npx knip"
+        "description" = "Runs knip to enforce that every generated/exported symbol is consumed (fails on unused files, exports, or deps)"
 # Mandatory node
 [environments]
diff --git a/README.md b/README.md
@@ -89,6 +89,15 @@ docker pull ghcr.io/bentbr/r-data-core-worker:latest
 docker pull ghcr.io/bentbr/r-data-core-maintenance:latest
 ```
 
+### Example deployments
+
+Runnable example setups for deploying RDataCore to common targets live in [`docs/examples/`](./docs/examples/):
+
+- **[Docker Compose](./docs/examples/docker-compose/)** — single-host deployment using pre-built images from GHCR.
+- **[Kubernetes + Longhorn](./docs/examples/kubernetes/)** — namespace-scoped manifests with Longhorn-backed persistent storage, Ingress, HPA, and a migrations Job.
+
+> These are **examples only, with no warranty**. Review before adapting to your environment.
+
 ## Configuration
 
 ### Required Environment Variables

diff --git a/crates/api/src/admin/api_keys/models.rs b/crates/api/src/admin/api_keys/models.rs
@@ -13,11 +13,11 @@ pub struct CreateApiKeyRequest {
     /// Name of the API key
     pub name: String,
     /// Optional description for the API key
+    #[serde(default)]
     pub description: Option<String>,
     /// Number of days until expiration (default: 365)
     #[serde(default)]
-    #[ts(type = "number | null")]
-    pub expires_in_days: Option<i64>,
+    pub expires_in_days: Option<u32>,
 }
 
 /// Response containing API key information

diff --git a/crates/api/src/admin/api_keys/routes.rs b/crates/api/src/admin/api_keys/routes.rs
@@ -184,7 +184,7 @@ pub async fn create_api_key(
     let description = req.description.clone().unwrap_or_default();
     let expires_in_days = req
         .expires_in_days
-        .map_or(365, |v| i32::try_from(v).unwrap_or(365));
+        .map_or(365, |v| i32::try_from(v).unwrap_or(i32::MAX));
 
     match service
         .create_api_key(&req.name, &description, creator_uuid, expires_in_days)

diff --git a/crates/api/src/admin/auth/models.rs b/crates/api/src/admin/auth/models.rs
@@ -8,10 +8,21 @@ use utoipa::ToSchema;
 use validator::Validate;
 
 /// Empty request body for endpoints that don't require any input
-#[derive(Debug, Deserialize, ToSchema, TS)]
-#[ts(export)]
+#[derive(Debug, Deserialize, ToSchema)]
 pub struct EmptyRequest {}
 
+/// Response body for `GET /admin/api/v1/auth/permissions`
+#[derive(Debug, Serialize, Deserialize, ToSchema, TS)]
+#[ts(export)]
+pub struct UserPermissionsResponse {
+    /// Whether the caller is a super admin (all permissions granted)
+    pub is_super_admin: bool,
+    /// Flat list of `namespace:permission_type` strings the caller holds
+    pub permissions: Vec<String>,
+    /// Router paths the caller is allowed to navigate to
+    pub allowed_routes: Vec<String>,
+}
+
 /// Refresh token request body
 #[derive(Debug, Deserialize, Serialize, ToSchema, TS)]
 #[ts(export)]
@@ -93,8 +104,7 @@ pub struct AdminLoginResponse {
 }
 
 /// Admin registration request body
-#[derive(Debug, Deserialize, ToSchema, Validate, TS)]
-#[ts(export)]
+#[derive(Debug, Deserialize, ToSchema, Validate)]
 pub struct AdminRegisterRequest {
     /// Username
     #[validate(length(min = 3, message = "Username must be at least 3 characters"))]
@@ -121,8 +131,7 @@ pub struct AdminRegisterRequest {
 }
 
 /// Admin registration response body
-#[derive(Debug, Serialize, ToSchema, TS)]
-#[ts(export)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct AdminRegisterResponse {
     /// User UUID
     pub uuid: String,