ci: add Hugging Face Space deployment pipeline

Add GitLab CI validation and production deploy flow for the private Hugging Face Docker Space.

- run pnpm check and build in the validate stage

- deploy prod branch commits to the Hugging Face Space repository

- document required Space settings, runtime secrets, CI variables and local Docker smoke test

.gitlab-ci.yml

@@ -0,0 +1,39 @@
+stages:
+  - validate
+  - deploy
+
+default:
+  interruptible: true
+
+validate:
+  stage: validate
+  image: node:24-alpine
+  cache:
+    key:
+      files:
+        - pnpm-lock.yaml
+    paths:
+      - .pnpm-store/
+  before_script:
+    - corepack enable
+    - pnpm config set store-dir .pnpm-store
+    - pnpm install --frozen-lockfile
+  script:
+    - pnpm check
+    - pnpm build
+
+deploy:huggingface:
+  stage: deploy
+  image: alpine:3.20
+  needs:
+    - validate
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "prod"'
+    - when: never
+  before_script:
+    - apk add --no-cache ca-certificates git
+    - git config --global user.email "${GITLAB_USER_EMAIL:-ci@hivetrace.local}"
+    - git config --global user.name "${GITLAB_USER_NAME:-GitLab CI}"
+  script:
+    - git remote add huggingface "https://${HF_USERNAME}:${HF_SPACE_TOKEN}@huggingface.co/spaces/${HF_SPACE_REPO}"
+    - git push huggingface "HEAD:main" --force

docs/huggingface-space-deploy.md

@@ -0,0 +1,134 @@
+# Hugging Face Space deploy
+
+Целевая схема:
+
+```text
+Corporate GitLab repository
+        ↓ GitLab CI
+Private Hugging Face Docker Space
+        ↓ CPU Basic / Free
+HiveTrace Leaderboard
+```
+
+## Hugging Face Space
+
+Space создается вручную один раз.
+
+Рекомендуемые настройки:
+
+- Visibility: `Private`
+- SDK: `Docker`
+- Hardware: `CPU Basic` / free
+- App port: `5173`
+
+В `README.md` проекта уже есть Space frontmatter:
+
+```yaml
+---
+title: HiveTrace Leaderboard
+emoji: 🛡️
+colorFrom: green
+colorTo: indigo
+sdk: docker
+app_port: 5173
+pinned: true
+---
+```
+
+## Runtime secrets and variables in Hugging Face
+
+В Space Settings нужно добавить runtime secret:
+
+```text
+HF_TOKEN=hf_...
+```
+
+Этот токен нужен приложению для чтения приватного Hugging Face bucket. Его нельзя делать
+`PUBLIC_*` переменной и нельзя коммитить в репозиторий.
+
+Variables:
+
+```text
+HF_BUCKET_ID=hivetrace/leaderboard_frontend_v2
+HF_BUCKET_PREFIX=latest
+HF_BUCKET_CACHE_TTL_MS=300000
+HF_BUCKET_REQUEST_TIMEOUT_MS=10000
+```
+
+Опционально:
+
+```text
+HF_BUCKET_ENDPOINT=https://huggingface.co
+```
+
+## GitLab CI variables
+
+В корпоративном GitLab нужно добавить CI/CD variables:
+
+```text
+HF_USERNAME=<huggingface-user-or-service-account-name>
+HF_SPACE_TOKEN=<huggingface-write-token-for-space-repo>
+HF_SPACE_REPO=<namespace>/<space-name>
+```
+
+Пример:
+
+```text
+HF_SPACE_REPO=hivetrace/guard-leaderboard
+```
+
+`HF_SPACE_TOKEN` должен иметь право записи в Space repository.
+
+Важно: `HF_SPACE_TOKEN` и runtime `HF_TOKEN` для чтения bucket лучше держать разными
+токенами.
+
+`HF_SPACE_TOKEN` в GitLab лучше пометить как masked/protected variable.
+
+## Deploy flow
+
+`.gitlab-ci.yml` делает два этапа:
+
+1. `validate`
+   - `pnpm install --frozen-lockfile`
+   - `pnpm check`
+   - `pnpm build`
+
+2. `deploy:huggingface`
+   - срабатывает только на ветке `prod`
+   - пушит текущий commit в private Hugging Face Space repository
+   - использует force push, потому что Hugging Face Space является deploy-репозиторием
+   - Space автоматически пересобирает Docker image после push
+
+## Production branch
+
+Продакшн-деплой запускается только из ветки `prod`.
+
+Типовой flow:
+
+```bash
+git checkout prod
+git merge main
+git push origin prod
+```
+
+После push в `prod` GitLab CI выполнит validate-этап и затем отправит этот commit в
+ветку `main` Hugging Face Space repository.
+
+## Local Docker smoke test
+
+Перед первым deploy желательно локально проверить Docker image:
+
+```bash
+docker build -t hivetrace-leaderboard .
+docker run --rm -p 5173:5173 \
+  -e HF_TOKEN=hf_... \
+  -e HF_BUCKET_ID=hivetrace/leaderboard_frontend_v2 \
+  -e HF_BUCKET_PREFIX=latest \
+  hivetrace-leaderboard
+```
+
+После запуска открыть:
+
+```text
+http://127.0.0.1:5173/
+```