fix(mobile): APK starts on Android 15+ 16 KB page devices and emulators

On an Android 16 emulator the release APK crashed at launch with
"Cannot read property 'NativeModule' of undefined": libexpo-modules-core.so
was missing for the ABI the device picked. Two build defects:

- librnskia.so was linked with 4 KB segment alignment (Skia 2.0.0-next.4
  lacks ANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES), so 16 KB page devices cannot
  load it; a pnpm patch adds the flag
- the APK carried incomplete x86, x86_64 and armeabi-v7a folders from the
  React Native libraries; an Expo config plugin keeps only arm64-v8a, the ABI
  the native modules are built for (the APK also halves in size)

scripts/check-apk.mjs now fails the release on another ABI, a missing core
library or a library not aligned to 16 KB.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitea/workflows/ci-db.yml

@@ -4,16 +4,19 @@
 name: ci / db
 
 on:
+  workflow_dispatch: # перезапуск вручную (например, после чистки раннера)
   push:
     branches: [main]
     paths:
       - 'services/api/**'
       - 'services/recommender/**'
+      - 'deploy/backup.sh'
       - '.gitea/workflows/ci-db.yml'
   pull_request:
     paths:
       - 'services/api/**'
       - 'services/recommender/**'
+      - 'deploy/backup.sh'
       - '.gitea/workflows/ci-db.yml'
 
 concurrency:
@@ -51,6 +54,23 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with: { go-version: "1.24", cache-dependency-path: services/api/go.sum }
+      # Контейнеры сервисов стартуют параллельно с job: без ожидания тесты иногда не находят даже DNS-имя postgres.
+      - name: Место на раннере и готовность Postgres, Redis, Meilisearch
+        run: |
+          # Диск раннера общий с контейнерами сервисов: при нехватке места Postgres падает посреди тестов.
+          free=$(df -Pm / | awk 'NR==2 {print $4}')
+          echo "свободно на раннере: ${free} МБ"
+          [ "$free" -ge 2048 ] || { echo "на раннере меньше 2 ГБ — почистите: docker system prune -af" >&2; exit 1; }
+          for svc in postgres:5432 redis:6379 meilisearch:7700; do
+            host=${svc%:*}; port=${svc#*:}
+            for i in $(seq 1 60); do
+              if getent hosts "$host" >/dev/null && timeout 2 bash -c "</dev/tcp/$host/$port" 2>/dev/null; then
+                echo "$svc готов"; break
+              fi
+              [ "$i" = 60 ] && { echo "$svc не поднялся за 2 минуты" >&2; exit 1; }
+              sleep 2
+            done
+          done
       - name: Go — миграции и запросы store
         working-directory: services/api
         run: go test -tags integration -count=1 -v ./internal/dbtest/
@@ -64,3 +84,26 @@ jobs:
         run: |
           uv sync --frozen
           uv run pytest -q tests/test_db_integration.py
+      # База уже наполнена сценариями выше — проверяем настоящий цикл копия → проверка → восстановление.
+      - name: Бэкап, проверка и восстановление (deploy/backup.sh)
+        env:
+          PGHOST: postgres
+          PGUSER: pipu
+          PGPASSWORD: pipu
+          PGDATABASE: pipu
+          BACKUP_DIR: /tmp/backups
+          VERIFY_EXACT: "1"
+        run: |
+          SUDO=$(command -v sudo || true)
+          $SUDO install -d /usr/share/postgresql-common/pgdg
+          $SUDO curl -fsSLo /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc
+          echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(. /etc/os-release && echo "$VERSION_CODENAME")-pgdg main"             | $SUDO tee /etc/apt/sources.list.d/pgdg.list >/dev/null
+          $SUDO apt-get update -qq && $SUDO apt-get install -y -qq postgresql-client-17 >/dev/null
+          export PATH=/usr/lib/postgresql/17/bin:$PATH
+          before=$(psql -Atc "SELECT count(*) FROM tracks")
+          file=$(bash deploy/backup.sh once)
+          bash deploy/backup.sh verify "$file"
+          bash deploy/backup.sh restore "$file"
+          after=$(psql -Atc "SELECT count(*) FROM tracks")
+          echo "tracks: $before → $after"
+          test "$before" = "$after"

.gitea/workflows/ci-mobile.yml

@@ -2,6 +2,7 @@
 name: ci / mobile
 
 on:
+  workflow_dispatch: # перезапуск вручную (например, после чистки раннера)
   push:
     branches: [main]
     paths:

.gitea/workflows/release.yml

@@ -48,6 +48,8 @@ jobs:
   android:
     name: android (APK в релиз)
     needs: release
+    # Обычно 10–15 минут; дольше — значит, сборка упёрлась в память, лучше упасть, чем держать раннер.
+    timeout-minutes: 60
     runs-on: ubuntu-latest
     # Постоянные кэши на хосте раннера: дистрибутив и зависимости Gradle, его build cache, Android SDK и NDK
     # переживают job (−4 мин на релиз). Работают, если в config.yaml раннера разрешены тома
@@ -60,7 +62,7 @@ jobs:
       image: docker.gitea.com/runner-images:ubuntu-latest
       # Жёсткие пределы контейнера: сборка не должна забирать всю VM раннера (а через неё — хост гипервизора).
       # Своп запрещён (memory-swap = memory): лучше OOM внутри контейнера, чем подвисший хост.
-      options: --cpus=3 --memory=6g --memory-swap=6g
+      options: --cpus=3 --memory=7g --memory-swap=7g
       volumes:
         - /opt/ci-cache/gradle:/root/.gradle
         - /opt/ci-cache/android:/root/.android
@@ -106,6 +108,8 @@ jobs:
           # CMake / ninja нативной части React Native по умолчанию берут все ядра — ограничиваем.
           CMAKE_BUILD_PARALLEL_LEVEL: "2"
           NINJAFLAGS: "-j2"
+          # JS-бандл (Metro) собирается внутри Gradle отдельным node — не даём ему разрастись.
+          NODE_OPTIONS: "--max-old-space-size=1536"
         # Только arm64-v8a: C++-часть React Native собирается под каждую ABI, и четыре ABI
         # вместе с NDK (~2.5 ГБ) не помещаются на диск раннера. arm64 — все устройства с 2017+.
         # Память: на раннере 8 ГБ, и без ограничений Gradle + демон Kotlin + Metro вызывают OOM killer.
@@ -120,7 +124,7 @@ jobs:
           cd android
           # nice / ionice: сборка уступает CPU и диск всему остальному на машине
           gradle=(nice -n 19 ionice -c 3 ./gradlew --max-workers=2 --build-cache -PreactNativeArchitectures=arm64-v8a
-            -Pkotlin.compiler.execution.strategy=in-process -Dorg.gradle.jvmargs="-Xmx2560m -XX:MaxMetaspaceSize=512m")
+            -Pkotlin.compiler.execution.strategy=in-process -Dorg.gradle.jvmargs="-Xmx2048m -XX:MaxMetaspaceSize=512m")
           # Без New Architecture (app.config.ts) CMake приложения не собирается — отдельный codegen не нужен.
           if grep -q '^newArchEnabled=true' gradle.properties; then
             "${gradle[@]}" generateCodegenArtifactsFromSchema
@@ -139,6 +143,11 @@ jobs:
           fi
           ./gradlew --stop
 
+      # Только arm64-v8a, все нужные .so на месте и выровнены по 16 КБ — иначе APK падает при запуске
+      # на части устройств (Android 15+ с 16 КБ страницами, эмуляторы x86).
+      - name: Проверка APK (ABI, 16 КБ страницы)
+        run: node scripts/check-apk.mjs apps/mobile/android/app/build/outputs/apk/release/app-release.apk
+
       - name: Диагностика сбоя (диск, память, OOM)
         if: failure()
         run: |

api/openapi.yaml

@@ -1006,6 +1006,24 @@ paths:
                 $ref: "#/components/schemas/SearchResults"
         default:
           $ref: "#/components/responses/Problem"
+  /api/v1/admin/library/analysis/retry:
+    post:
+      operationId: retryAnalysis
+      tags: [library]
+      summary: Вернуть в очередь треки, которые не удалось проанализировать (admin)
+      responses:
+        "200":
+          description: Сколько задач снова в очереди
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [requeued]
+                properties:
+                  requeued:
+                    type: integer
+        default:
+          $ref: "#/components/responses/Problem"
   /api/v1/admin/search/reindex:
     post:
       operationId: reindexSearch
@@ -1256,6 +1274,38 @@ paths:
           description: Снято
         default:
           $ref: "#/components/responses/Problem"
+  /api/v1/onboarding:
+    get:
+      operationId: getOnboarding
+      tags: [wave]
+      summary: Онбординг вкуса — исполнители и жанры библиотеки для выбора
+      description: |
+        `required` — показать онбординг: пользователь его не проходил и не пропускал, а своей истории почти нет.
+      responses:
+        "200":
+          description: Варианты и состояние
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Onboarding"
+        default:
+          $ref: "#/components/responses/Problem"
+  /api/v1/me/onboarding:
+    put:
+      operationId: saveOnboarding
+      tags: [wave]
+      summary: Сохранить выбор онбординга (или пропуск — пустые списки)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OnboardingChoice"
+      responses:
+        "204":
+          description: Сохранено
+        default:
+          $ref: "#/components/responses/Problem"
   /api/v1/wave/options:
     get:
       operationId: getWaveOptions
@@ -1347,6 +1397,7 @@ paths:
     get:
       operationId: getAndroidLatest
       tags: [app]
+      security: [] # публично: страница /android раздаёт приложение без входа
       summary: Последняя версия Android-приложения (из релизов Gitea через сервер)
       description: |
         Сервер сам опрашивает Gitea своим токеном и кэширует ответ на 10 минут, поэтому приложению
@@ -1364,6 +1415,7 @@ paths:
     get:
       operationId: downloadAndroidApk
       tags: [app]
+      security: []
       summary: APK версии (кэшируется на сервере, поддерживает Range для докачки)
       parameters:
         - name: version
@@ -1442,6 +1494,59 @@ components:
           schema:
             $ref: "#/components/schemas/Problem"
   schemas:
+    Onboarding:
+      type: object
+      required: [required, artists, genres]
+      properties:
+        required:
+          type: boolean
+        artists:
+          type: array
+          items:
+            type: object
+            required: [id, name, track_count, cover_url, cover_colors]
+            properties:
+              id:
+                type: string
+                format: uuid
+              name:
+                type: string
+              track_count:
+                type: integer
+              cover_url:
+                type: string
+                nullable: true
+                description: Обложка самого большого альбома исполнителя
+              cover_colors:
+                type: array
+                items:
+                  type: string
+        genres:
+          type: array
+          items:
+            type: object
+            required: [name, track_count]
+            properties:
+              name:
+                type: string
+              track_count:
+                type: integer
+    OnboardingChoice:
+      type: object
+      required: [artist_ids, genres]
+      properties:
+        artist_ids:
+          type: array
+          maxItems: 50
+          items:
+            type: string
+            format: uuid
+        genres:
+          type: array
+          maxItems: 30
+          items:
+            type: string
+            maxLength: 100
     UserRef:
       type: object
       required: [id, username]
@@ -1909,6 +2014,10 @@ components:
         web_player:
           type: string
           enum: [bar, island]
+        search_position:
+          type: string
+          enum: [center, left, right]
+          description: Где в топбаре веба поиск (по умолчанию center)
         mobile_player:
           type: string
           enum: [cover, wave]
@@ -2996,7 +3105,7 @@ components:
           description: Рекомендатель недоступен — пачка собрана упрощённо (лайки, любимые исполнители)
     AnalysisStatus:
       type: object
-      required: [queued, running, done, failed, analyzer_ver]
+      required: [queued, running, done, failed, analyzer_ver, top_error]
       properties:
         queued:
           type: integer
@@ -3009,9 +3118,13 @@ components:
         analyzer_ver:
           type: string
           nullable: true
+        top_error:
+          type: string
+          nullable: true
+          description: Самая частая ошибка среди неудавшихся — подсказка, что чинить
     WaveMetrics:
       type: object
-      required: [served, listen_through_rate, early_skip_rate, like_rate, sessions]
+      required: [served, listen_through_rate, early_skip_rate, like_rate, sessions, by_model]
       description: Метрики волны за 7 дней
       properties:
         served:
@@ -3028,6 +3141,28 @@ components:
           description: Лайков на 100 треков
         sessions:
           type: integer
+        by_model:
+          type: array
+          description: Те же метрики по версии модели показа (v1 / ALS / ранжировщик) — сравнение онлайн
+          items:
+            $ref: '#/components/schemas/WaveModelMetrics'
+    WaveModelMetrics:
+      type: object
+      required: [model_ver, served, listen_through_rate, early_skip_rate, like_rate]
+      properties:
+        model_ver:
+          type: string
+        served:
+          type: integer
+        listen_through_rate:
+          type: number
+          nullable: true
+        early_skip_rate:
+          type: number
+          nullable: true
+        like_rate:
+          type: number
+          nullable: true
     AndroidRelease:
       type: object
       required: [version, version_code, notes_md, size, sha256, download_url, min_supported]

apps/mobile/app.config.ts

@@ -31,6 +31,8 @@ export default ({ config }: ConfigContext): ExpoConfig => ({
     // Сервер часто живёт в домашней сети без TLS (http://192.168.1.10:8080), а release-сборка
     // Android по умолчанию запрещает незашифрованный HTTP.
     ['expo-build-properties', { android: { usesCleartextTraffic: true } }],
+    // APK только под arm64-v8a — та же ABI, под которую собираются нативные модули (plugins/withArm64Only.js).
+    './plugins/withArm64Only',
   ],
   extra: { versionCode },
   experiments: { typedRoutes: false },

apps/mobile/plugins/withArm64Only.js

@@ -0,0 +1,18 @@
+// Только arm64-v8a в APK. Наши нативные модули (Expo, Skia, Reanimated) собираются под одну ABI
+// (-PreactNativeArchitectures=arm64-v8a в release.yml), а готовые библиотеки React Native приносят
+// каталоги всех ABI. Без фильтра x86/x86_64-эмулятор и 32-битные устройства выбирают неполный каталог
+// и падают при старте: «couldn't find DSO to load: libexpo-modules-core.so».
+const { withAppBuildGradle } = require('expo/config-plugins');
+
+const MARKER = '// pipu: arm64-v8a only';
+
+module.exports = function withArm64Only(config) {
+  return withAppBuildGradle(config, (cfg) => {
+    if (cfg.modResults.contents.includes(MARKER)) return cfg;
+    cfg.modResults.contents = cfg.modResults.contents.replace(
+      /defaultConfig\s*\{/,
+      (m) => `${m}\n        ${MARKER}\n        ndk { abiFilters "arm64-v8a" }`,
+    );
+    return cfg;
+  });
+};

apps/mobile/src/app/(tabs)/index.tsx

@@ -117,7 +117,7 @@ function Chips({
                 height: 38,
                 paddingHorizontal: 14,
                 borderRadius: 999,
-                backgroundColor: on ? colors.accent : colors.surface2,
+                backgroundColor: on ? colors['accent-fill'] : colors.surface2,
                 borderWidth: 1,
                 borderColor: on ? colors.accent : colors.line,
               }}

apps/mobile/src/ui/kit.tsx

@@ -107,7 +107,7 @@ export function Button({
 }) {
   const s = useStyles();
   const colors = useColors();
-  const bg = { primary: colors.accent, secondary: colors.surface3, ghost: 'transparent', danger: colors['danger-soft'] }[variant];
+  const bg = { primary: colors['accent-fill'], secondary: colors.surface3, ghost: 'transparent', danger: colors['danger-soft'] }[variant];
   const fg = { primary: '#fff', secondary: colors.text, ghost: colors.text2, danger: colors.danger }[variant];
   return (
     <Pressable
@@ -282,7 +282,7 @@ export function Segmented<T extends string>({
           onPress={() => onChange(o.value)}
           accessibilityRole="tab"
           accessibilityState={{ selected: value === o.value }}
-          style={[s.segment, value === o.value && { backgroundColor: colors.accent }]}
+          style={[s.segment, value === o.value && { backgroundColor: colors['accent-fill'] }]}
         >
           <Text style={{ color: value === o.value ? '#fff' : colors.text2, fontWeight: '600', fontSize: 13 }}>{o.label}</Text>
         </Pressable>

apps/web/Dockerfile

@@ -8,6 +8,8 @@ WORKDIR /repo
 # Сначала только манифесты workspace: слой с установкой зависимостей пересобирается лишь при их изменении,
 # а не при любой правке кода. Новый пакет в apps/ или packages/ — добавить его package.json сюда.
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+# pnpm-патчи зависимостей (lockfile ссылается на них, без них --frozen-lockfile падает)
+COPY patches/ patches/
 COPY apps/web/package.json apps/web/
 COPY apps/mobile/package.json apps/mobile/
 COPY packages/api-client/package.json packages/api-client/

apps/web/src/App.test.tsx

@@ -250,7 +250,7 @@ describe('player', () => {
     const alice = makeUser('alice', 'user');
     const { user, api } = await renderApp([alice], '/album/00000000-0000-4000-8000-0000000000bb', { signedInAs: alice });
 
-    const row = (await screen.findByText('Закрой за мной дверь')).closest('[role="row"]')!;
+    const row = (await screen.findByText('Закрой за мной дверь')).closest('[role="listitem"]')!;
     await user.click(row);
     const bar = screen.getByRole('contentinfo', { name: 'Плеер' });
     await waitFor(() => expect(within(bar).getByText('Закрой за мной дверь')).toBeInTheDocument());

apps/web/src/app/router.tsx

@@ -21,6 +21,7 @@ import { AlbumPage } from '../pages/AlbumPage';
 import { ArtistPage } from '../pages/ArtistPage';
 import { CollectionPage } from '../pages/CollectionPage';
 import { HomePage } from '../pages/HomePage';
+import { AppDownloadPage } from '../pages/AppDownloadPage';
 import { LoginPage } from '../pages/LoginPage';
 import { SearchPage, type SearchType } from '../pages/SearchPage';
 import { SettingsPage } from '../pages/SettingsPage';
@@ -59,6 +60,9 @@ const rootRoute = createRootRouteWithContext<RouterContext>()({
   errorComponent: RouteError,
 });
 
+// Публичная: ссылку на приложение отправляют тем, у кого ещё нет аккаунта на этом устройстве.
+const androidAppRoute = createRoute({ getParentRoute: () => rootRoute, path: '/android', component: AppDownloadPage });
+
 const loginRoute = createRoute({
   getParentRoute: () => rootRoute,
   path: '/login',
@@ -233,6 +237,7 @@ const adminSettingsRoute = createRoute({
 });
 
 const routeTree = rootRoute.addChildren([
+  androidAppRoute,
   loginRoute,
   setupAdminRoute,
   setupPasswordRoute,

apps/web/src/entities/catalog.tsx

@@ -132,7 +132,7 @@ export function TrackList({
   const discs = new Set(tracks.map((tr) => tr.disc_no ?? 1));
   let lastDisc: number | null = null;
   return (
-    <div className={s.tracks} role="table" aria-label={t('search.tracks')}>
+    <div className={s.tracks} role="list" aria-label={t('search.tracks')}>
       {tracks.map((tr, i) => {
         const disc = tr.disc_no ?? 1;
         const header = numbered && discs.size > 1 && disc !== lastDisc;
@@ -145,7 +145,7 @@ export function TrackList({
           <Fragment key={`${tr.id}-${i}`}>
             {header && <div className={s.disc}>{t('catalog.disc', { n: disc })}</div>}
             <div
-              role="row"
+              role="listitem"
               tabIndex={tr.available ? 0 : -1}
               aria-current={isCurrent || undefined}
               className={cx(s.track, !tr.available && s.unavailable, isCurrent && s.current)}

apps/web/src/pages/AppDownloadPage.tsx

@@ -0,0 +1,70 @@
+import { useQuery } from '@tanstack/react-query';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useSession } from '../app/session';
+import { formatBytes } from '../shared/lib/format';
+import { checkIcon, copyIcon, downloadIcon } from '../shared/ui/icons';
+import { Icon } from '../shared/ui/ui';
+import { AuthLayout } from './AuthLayout';
+import s from './auth.module.css';
+
+/**
+ * Публичная страница Android-приложения (/android): ссылку можно просто отправить человеку.
+ * APK — последний релиз, который сервер сам берёт из Gitea (docs/mobile.md#самообновление).
+ */
+export function AppDownloadPage() {
+  const { t, i18n } = useTranslation(['auth', 'common']);
+  const session = useSession();
+  const [copied, setCopied] = useState(false);
+  const latest = useQuery({
+    queryKey: ['android-latest'],
+    queryFn: async () => (await session.client.GET('/api/v1/app/android/latest')).data ?? null,
+    staleTime: 10 * 60_000,
+  });
+  const server = location.origin;
+  const copy = () =>
+    void navigator.clipboard?.writeText(server).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    });
+  const r = latest.data;
+
+  return (
+    <AuthLayout footer={<a href="/login">{t('app.to_login')}</a>}>
+      <span className={s.badge}>Android</span>
+      <h1>{t('app.title')}</h1>
+      <p className={s.lead}>{t('app.subtitle')}</p>
+      {latest.isPending ? null : r ? (
+        <>
+          <a className={s.download} href={r.download_url} download>
+            <Icon src={downloadIcon} size={22} />
+            <span>
+              {t('app.download')}
+              <span className={s.downloadMeta}>
+                {t('app.version', { version: r.version })} · {formatBytes(r.size, i18n.language)}
+              </span>
+            </span>
+          </a>
+          <ol className={s.steps}>
+            <li>{t('app.step_install')}</li>
+            <li>
+              {t('app.step_server')}
+              <button type="button" className={s.server} onClick={copy} aria-label={t('app.copy_server')}>
+                <code>{server}</code>
+                <Icon src={copied ? checkIcon : copyIcon} size={16} />
+              </button>
+            </li>
+            <li>{t('app.step_updates')}</li>
+          </ol>
+          <details className={s.details}>
+            <summary>{t('app.checksum')}</summary>
+            <code>{r.sha256}</code>
+          </details>
+        </>
+      ) : (
+        <div className={s.hint}>{t('app.unavailable')}</div>
+      )}
+    </AuthLayout>
+  );
+}

apps/web/src/pages/HomePage.tsx

@@ -1,5 +1,5 @@
 import { unwrap } from '@pipu/core';
-import { useQuery } from '@tanstack/react-query';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
@@ -24,6 +24,7 @@ import {
 import { cx, FormError, Icon } from '../shared/ui/ui';
 import { WaveButton } from '../widgets/wave/WaveButton';
 import s from './home.module.css';
+import { Onboarding } from './Onboarding';
 
 /** Иконки Material Symbols по именам из /wave/options. */
 const ICONS: Record<string, string> = {
@@ -44,8 +45,28 @@ const WAVE_COLORS: [string, string, string] = ['#2F80FF', '#7C5CFF', '#35D3FF'];
 
 type Tr = (key: string) => string;
 
-/** Главная (раскладка Center): кнопка «Моя волна» и под ней выбор занятия и настроения. */
+/** Главная: для нового пользователя без истории — сначала онбординг вкуса, затем волна. */
 export function HomePage() {
+  const session = useSession();
+  const queryClient = useQueryClient();
+  const onboarding = useQuery({
+    queryKey: ['onboarding'],
+    queryFn: async () => unwrap(await session.client.GET('/api/v1/onboarding')),
+    staleTime: Infinity,
+  });
+  if (onboarding.data?.required) {
+    return (
+      <Onboarding
+        options={onboarding.data}
+        onDone={() => queryClient.setQueryData(['onboarding'], { ...onboarding.data, required: false })}
+      />
+    );
+  }
+  return <WaveHome />;
+}
+
+/** Главная (раскладка Center): кнопка «Моя волна» и под ней выбор занятия и настроения. */
+function WaveHome() {
   const { t } = useTranslation();
   const tr = t as unknown as Tr;
   const session = useSession();

apps/web/src/pages/LoginPage.tsx

@@ -37,7 +37,15 @@ export function LoginPage() {
   };
 
   return (
-    <AuthLayout footer={info.data ? `pipu ${info.data.version}` : undefined}>
+    <AuthLayout
+      footer={
+        info.data ? (
+          <>
+            pipu {info.data.version} · <a href="/android">{t('app.link')}</a>
+          </>
+        ) : undefined
+      }
+    >
       <h1>{t('login.title')}</h1>
       <p className={s.lead}>{t('login.subtitle')}</p>
       {info.data?.bootstrap_required && <div className={s.hint}>{t('login.bootstrap_hint')}</div>}

apps/web/src/pages/Onboarding.tsx

@@ -0,0 +1,113 @@
+import type { components } from '@pipu/api-client';
+import { unwrap } from '@pipu/core';
+import { useMutation } from '@tanstack/react-query';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useSession } from '../app/session';
+import { Cover } from '../entities/catalog';
+import { useErrorText } from '../shared/lib/errors';
+import { checkIcon } from '../shared/ui/icons';
+import { Button, cx, FormError, Icon } from '../shared/ui/ui';
+import s from './onboarding.module.css';
+
+type Options = components['schemas']['Onboarding'];
+
+/** Минимум исполнителей, чтобы волне было от чего оттолкнуться. */
+const MIN_ARTISTS = 3;
+
+/**
+ * Онбординг вкуса (docs/recommendations.md#7): исполнители и жанры библиотеки — начальный вкус «Моей волны»,
+ * пока своей истории почти нет. Пропуск тоже запоминается: второй раз не спросим.
+ */
+export function Onboarding({ options, onDone }: { options: Options; onDone: () => void }) {
+  const { t } = useTranslation();
+  const session = useSession();
+  const errorText = useErrorText();
+  const [artists, setArtists] = useState<Set<string>>(new Set());
+  const [genres, setGenres] = useState<Set<string>>(new Set());
+  const save = useMutation({
+    mutationFn: async (skip: boolean) =>
+      unwrap(
+        await session.client.PUT('/api/v1/me/onboarding', {
+          body: skip ? { artist_ids: [], genres: [] } : { artist_ids: [...artists], genres: [...genres] },
+        }),
+      ),
+    onSuccess: onDone,
+  });
+  // Функциональное обновление: быстрые нажатия подряд не теряют выбор.
+  const toggle = (update: (fn: (prev: Set<string>) => Set<string>) => void, key: string) =>
+    update((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  const enough = artists.size >= MIN_ARTISTS || (artists.size > 0 && genres.size > 0);
+
+  return (
+    <div className={s.page}>
+      <header className={s.head}>
+        <h1>{t('onboarding.title')}</h1>
+        <p>{t('onboarding.subtitle')}</p>
+      </header>
+
+      <section aria-label={t('onboarding.artists')}>
+        <h2 className={s.label}>{t('onboarding.artists')}</h2>
+        <div className={s.artists}>
+          {options.artists.map((a) => {
+            const on = artists.has(a.id);
+            return (
+              <button
+                key={a.id}
+                type="button"
+                className={cx(s.artist, on && s.on)}
+                aria-pressed={on}
+                onClick={() => toggle(setArtists, a.id)}
+              >
+                <span className={s.avatar}>
+                  <Cover album={{ id: a.id, cover_url: a.cover_url, cover_colors: a.cover_colors }} size={96} round />
+                  {on && (
+                    <span className={s.check}>
+                      <Icon src={checkIcon} size={22} />
+                    </span>
+                  )}
+                </span>
+                <span className={s.name}>{a.name}</span>
+              </button>
+            );
+          })}
+        </div>
+      </section>
+
+      {options.genres.length > 0 && (
+        <section aria-label={t('onboarding.genres')}>
+          <h2 className={s.label}>{t('onboarding.genres')}</h2>
+          <div className={s.genres}>
+            {options.genres.map((g) => (
+              <button
+                key={g.name}
+                type="button"
+                className={s.genre}
+                aria-pressed={genres.has(g.name)}
+                onClick={() => toggle(setGenres, g.name)}
+              >
+                {g.name}
+              </button>
+            ))}
+          </div>
+        </section>
+      )}
+
+      <FormError>{save.error ? errorText(save.error) : null}</FormError>
+      <div className={s.actions}>
+        <Button variant="ghost" busy={save.isPending && save.variables} onClick={() => save.mutate(true)}>
+          {t('onboarding.skip')}
+        </Button>
+        <Button variant="primary" busy={save.isPending && !save.variables} disabled={!enough} onClick={() => save.mutate(false)}>
+          {enough ? t('onboarding.done') : t('onboarding.pick_more', { count: MIN_ARTISTS - artists.size })}
+        </Button>
+      </div>
+    </div>
+  );
+}

apps/web/src/pages/SettingsPage.tsx

@@ -126,6 +126,19 @@ function AppearanceSection() {
           ]}
         />
       </div>
+      <div className={s.settingRow}>
+        <span>{t('settings.search_position')}</span>
+        <Segmented<'left' | 'center' | 'right'>
+          label={t('settings.search_position')}
+          value={user.ui_prefs.search_position ?? 'center'}
+          onChange={(v) => void setPrefs({ search_position: v })}
+          options={[
+            { value: 'left', label: t('settings.search_left') },
+            { value: 'center', label: t('settings.search_center') },
+            { value: 'right', label: t('settings.search_right') },
+          ]}
+        />
+      </div>
       <div className={s.settingRow}>
         <span>{t('settings.ambient')}</span>
         <Segmented<'on' | 'off'>

apps/web/src/pages/admin/LibraryPage.tsx

@@ -1,5 +1,6 @@
 import { unwrap } from '@pipu/core';
-import { useMutation, useQuery } from '@tanstack/react-query';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useId } from 'react';
 import { useTranslation } from 'react-i18next';
 
 import { useSession, useUser } from '../../app/session';
@@ -31,6 +32,11 @@ export function LibraryPage() {
   const reindex = useMutation({
     mutationFn: async () => unwrap(await session.client.POST('/api/v1/admin/search/reindex')),
   });
+  const queryClient = useQueryClient();
+  const retry = useMutation({
+    mutationFn: async () => unwrap(await session.client.POST('/api/v1/admin/library/analysis/retry')),
+    onSuccess: () => void queryClient.invalidateQueries({ queryKey: ['library-status'] }),
+  });
   const d = status.data;
   const tiles = d
     ? ([
@@ -76,7 +82,19 @@ export function LibraryPage() {
               total: d.analysis.done + d.analysis.queued + d.analysis.running + d.analysis.failed,
             })}
           />
-          {d.analysis.failed > 0 && <span className={l.scanError}>{t('library.analysis_failed', { count: d.analysis.failed })}</span>}
+          {d.analysis.failed > 0 && (
+            <div className={l.retryRow}>
+              <span className={l.scanError}>
+                {t('library.analysis_failed', { count: d.analysis.failed })}
+                {d.analysis.top_error && <span className={l.errorDetail}>{d.analysis.top_error}</span>}
+              </span>
+              {admin && (
+                <Button variant="secondary" icon={refreshIcon} busy={retry.isPending} onClick={() => retry.mutate()}>
+                  {t('library.analysis_retry')}
+                </Button>
+              )}
+            </div>
+          )}
           {d.analysis.analyzer_ver && <span className={l.scanSummary}>{t('library.analyzer', { ver: d.analysis.analyzer_ver })}</span>}
         </section>
       )}
@@ -99,6 +117,33 @@ export function LibraryPage() {
               </div>
             ))}
           </div>
+          {d.wave.by_model.length > 1 && (
+            <div className={s.tableWrap}>
+              <table className={s.table}>
+                <caption className={s.muted}>{t('library.wave_by_model')}</caption>
+                <thead>
+                  <tr>
+                    <th scope="col">{t('library.wave_model')}</th>
+                    <th scope="col">{t('library.wave_served')}</th>
+                    <th scope="col">{t('library.wave_listen')}</th>
+                    <th scope="col">{t('library.wave_early_skip')}</th>
+                    <th scope="col">{t('library.wave_likes')}</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {d.wave.by_model.map((m) => (
+                    <tr key={m.model_ver}>
+                      <td>{m.model_ver || '—'}</td>
+                      <td>{m.served.toLocaleString()}</td>
+                      <td>{pct(m.listen_through_rate)}</td>
+                      <td>{pct(m.early_skip_rate)}</td>
+                      <td>{m.like_rate === null ? '—' : m.like_rate.toFixed(1)}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
         </section>
       )}
       {d && d.sources.length > 0 && (
@@ -133,10 +178,13 @@ const pct = (v: number | null) => (v === null ? '—' : `${Math.round(v * 100)}%
 
 function ScanLineBar({ done, total, label }: { done: number; total: number; label: string }) {
   const value = total > 0 ? Math.round((done / total) * 100) : 0;
+  const id = useId();
   return (
     <div className={l.scan}>
-      <div className={l.scanText}>{label}</div>
-      <div className={l.bar} role="progressbar" aria-valuenow={value} aria-valuemin={0} aria-valuemax={100}>
+      <div className={l.scanText} id={id}>
+        {label}
+      </div>
+      <div className={l.bar} role="progressbar" aria-labelledby={id} aria-valuenow={value} aria-valuemin={0} aria-valuemax={100}>
         <span style={{ width: `${value}%` }} />
       </div>
     </div>

apps/web/src/pages/admin/ScanStatus.tsx

@@ -1,4 +1,5 @@
 import type { components } from '@pipu/api-client';
+import { useId } from 'react';
 import { useTranslation } from 'react-i18next';
 
 import { formatDateTime } from '../../shared/lib/format';
@@ -16,14 +17,15 @@ export function StatusBadge({ status }: { status: SourceStatus }) {
 /** Прогресс идущего скана или итог последнего. */
 export function ScanLine({ scan, lastScanAt }: { scan: ScanProgress | null; lastScanAt: string | null }) {
   const { t, i18n } = useTranslation('admin');
+  const id = useId();
   if (scan?.running) {
     const pct = scan.to_process > 0 ? Math.round((scan.processed / scan.to_process) * 100) : 0;
     return (
       <div className={s.scan}>
-        <div className={s.scanText}>
+        <div className={s.scanText} id={id}>
           {scan.found === 0 ? t('sources.scan_walking') : t('sources.scanning', { processed: scan.processed, total: scan.to_process })}
         </div>
-        <div className={s.bar} role="progressbar" aria-valuenow={pct} aria-valuemin={0} aria-valuemax={100}>
+        <div className={s.bar} role="progressbar" aria-labelledby={id} aria-valuenow={pct} aria-valuemin={0} aria-valuemax={100}>
           <span style={{ width: `${pct}%` }} />
         </div>
       </div>

apps/web/src/pages/admin/library.module.css

@@ -118,6 +118,20 @@
   color: var(--danger);
 }
 
+.retryRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.errorDetail {
+  display: block;
+  margin-top: 4px;
+  color: var(--text3);
+  word-break: break-word;
+}
+
 .bar {
   height: 6px;
   border-radius: 3px;

apps/web/src/pages/auth.module.css

@@ -161,6 +161,83 @@
   color: var(--text3);
 }
 
+.footer a {
+  color: var(--text2);
+}
+
+/* Страница Android-приложения (/android). */
+.download {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 14px 18px;
+  border-radius: var(--radius-lg);
+  background: var(--accent-fill);
+  color: #fff;
+  font-weight: 700;
+  text-decoration: none;
+  box-shadow: var(--glow);
+  transition:
+    background 0.2s,
+    transform 0.15s;
+}
+
+.download:hover {
+  background: var(--accent-fill2);
+}
+
+.download:active {
+  transform: scale(0.98);
+}
+
+.downloadMeta {
+  display: block;
+  margin-top: 2px;
+  font-size: 12px;
+  font-weight: 500;
+  opacity: 0.85;
+}
+
+.steps {
+  margin: 0;
+  padding-left: 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  color: var(--text2);
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+.server {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  margin-left: 6px;
+  padding: 2px 10px;
+  border-radius: 8px;
+  border: 1px solid var(--line2);
+  background: var(--surface2);
+  color: var(--text);
+  cursor: pointer;
+}
+
+.details {
+  font-size: 12px;
+  color: var(--text3);
+}
+
+.details summary {
+  cursor: pointer;
+}
+
+.details code {
+  display: block;
+  margin-top: 6px;
+  word-break: break-all;
+  font-family: var(--font-mono);
+}
+
 .link {
   align-self: center;
 }

apps/web/src/pages/home.module.css

@@ -7,6 +7,7 @@
   gap: 28px;
   padding: 24px 0;
   text-align: center;
+  user-select: none; /* главная — только элементы управления волной */
 }
 
 .orbLabel {
@@ -86,7 +87,7 @@
 
 .chipOn,
 .chipOn:hover {
-  background: var(--accent);
+  background: var(--accent-fill);
   border-color: var(--accent);
   color: #fff;
   box-shadow: var(--glow);

apps/web/src/pages/onboarding.module.css

@@ -0,0 +1,124 @@
+.page {
+  display: flex;
+  flex-direction: column;
+  gap: 28px;
+  max-width: 1100px;
+  margin: 0 auto;
+  animation: pipuIn 0.2s ease-out;
+}
+
+.head h1 {
+  margin: 0 0 8px;
+  font-family: var(--font-display);
+  font-size: 32px;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+}
+
+.head p {
+  margin: 0;
+  color: var(--text2);
+}
+
+.label {
+  margin: 0 0 14px;
+  font-size: 13px;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text3);
+}
+
+.artists {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(120px, 1fr));
+  gap: 18px 12px;
+}
+
+.artist {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 6px;
+  border-radius: var(--radius-lg);
+  text-align: center;
+}
+
+.artist:hover {
+  background: var(--hover);
+}
+
+.avatar {
+  position: relative;
+  border-radius: 50%;
+  transition:
+    box-shadow 0.15s,
+    transform 0.15s;
+}
+
+.on .avatar {
+  box-shadow:
+    0 0 0 3px var(--bg),
+    0 0 0 5px var(--accent);
+  transform: scale(0.96);
+}
+
+.check {
+  position: absolute;
+  right: -2px;
+  bottom: -2px;
+  display: grid;
+  place-items: center;
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  background: var(--accent);
+  color: #fff;
+  box-shadow: var(--glow);
+}
+
+.name {
+  font-size: 14px;
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 100%;
+}
+
+.genres {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.genre {
+  height: 38px;
+  padding: 0 16px;
+  border-radius: var(--radius-pill);
+  border: 1px solid var(--line);
+  background: var(--surface2);
+  font-weight: 600;
+  font-size: 14px;
+}
+
+.genre[aria-pressed='true'] {
+  background: var(--accent-fill);
+  border-color: var(--accent);
+  color: #fff;
+  box-shadow: var(--glow);
+}
+
+.actions {
+  position: sticky;
+  bottom: 16px;
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+  padding: 12px;
+  border-radius: var(--radius-lg);
+  border: 1px solid var(--line2);
+  background: var(--glass);
+  backdrop-filter: blur(28px) saturate(1.3);
+}

apps/web/src/pages/uploads/common.tsx

@@ -1,6 +1,7 @@
 import type { components } from '@pipu/api-client';
 import { unwrap } from '@pipu/core';
 import { useQuery } from '@tanstack/react-query';
+import { useId } from 'react';
 import { useTranslation } from 'react-i18next';
 
 import { useSession } from '../../app/session';
@@ -47,18 +48,19 @@ export function useUploadQuota() {
 export function QuotaMeter() {
   const { t, i18n } = useTranslation('admin');
   const quota = useUploadQuota();
+  const id = useId();
   if (!quota.data) return null;
   const q = quota.data;
   const ratio = q.limit_bytes > 0 ? Math.min(q.used_bytes / q.limit_bytes, 1) : 1;
   const fmt = (n: number) => formatBytes(n, i18n.language);
   return (
     <div className={u.quota}>
-      <span className={u.quotaText}>
+      <span className={u.quotaText} id={id}>
         {t('uploads.quota', { used: fmt(q.used_bytes), limit: fmt(q.limit_bytes) })}
         {q.per_user_limit_bytes !== null &&
           ` · ${t('uploads.quota_mine', { used: fmt(q.user_used_bytes), limit: fmt(q.per_user_limit_bytes) })}`}
       </span>
-      <div className={u.progress} role="progressbar" aria-valuenow={Math.round(ratio * 100)} aria-valuemin={0} aria-valuemax={100}>
+      <div className={u.progress} role="progressbar" aria-labelledby={id} aria-valuenow={Math.round(ratio * 100)} aria-valuemin={0} aria-valuemax={100}>
         <span style={{ width: `${ratio * 100}%` }} />
       </div>
     </div>

apps/web/src/shared/ui/icons.ts

@@ -23,6 +23,8 @@ export { default as albumIcon } from '@material-symbols/svg-400/rounded/album.sv
 export { default as arrowDownIcon } from '@material-symbols/svg-400/rounded/arrow_downward.svg';
 export { default as arrowUpIcon } from '@material-symbols/svg-400/rounded/arrow_upward.svg';
 export { default as chevronRightIcon } from '@material-symbols/svg-400/rounded/chevron_right.svg';
+export { default as downloadIcon } from '@material-symbols/svg-400/rounded/download.svg';
+export { default as androidIcon } from '@material-symbols/svg-400/rounded/phone_android.svg';
 export { default as deleteIcon } from '@material-symbols/svg-400/rounded/delete.svg';
 export { default as editIcon } from '@material-symbols/svg-400/rounded/edit.svg';
 export { default as folderIcon } from '@material-symbols/svg-400/rounded/folder.svg';

apps/web/src/shared/ui/ui.module.css

@@ -53,13 +53,13 @@
 }
 
 .primary {
-  background: var(--accent);
+  background: var(--accent-fill);
   color: #fff;
   box-shadow: var(--glow);
 }
 
 .primary:hover:not(:disabled) {
-  background: var(--accent2);
+  background: var(--accent-fill2);
 }
 
 .secondary {
@@ -186,7 +186,7 @@
 }
 
 .segmented button[aria-pressed='true'] {
-  background: var(--accent);
+  background: var(--accent-fill);
   color: #fff;
 }
 

apps/web/src/styles.css

@@ -41,6 +41,19 @@ button {
   cursor: pointer;
 }
 
+/* Элементы управления не выделяются при кликах и двойных кликах — текст остаётся выделяемым на страницах. */
+button,
+[role='button'],
+[role='tab'],
+[role='option'],
+[role='menuitem'],
+[role='listitem'],
+nav a,
+label {
+  user-select: none;
+  -webkit-user-select: none;
+}
+
 :focus-visible {
   outline: 2px solid var(--accent);
   outline-offset: 2px;
@@ -53,6 +66,14 @@ button {
   }
 }
 
+/* Выезжающие справа панели (очередь, docs/design.md#4). */
+@keyframes pipuSlideIn {
+  from {
+    opacity: 0;
+    transform: translateX(24px);
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   *,
   *::before,

apps/web/src/widgets/AppShell.module.css

@@ -27,12 +27,15 @@
   padding-bottom: 132px;
 }
 
+/* Над контентом: выпадающие подсказки поиска и меню профиля перекрывают страницу, а не уходят под неё. */
 .top {
   grid-area: top;
-  display: flex;
+  z-index: 30;
+  /* Три зоны: логотип, середина, профиль; поиск — в одной из них (настройка «Расположение поиска»). */
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
   align-items: center;
-  gap: 24px;
-  justify-content: space-between;
+  gap: 16px;
   padding: 0 20px;
   border-bottom: 1px solid var(--line);
   background: var(--bar-a);
@@ -51,9 +54,22 @@
   }
 }
 
+.topLeft {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  min-width: 0;
+}
+
+.topCenter {
+  display: flex;
+  justify-content: center;
+}
+
 .topRight {
   display: flex;
   align-items: center;
+  justify-content: flex-end;
   gap: 12px;
 }
 
@@ -155,7 +171,7 @@
   height: 20px;
   padding: 0 6px;
   border-radius: var(--radius-pill);
-  background: var(--accent);
+  background: var(--accent-fill);
   color: #fff;
   font-size: 11px;
   font-weight: 700;

apps/web/src/widgets/AppShell.tsx

@@ -22,6 +22,7 @@ import {
   dislikeFillIcon,
   dislikeIcon,
   settingsIcon,
+  androidIcon,
   storageFillIcon,
   storageIcon, inboxFillIcon, inboxIcon, myUploadsFillIcon, myUploadsIcon, uploadFillIcon, uploadIcon, tuneFillIcon, tuneIcon} from '../shared/ui/icons';
 import { Avatar, cx, Icon, Logo, Menu } from '../shared/ui/ui';
@@ -92,6 +93,8 @@ function Shell() {
   const name = user.display_name ?? user.username;
   const staff = user.role !== 'user';
   const island = user.ui_prefs.web_player === 'island';
+  const searchAt = user.ui_prefs.search_position ?? 'center';
+  const search = <SearchBox align={searchAt} />;
   const counts = useCollectionCounts();
   const pending = usePendingUploads(user.role === 'admin');
 
@@ -99,11 +102,15 @@ function Shell() {
     <div className={cx(s.shell, island && s.island)}>
       {user.ui_prefs.ambient !== false && <ShellAmbient />}
       <header className={s.top}>
-        <Link to="/" className={s.logoLink}>
-          <Logo />
-        </Link>
-        <SearchBox />
+        <div className={s.topLeft}>
+          <Link to="/" className={s.logoLink}>
+            <Logo />
+          </Link>
+          {searchAt === 'left' && search}
+        </div>
+        <div className={s.topCenter}>{searchAt === 'center' && search}</div>
         <div className={s.topRight}>
+          {searchAt === 'right' && search}
           <Menu
             label={t('profile.menu')}
             triggerClassName={s.profileButton}
@@ -122,6 +129,7 @@ function Shell() {
             }
             items={[
               { label: t('profile.settings'), icon: settingsIcon, onSelect: () => void navigate({ to: '/settings' }) },
+              { label: t('profile.android_app'), icon: androidIcon, onSelect: () => void navigate({ to: '/android' }) },
               { label: t('profile.logout'), icon: logoutIcon, danger: true, onSelect: () => void session.logout() },
             ]}
           />

apps/web/src/widgets/PlayerBar.module.css

@@ -246,7 +246,15 @@ a.source:hover {
   background: var(--glass);
   backdrop-filter: blur(28px) saturate(1.3);
   box-shadow: var(--shadow);
-  animation: pipuIn 0.2s ease-out;
+  animation: pipuSlideIn 0.22s cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+
+.drawerNote {
+  margin: 0;
+  padding: 12px 18px 16px;
+  border-top: 1px solid var(--line);
+  color: var(--text3);
+  font-size: 13px;
 }
 
 .drawerIsland {

apps/web/src/widgets/PlayerBar.tsx

@@ -1,4 +1,4 @@
-import { useState, type CSSProperties } from 'react';
+import { useCallback, useEffect, useId, useRef, useState, type CSSProperties } from 'react';
 import { createPortal } from 'react-dom';
 import { Link } from '@tanstack/react-router';
 import { useTranslation } from 'react-i18next';
@@ -35,6 +35,12 @@ export function PlayerBar({ variant = 'bar' }: { variant?: 'bar' | 'island' }) {
   const player = usePlayer();
   const st = usePlayerState();
   const [queueOpen, setQueueOpen] = useState(false);
+  const queueButton = useRef<HTMLButtonElement>(null);
+  const queueId = useId();
+  const closeQueue = useCallback(() => {
+    setQueueOpen(false);
+    queueButton.current?.focus(); // фокус — туда, откуда открыли
+  }, []);
   const track = st.track;
 
   if (!track) {
@@ -167,10 +173,12 @@ export function PlayerBar({ variant = 'bar' }: { variant?: 'bar' | 'island' }) {
           <Icon src={st.repeat === 'one' ? repeatOneIcon : repeatIcon} size={20} />
         </button>
         <button
+          ref={queueButton}
           type="button"
           className={cx(s.icon, queueOpen && s.accent)}
           aria-label={t('player.queue')}
           aria-expanded={queueOpen}
+          aria-controls={queueOpen ? queueId : undefined}
           onClick={() => setQueueOpen((v) => !v)}
         >
           <Icon src={queueIcon} size={20} />
@@ -195,23 +203,33 @@ export function PlayerBar({ variant = 'bar' }: { variant?: 'bar' | 'island' }) {
           style={{ '--pct': `${(st.muted ? 0 : st.volume) * 100}%` } as CSSProperties}
         />
       </div>
-      {queueOpen && <QueueDrawer variant={variant} onClose={() => setQueueOpen(false)} />}
+      {queueOpen && <QueueDrawer id={queueId} variant={variant} onClose={closeQueue} />}
     </footer>
   );
 }
 
 /** Очередь воспроизведения (выдвижная панель справа): что играет и что дальше, клик — перейти к треку. */
-function QueueDrawer({ variant, onClose }: { variant: 'bar' | 'island'; onClose: () => void }) {
+function QueueDrawer({ id, variant, onClose }: { id: string; variant: 'bar' | 'island'; onClose: () => void }) {
   const { t } = useTranslation();
   const player = usePlayer();
   const st = usePlayerState();
   const upcoming = st.queue.slice(st.index, st.index + 40);
+  const close = useRef<HTMLButtonElement>(null);
+  // Клавиатура: при открытии фокус в панель, Escape закрывает.
+  useEffect(() => {
+    close.current?.focus();
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [onClose]);
   // Портал: у плеера backdrop-filter, а он делает fixed-потомков относительными к себе.
   return createPortal(
-    <aside className={cx(s.drawer, variant === 'island' && s.drawerIsland)} aria-label={t('player.queue')}>
+    <aside id={id} className={cx(s.drawer, variant === 'island' && s.drawerIsland)} aria-label={t('player.queue')}>
       <div className={s.drawerHead}>
         <span>{t('player.queue')}</span>
-        <button type="button" className={s.icon} aria-label={t('form.close')} onClick={onClose}>
+        <button ref={close} type="button" className={s.icon} aria-label={t('form.close')} onClick={onClose}>
           <Icon src={closeIcon} size={20} />
         </button>
       </div>
@@ -221,6 +239,7 @@ function QueueDrawer({ variant, onClose }: { variant: 'bar' | 'island'; onClose:
             key={`${tr.id}-${k}`}
             type="button"
             className={cx(s.queueRow, k === 0 && s.queueCurrent)}
+            aria-current={k === 0 || undefined}
             onClick={() => player.jump(st.index + k)}
           >
             <Cover album={tr.album} size={40} />
@@ -232,6 +251,7 @@ function QueueDrawer({ variant, onClose }: { variant: 'bar' | 'island'; onClose:
           </button>
         ))}
       </div>
+      {st.wave && <p className={s.drawerNote}>{t('player.queue_wave')}</p>}
     </aside>,
     document.body,
   );

apps/web/src/widgets/SearchBox.module.css

@@ -1,12 +1,17 @@
 .box {
   position: relative;
-  flex: 1;
-  max-width: 520px;
+  flex: none;
+  width: 40px;
+  transition: width 0.32s cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+
+.expanded {
+  width: min(520px, 46vw);
 }
 
 .icon {
   position: absolute;
-  left: 14px;
+  left: 11px;
   top: 50%;
   transform: translateY(-50%);
   color: var(--text3);
@@ -16,13 +21,36 @@
 .input {
   width: 100%;
   height: 40px;
-  padding: 0 40px 0 42px;
+  padding: 0 40px 0 40px;
   border-radius: var(--radius-pill);
   border: 1px solid var(--line);
   background: var(--surface2);
   color: var(--text);
   font: inherit;
   outline: none;
+  transition:
+    border-color 0.2s,
+    box-shadow 0.2s,
+    background 0.2s;
+}
+
+/* Свёрнутое поле — круглая кнопка: без подсказки и курсора ввода. */
+.box:not(.expanded) .input {
+  padding: 0;
+  cursor: pointer;
+  color: transparent;
+}
+
+.box:not(.expanded) .input::placeholder {
+  color: transparent;
+}
+
+.box:not(.expanded) .input:hover {
+  background: var(--surface3);
+}
+
+.box:not(.expanded) .kbd {
+  display: none;
 }
 
 .input:focus {
@@ -56,8 +84,7 @@
 
 .popover {
   position: absolute;
-  left: 0;
-  right: 0;
+  width: min(520px, calc(100vw - 32px));
   top: calc(100% + 8px);
   z-index: 45;
   max-height: min(70vh, 560px);
@@ -70,6 +97,20 @@
   animation: pipuIn 0.15s ease-out;
 }
 
+/* Подсказки раскрываются в сторону свободного места: слева — вправо, справа — влево, по центру — от середины. */
+.left .popover {
+  left: 0;
+}
+
+.right .popover {
+  right: 0;
+}
+
+.center .popover {
+  left: 50%;
+  transform: translateX(-50%);
+}
+
 .corrected {
   margin: 4px 10px 8px;
   font-size: 13px;

apps/web/src/widgets/SearchBox.tsx

@@ -23,8 +23,11 @@ type Item = {
   go: () => void;
 };
 
-/** Поиск в топбаре: подсказки по мере ввода, Enter — страница поиска или выбранный элемент. */
-export function SearchBox() {
+/**
+ * Поиск в топбаре: подсказки по мере ввода, Enter — страница поиска или выбранный элемент.
+ * Без фокуса и текста свёрнут в кнопку с лупой; поле раскрывается влево с анимацией.
+ */
+export function SearchBox({ align = 'center' }: { align?: 'left' | 'center' | 'right' }) {
   const { t } = useTranslation();
   const session = useSession();
   const navigate = useNavigate();
@@ -34,6 +37,10 @@ export function SearchBox() {
   const [debounced, setDebounced] = useState('');
   const [open, setOpen] = useState(false);
   const [active, setActive] = useState(-1);
+  const [focused, setFocused] = useState(false);
+  const blurTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
+  // Свёрнут в круглую кнопку, пока не нужен: раскрывается по клику, «/» или Ctrl+K.
+  const expanded = focused || q !== '';
 
   useEffect(() => {
     const id = setTimeout(() => setDebounced(q.trim()), DEBOUNCE_MS);
@@ -141,7 +148,7 @@ export function SearchBox() {
   const optionId = (i: number) => `${listId}-${i}`;
 
   return (
-    <div className={s.box}>
+    <div className={cx(s.box, expanded && s.expanded, s[align])}>
       <Icon src={searchIcon} size={18} className={s.icon} />
       <input
         ref={inputRef}
@@ -160,8 +167,16 @@ export function SearchBox() {
           setOpen(true);
           setActive(-1);
         }}
-        onFocus={() => setOpen(true)}
-        onBlur={() => setTimeout(close, 120)}
+        onFocus={() => {
+          // Вернулись в поле раньше, чем сработало закрытие по blur, — подсказки не прячем.
+          clearTimeout(blurTimer.current);
+          setFocused(true);
+          setOpen(true);
+        }}
+        onBlur={() => {
+          setFocused(false);
+          blurTimer.current = setTimeout(close, 120);
+        }}
         onKeyDown={onKeyDown}
       />
       <kbd className={s.kbd} aria-hidden>

deploy/.env.example

@@ -45,6 +45,8 @@ SUPPORTED_LOCALES=ru,en
 MIN_ANDROID_VERSION_CODE=0
 
 # --- Самообновление Android (M5) ---
-GITEA_URL=https://git.example.lan
-GITEA_REPO=owner/pipu-music
+# Пусто — install.sh и update.sh возьмут из origin клона (например, https://gitea.example.com и owner/pipu-music).
+# Если сервер не видит Gitea по внешнему адресу, укажите внутренний: GITEA_URL=http://10.0.0.5:3000
+GITEA_URL=
+GITEA_REPO=
 GITEA_TOKEN=

deploy/backup.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# Резервные копии PostgreSQL (docs/deployment.md#бэкапы). Работает в контейнере backup (compose.yaml) и в CI;
+# подключение — стандартные PGHOST, PGUSER, PGPASSWORD, PGDATABASE.
+#   backup.sh loop          — каждый день в BACKUP_HOUR (UTC): копия и ротация; раз в неделю — проверка восстановления
+#   backup.sh once          — копия сейчас; печатает путь к файлу
+#   backup.sh verify FILE   — восстановить FILE во временную базу и сверить таблицы и число строк
+#   backup.sh restore FILE  — заменить рабочую базу копией (сервисы, пишущие в базу, должны быть остановлены);
+#                             прежняя база остаётся рядом как <db>_before_restore_<время>
+set -euo pipefail
+
+DIR="${BACKUP_DIR:-/backups}"
+DB="${PGDATABASE:-pipu}"
+KEEP_DAILY="${BACKUP_KEEP_DAILY:-14}"
+KEEP_WEEKLY="${BACKUP_KEEP_WEEKLY:-8}"
+
+log() { echo "$(date -u +%FT%TZ) backup: $*" >&2; }
+
+# Число строк в каждой таблице базы $1: «таблица<TAB>строк», по алфавиту.
+counts() {
+  psql -X -d "$1" -Atq -F $'\t' -c "
+    SELECT table_name,
+           (xpath('/row/c/text()', query_to_xml(format('SELECT count(*) AS c FROM %I.%I', table_schema, table_name),
+                                                false, true, '')))[1]::text
+    FROM information_schema.tables
+    WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+    ORDER BY 1"
+}
+
+rotate() {
+  # shellcheck disable=SC2012 # имена файлов наши, без пробелов
+  ls -1t "$DIR"/daily/pipu-*.dump 2>/dev/null | tail -n +$((KEEP_DAILY + 1)) | xargs -r rm -f --
+  # shellcheck disable=SC2012
+  ls -1t "$DIR"/weekly/pipu-*.dump 2>/dev/null | tail -n +$((KEEP_WEEKLY + 1)) | xargs -r rm -f --
+  find "$DIR/daily" "$DIR/weekly" -name '*.counts' | while read -r c; do
+    [ -f "${c%.counts}.dump" ] || rm -f -- "$c"
+  done
+}
+
+once() {
+  mkdir -p "$DIR/daily" "$DIR/weekly"
+  local name file
+  name="pipu-$(date -u +%Y%m%d-%H%M%S)"
+  file="$DIR/daily/$name.dump"
+  pg_dump -Fc -d "$DB" -f "$file.part"
+  pg_restore -l "$file.part" >/dev/null # оглавление читается — архив не обрезан
+  counts "$DB" >"$file.counts"          # для verify: что было в базе в момент копии
+  mv "$file.part" "$file"
+  # Еженедельная копия — первая за 7 дней (не зависит от того, в какой день сервер был выключен).
+  if ! find "$DIR/weekly" -name 'pipu-*.dump' -mtime -7 | grep -q .; then
+    cp "$file" "$DIR/weekly/$name.dump"
+    cp "$file.counts" "$DIR/weekly/$name.dump.counts"
+  fi
+  rotate
+  log "$file ($(du -h "$file" | cut -f1))"
+  echo "$file"
+}
+
+verify() {
+  local file="$1" tmpdb="${DB}_verify" got want
+  [ -f "$file" ] || { log "нет файла $file"; return 1; }
+  dropdb --if-exists "$tmpdb"
+  createdb "$tmpdb"
+  if ! pg_restore --no-owner --exit-on-error -d "$tmpdb" "$file"; then
+    dropdb --if-exists "$tmpdb"
+    log "ПРОВЕРКА НЕ ПРОЙДЕНА: $file не восстанавливается"
+    return 1
+  fi
+  got="$(counts "$tmpdb")"
+  dropdb "$tmpdb"
+  want="$(cat "$file.counts" 2>/dev/null || counts "$DB")"
+  # Таблица пропала или опустела — копия негодна. Расхождение в числе строк — рабочая база менялась во время
+  # копии (предупреждение); VERIFY_EXACT=1 (CI, база в покое) — тоже ошибка.
+  local bad=0 table n m
+  while IFS=$'\t' read -r table n; do
+    m="$(printf '%s\n' "$got" | awk -F'\t' -v t="$table" '$1 == t { print $2 }')"
+    if [ -z "$m" ]; then
+      log "в копии нет таблицы $table"
+      bad=1
+    elif [ "$m" = 0 ] && [ "$n" != 0 ]; then
+      log "в копии пуста таблица $table (было $n)"
+      bad=1
+    elif [ "$m" != "$n" ]; then
+      log "$table: $m строк в копии, $n при копировании"
+      [ "${VERIFY_EXACT:-}" = 1 ] && bad=1
+    fi
+  done <<<"$want"
+  if [ "$bad" = 1 ]; then
+    log "ПРОВЕРКА НЕ ПРОЙДЕНА: $file"
+    return 1
+  fi
+  log "проверено: $file восстанавливается ($(printf '%s\n' "$got" | wc -l) таблиц)"
+  date -u +%FT%TZ >"$DIR/.last-verify"
+}
+
+restore() {
+  local file="$1" old
+  verify "$file"
+  old="${DB}_before_restore_$(date -u +%Y%m%d%H%M%S)"
+  psql -X -d postgres -Atqc "SELECT pg_terminate_backend(pid) FROM pg_stat_activity
+                            WHERE datname = '$DB' AND pid <> pg_backend_pid()" >/dev/null
+  psql -X -d postgres -qc "ALTER DATABASE \"$DB\" RENAME TO \"$old\""
+  createdb "$DB"
+  if ! pg_restore --no-owner --exit-on-error -d "$DB" "$file"; then
+    dropdb "$DB"
+    psql -X -d postgres -qc "ALTER DATABASE \"$old\" RENAME TO \"$DB\""
+    log "восстановление не удалось — рабочая база не тронута"
+    return 1
+  fi
+  log "база $DB восстановлена из $file; прежняя сохранена как $old (удалить: dropdb $old)"
+}
+
+loop() {
+  local hour="${BACKUP_HOUR:-3}" now next file
+  log "ежедневная копия в $hour:30 UTC, хранится $KEEP_DAILY ежедневных и $KEEP_WEEKLY еженедельных"
+  while true; do
+    now="$(date -u +%s)"
+    next="$(date -u -d "today $hour:30" +%s)"
+    [ "$next" -gt "$now" ] || next="$(date -u -d "tomorrow $hour:30" +%s)"
+    sleep $((next - now))
+    if ! file="$(once)"; then
+      log "КОПИЯ НЕ СДЕЛАНА"
+      continue
+    fi
+    if [ -z "$(find "$DIR" -maxdepth 1 -name .last-verify -mtime -7)" ]; then
+      verify "$file" || true
+    fi
+  done
+}
+
+case "${1:-}" in
+  loop) loop ;;
+  once) once ;;
+  verify) verify "${2:?укажите файл копии}" ;;
+  restore) restore "${2:?укажите файл копии}" ;;
+  *)
+    sed -n '2,9p' "$0" >&2
+    exit 2
+    ;;
+esac

deploy/compose.yaml

@@ -20,11 +20,13 @@ x-library-ro: &library-ro
 # Локальная музыка (источники type=local): каталог хоста, например смонтированный диск /mnt/music.
 # Всем сервисам — только чтение; на запись (импорт загрузок) его видит только storage-agent — /library-host-rw
 # (docs/library-and-storage.md#запись-в-хранилище).
+# rslave: диск, смонтированный на хосте уже после старта контейнеров, становится виден внутри без перезапуска.
 x-library-host-ro: &library-host-ro
   type: bind
   source: ${LIBRARY_HOST:-${PIPU_DATA:-/srv/pipu}/library-host}
   target: /library-host
   read_only: true
+  bind: { propagation: rslave }
 
 x-restart: &restart
   restart: unless-stopped
@@ -96,6 +98,7 @@ services:
       - type: bind
         source: ${LIBRARY_HOST:-${PIPU_DATA:-/srv/pipu}/library-host}
         target: /library-host-rw
+        bind: { propagation: rslave }
       - ${PIPU_DATA:-/srv/pipu}/uploads:/uploads:ro
 
   recommender:
@@ -142,6 +145,26 @@ services:
       interval: 5s
       retries: 20
 
+  # Ежедневная копия базы и еженедельная проверка восстановления (deploy/backup.sh, docs/deployment.md#бэкапы).
+  backup:
+    <<: *restart
+    image: pgvector/pgvector:0.8.7-pg17
+    entrypoint: ["bash", "/backup.sh"]
+    command: ["loop"]
+    environment:
+      PGHOST: postgres
+      PGUSER: pipu
+      PGPASSWORD: ${POSTGRES_PASSWORD}
+      PGDATABASE: pipu
+      BACKUP_HOUR: ${BACKUP_HOUR:-3}
+      BACKUP_KEEP_DAILY: ${BACKUP_KEEP_DAILY:-14}
+      BACKUP_KEEP_WEEKLY: ${BACKUP_KEEP_WEEKLY:-8}
+    volumes:
+      - ./backup.sh:/backup.sh:ro
+      - ${PIPU_DATA:-/srv/pipu}/backups:/backups
+    depends_on:
+      postgres: { condition: service_healthy }
+
   redis:
     <<: *restart
     image: redis:7.4-alpine

deploy/install.sh

@@ -76,6 +76,39 @@ for key in JWT_PRIVATE_KEY STREAM_SIGNING_KEY; do
   fi
 done
 
+# Самообновление Android: адрес Gitea и репозиторий — из origin этого клона, если в .env пусто
+# или осталась заглушка из .env.example (https://host/owner/repo, git@host:owner/repo, ssh://git@host:port/owner/repo).
+fill_gitea() {
+  local url repo origin host path
+  url="$(sed -n 's/^GITEA_URL=//p' .env)"
+  repo="$(sed -n 's/^GITEA_REPO=//p' .env)"
+  case "$url" in "" | *example.*) url="" ;; esac
+  case "$repo" in "" | owner/*) repo="" ;; esac
+  [ -n "$url" ] && [ -n "$repo" ] && return 0
+  origin="$(git -c safe.directory='*' remote get-url origin 2>/dev/null || true)"
+  [ -n "$origin" ] || return 0
+  case "$origin" in
+    http://* | https://*)
+      host="$(printf '%s' "$origin" | sed -E 's#^(https?://)([^@/]*@)?([^/]+)/.*#\1\3#')"
+      path="$(printf '%s' "$origin" | sed -E 's#^https?://[^/]+/##')" ;;
+    ssh://*)
+      host="https://$(printf '%s' "$origin" | sed -E 's#^ssh://([^@/]*@)?([^:/]+).*#\2#')"
+      path="$(printf '%s' "$origin" | sed -E 's#^ssh://[^/]+/##')" ;;
+    *:*)
+      host="https://$(printf '%s' "$origin" | sed -E 's#^([^@]*@)?([^:]+):.*#\2#')"
+      path="${origin#*:}" ;;
+    *) return 0 ;;
+  esac
+  path="${path%.git}"
+  [ -n "$url" ] || url="$host"
+  [ -n "$repo" ] || repo="$path"
+  for kv in "GITEA_URL=$url" "GITEA_REPO=$repo"; do
+    if grep -q "^${kv%%=*}=" .env; then sed -i "s|^${kv%%=*}=.*|$kv|" .env; else echo "$kv" >> .env; fi
+  done
+  echo "→ самообновление Android: $url, $repo (из git remote; поменять — в .env)"
+}
+fill_gitea
+
 # LIBRARY_HOST, переданный при повторном запуске, попадает и в уже существующий .env
 if [ -n "$LIBRARY_HOST" ]; then
   if grep -q '^LIBRARY_HOST=' .env; then

deploy/restore.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Восстановление базы из резервной копии (docs/deployment.md#бэкапы).
+#   ./restore.sh                          — список копий
+#   ./restore.sh daily/pipu-20261020-033000.dump
+# Сервисы, пишущие в базу, останавливаются на время восстановления; прежняя база сохраняется рядом.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+[ -f .env ] || { echo "нет .env — сначала sudo ./install.sh" >&2; exit 1; }
+DATA="$(sed -n 's/^PIPU_DATA=//p' .env)"
+DATA="${DATA:-/srv/pipu}"
+
+if [ -z "${1:-}" ]; then
+  echo "Копии в $DATA/backups (новые сверху):"
+  (cd "$DATA/backups" && ls -1t daily/*.dump weekly/*.dump 2>/dev/null) || echo "  копий нет"
+  exit 0
+fi
+
+rel="${1#"$DATA/backups/"}"
+[ -f "$DATA/backups/$rel" ] || { echo "нет файла $DATA/backups/$rel" >&2; exit 1; }
+
+echo "→ восстановление из $rel: api, рекомендации и анализ будут остановлены на время восстановления"
+read -r -p "Продолжить? [y/N] " yes
+[ "$yes" = y ] || [ "$yes" = Y ] || exit 1
+
+docker compose stop api recommender analyzer storage-agent
+if docker compose run --rm backup restore "/backups/$rel"; then
+  status=0
+else
+  status=1
+fi
+docker compose up -d
+[ "$status" = 0 ] || { echo "восстановление не удалось — база не изменена" >&2; exit 1; }
+echo "готово. Поиск переиндексируется при старте api (или вручную: «Администрирование → Библиотека»)."

deploy/update.sh

@@ -26,6 +26,48 @@ for key in JWT_PRIVATE_KEY STREAM_SIGNING_KEY; do
   fi
 done
 
+# Самообновление Android: адрес Gitea и репозиторий — из origin этого клона, если в .env пусто
+# или осталась заглушка из .env.example (https://host/owner/repo, git@host:owner/repo, ssh://git@host:port/owner/repo).
+fill_gitea() {
+  local url repo origin host path
+  url="$(sed -n 's/^GITEA_URL=//p' .env)"
+  repo="$(sed -n 's/^GITEA_REPO=//p' .env)"
+  case "$url" in "" | *example.*) url="" ;; esac
+  case "$repo" in "" | owner/*) repo="" ;; esac
+  [ -n "$url" ] && [ -n "$repo" ] && return 0
+  origin="$(git -c safe.directory='*' remote get-url origin 2>/dev/null || true)"
+  [ -n "$origin" ] || return 0
+  case "$origin" in
+    http://* | https://*)
+      host="$(printf '%s' "$origin" | sed -E 's#^(https?://)([^@/]*@)?([^/]+)/.*#\1\3#')"
+      path="$(printf '%s' "$origin" | sed -E 's#^https?://[^/]+/##')" ;;
+    ssh://*)
+      host="https://$(printf '%s' "$origin" | sed -E 's#^ssh://([^@/]*@)?([^:/]+).*#\2#')"
+      path="$(printf '%s' "$origin" | sed -E 's#^ssh://[^/]+/##')" ;;
+    *:*)
+      host="https://$(printf '%s' "$origin" | sed -E 's#^([^@]*@)?([^:]+):.*#\2#')"
+      path="${origin#*:}" ;;
+    *) return 0 ;;
+  esac
+  path="${path%.git}"
+  [ -n "$url" ] || url="$host"
+  [ -n "$repo" ] || repo="$path"
+  for kv in "GITEA_URL=$url" "GITEA_REPO=$repo"; do
+    if grep -q "^${kv%%=*}=" .env; then sed -i "s|^${kv%%=*}=.*|$kv|" .env; else echo "$kv" >> .env; fi
+  done
+  echo "→ самообновление Android: $url, $repo (из git remote; поменять — в .env)"
+}
+fill_gitea
+
+# Папка с музыкой пуста — почти всегда это несмонтированный диск: api отдавал бы ошибки воспроизведения.
+LIBRARY_HOST="$(sed -n 's/^LIBRARY_HOST=//p' .env)"
+if [ -n "$LIBRARY_HOST" ] && [ -z "$(ls -A "$LIBRARY_HOST" 2>/dev/null)" ] && [ "${PIPU_ALLOW_EMPTY_LIBRARY:-}" != 1 ]; then
+  echo "LIBRARY_HOST=$LIBRARY_HOST пуст или не существует — диск с музыкой не смонтирован?" >&2
+  echo "  проверьте: findmnt $LIBRARY_HOST; смонтируйте (sudo mount -a) и повторите." >&2
+  echo "  Если папка и должна быть пустой: PIPU_ALLOW_EMPTY_LIBRARY=1 ./update.sh ${1:-}" >&2
+  exit 1
+fi
+
 REF="${1:-}"
 git fetch --tags --prune --quiet origin
 
@@ -53,6 +95,12 @@ if [ -n "$cur_core" ] && [ -n "$tgt_core" ] && [ "$cur_core" != "$tgt_core" ] &&
   fi
 fi
 
+# Копия базы перед обновлением: миграции назад не откатываются (deploy/restore.sh — вернуть).
+if [ -n "$(docker compose ps -q --status running postgres 2>/dev/null)" ]; then
+  echo "→ резервная копия базы"
+  docker compose run --rm --no-deps backup once >/dev/null
+fi
+
 echo "→ переключаемся на $REF"
 if git show-ref --verify --quiet "refs/remotes/origin/$REF"; then
   git checkout --quiet "$REF"

docs/README.md

@@ -23,6 +23,7 @@ Pipu Music — self-hosted музыкальный сервис (веб + Android
 | [testing.md](testing.md) | Стратегия тестирования |
 | [ci-cd.md](ci-cd.md) | Gitea Actions: проверки и релиз по тегу |
 | [install-guide.md](install-guide.md) | **Пошагово:** установка сервера на домен с HTTPS, подключение веба и Android |
+| [admin-guide.md](admin-guide.md) | **Администратору:** пользователи, хранилища, очередь, волна, обновления, бэкапы, диагностика |
 | [deployment.md](deployment.md) | Справочник по развёртыванию: сервисы, каталоги, переменные, бэкапы |
 | [conventions.md](conventions.md) | Соглашения по коду, git, версиям |
 | [roadmap.md](roadmap.md) | Этапы разработки и критерии готовности |

docs/admin-guide.md

@@ -0,0 +1,139 @@
+# Руководство администратора
+
+Повседневная работа с сервером после установки ([install-guide.md](install-guide.md)): пользователи, музыка,
+очередь на добавление, «Моя волна», обновления, бэкапы и диагностика. Все команды — из каталога
+`/opt/pipu-music/deploy`. Справочник по сервисам и переменным — [deployment.md](deployment.md).
+
+## 1. Первый вход
+
+1. Логин `admin`. Пароль — `BOOTSTRAP_ADMIN_PASSWORD` из `.env`, а если он не задан — сгенерированный, его
+   печатает лог один раз: `docker compose logs api | grep -i bootstrap`.
+2. Сервер сразу попросит сменить логин и пароль администратора (пароль ≥ 12 символов). До этого остальные
+   разделы недоступны.
+3. Подключите хранилище с музыкой (раздел 3) — после первого скана появятся библиотека, поиск и «Моя волна».
+
+## 2. Пользователи и роли
+
+«Администрирование → Пользователи».
+
+| Роль | Что может |
+|---|---|
+| Пользователь | Слушать, искать, собирать коллекцию, «Моя волна» |
+| Модератор | Плюс: заводить пользователей и сбрасывать им пароли, смотреть статус библиотеки, предлагать треки |
+| Администратор | Всё: хранилища, сканы, очередь на добавление, настройки сервера, роли, аудит |
+
+Полная матрица прав — [auth-and-roles.md](auth-and-roles.md#матрица-прав).
+
+- **Новый пользователь:** «Создать» → логин, имя, роль. Сервер выдаёт **временный пароль** — он показывается один
+  раз, передайте его человеку. При первом входе пароль придётся сменить.
+- **Забыл пароль:** «Сбросить пароль» — новый временный пароль, все сессии пользователя завершаются.
+- **Заблокировать** — вход запрещён, история и лайки сохраняются; **удалить** — безвозвратно вместе с историей.
+- Последнего администратора нельзя понизить, заблокировать или удалить.
+- **Аудит** («Администрирование → Аудит»): кто, когда и что сделал — создание пользователей, смена ролей, сбросы
+  паролей, изменения хранилищ и настроек, решения по очереди.
+
+## 3. Хранилища и библиотека
+
+«Администрирование → Хранилища».
+
+- **Папка на сервере** — каталог хоста из `LIBRARY_HOST` в `.env` (например, смонтированный диск `/mnt/music`);
+  в форме указывается путь внутри него. **NFS** — сервер и экспорт; монтирует `storage-agent`.
+- «Проверить» — доступ к хранилищу, число найденных аудиофайлов.
+- **Шаблоны путей** («Шаблоны»): как из пути файла получить исполнителя, альбом, год и номер трека, если в тегах
+  пусто. «Предпросмотр» показывает разбор реальных путей до сохранения. Что важнее — теги или путь, задаётся
+  в карточке хранилища (по умолчанию теги).
+- **Скан:** обычный — только новые и изменённые файлы (по расписанию — интервал в карточке хранилища — и после
+  изменения настроек), «Полный» — перечитать всё. Удалённые с диска файлы помечаются отсутствующими, а не стираются из истории.
+- «Администрирование → Библиотека» — счётчики, прогресс скана и аудиоанализа, файлы с ошибками чтения
+  (битые файлы, неизвестные форматы) и «Переиндексировать поиск» — если поиск выдаёт устаревшее (обычно не нужно:
+  индекс обновляется сам и пересобирается при старте api).
+- **Аудиоанализ** (темп, энергия, настроение — для «Моей волны») идёт в фоне: на 10 тыс. треков — несколько часов
+  при 4 ядрах (`analyzer` в `compose.yaml`, `--workers`). Волна работает и до его окончания, но точнее — после.
+  Не удалось проанализировать часть треков (например, пока диск не был смонтирован) — «Повторить» под счётчиком
+  ошибок возвращает их в очередь; рядом показана самая частая ошибка. Пропавшие файлы анализатор не считает
+  попыткой и ждёт, пока диск вернётся.
+
+## 4. Очередь на добавление
+
+Модераторы и администраторы предлагают треки («Предложить треки»), администратор решает, что попадёт
+в библиотеку. Подробно — [uploads.md](uploads.md).
+
+- **Куда пишутся файлы:** у хранилища включите «Принимать загрузки» и задайте **шаблон раскладки** — «Подобрать»
+  предложит шаблон по уже лежащим файлам, «Проверить» убедится, что из пути, построенного шаблоном, сканер
+  получит те же исполнителя, альбом и номер трека. Хранилище по умолчанию — в «Настройках сервера».
+- **Рассмотрение** («Очередь на добавление»): прослушать, поправить метаданные (в том числе сразу для всего
+  альбома), одобрить или отклонить с причиной — автор её увидит. Итоговый путь пересчитывается при правке.
+  Отметка «возможный дубль» — со ссылкой на похожий трек библиотеки; точные копии отсекаются ещё до загрузки.
+- **Импорт:** одобренный файл записывается в хранилище только под окончательным именем, с проверкой контрольной
+  суммы; кроме самих аудиофайлов (и папок для них) на диск ничего не пишется.
+- **Квота** («Настройки сервера»): общий лимит очереди (10 ГБ по умолчанию), лимит на одного модератора
+  (выключен) и максимальный размер файла (2 ГБ). Отклонённые файлы и дубли место не занимают; снижение лимита ниже
+  занятого не удаляет загрузки, просто новые не принимаются.
+
+## 5. «Моя волна»
+
+- «Администрирование → Библиотека → Моя волна за 7 дней»: сколько треков выдано, доля дослушанных до конца,
+  ранних скипов и лайков на 100 треков. Ориентир — ранних скипов меньше 30%.
+- Таблица по **версиям модели**: `heuristic-v1` — эвристика, `heuristic-v1+cf` — она же с коллаборативной
+  фильтрацией (ALS), `lgbm-…` — обученный ранжировщик. По ней видно, стало ли лучше после смены модели.
+- Обучение — каждую ночь в 3:00 UTC: ALS по прослушиваниям, бандит по источникам
+  кандидатов, ранжировщик по показам волны. Новая модель включается, только если по проверке на последней неделе
+  не хуже текущей. Ранжировщику нужно ~20 тыс. показов с известным исходом — до этого работает эвристика.
+- Новые пользователи с почти пустой историей проходят **онбординг вкуса**: выбирают исполнителей и жанры
+  библиотеки. Пропуск тоже запоминается.
+
+## 6. Обновление
+
+```bash
+./update.sh
+```
+
+Скрипт делает копию базы, переключается на последний релиз, собирает образы, перезапускает сервисы и ждёт
+готовности; миграции применяются при старте api. Конкретная версия — `./update.sh v1.0.0`; откат на старую версию
+требует `PIPU_ALLOW_DOWNGRADE=1` (миграции не откатываются — сначала проверьте совместимость). Перед обновлением
+прочитайте заметки к релизу на странице релизов Gitea.
+
+Android-приложение обновляется само: при запуске оно сверяется с сервером и предлагает новый APK.
+Раздать приложение — ссылка `https://<ваш-домен>/android` (без входа): кнопка «Скачать APK» последнего релиза,
+адрес сервера для копирования и короткая инструкция; та же страница — внизу экрана входа и в меню профиля.
+
+## 7. Бэкапы и восстановление
+
+- Каждую ночь (`BACKUP_HOUR`, по умолчанию 3:30 UTC) контейнер `backup` делает копию базы в
+  `/srv/pipu/backups/daily` (14 последних) и раз в неделю — в `weekly` (8 последних).
+- Раз в неделю копия **проверяется восстановлением** во временную базу. Результат:
+  `docker compose logs backup | tail`; при ошибке в логе — «ПРОВЕРКА НЕ ПРОЙДЕНА».
+- Копия сейчас: `docker compose run --rm backup once`.
+- Восстановление: `./restore.sh` — список копий, `./restore.sh daily/<файл>` — восстановить. Прежняя база
+  остаётся рядом как `pipu_before_restore_<время>`; убедившись, что всё в порядке, удалите её:
+  `docker compose exec postgres dropdb -U pipu pipu_before_restore_<время>`.
+- В копию входит всё, что нельзя пересоздать: пользователи, история, лайки, состояние плеера, очередь на добавление,
+  результаты аудиоанализа и модели волны. Поиск, обложки и транскоды восстанавливаются сами.
+- **Сама музыка не бэкапится** приложением — это ваш диск или NFS. Каталог бэкапов тоже лежит на сервере:
+  копируйте `/srv/pipu/backups` на другую машину, например `rsync` по cron.
+
+## 8. Наблюдение
+
+| Что | Как |
+|---|---|
+| Сервер жив и готов | `curl -s https://music.example.com/readyz` → все зависимости `ok` |
+| Состояние сервисов | `docker compose ps` |
+| Логи | `docker compose logs -f --tail=100 api` (или `recommender`, `analyzer`, `storage-agent`, `backup`) |
+| Место на диске | `df -h /srv/pipu`; больше всего занимают `cache/transcode` (чистится сам) и `backups` |
+| Версия | `grep PIPU_VERSION .env`, `GET /api/v1/server-info`; Android — внизу вкладки «Профиль» |
+| Нагрузка | `tests/load/smoke.js` — см. [testing.md](testing.md#нагрузочный-smoke) |
+
+## 9. Частые ситуации
+
+| Ситуация | Что делать |
+|---|---|
+| Ни один трек не играет («Не удалось воспроизвести трек»), в логе api `no such file or directory` | Диск с музыкой не смонтирован: `findmnt <LIBRARY_HOST>`, `sudo mount -a`. Контейнеры увидят диск сами; скан на пустой папке прерывается с ошибкой «is the disk mounted?» и ничего не помечает пропавшим |
+| Трек не находится поиском | Есть ли он в «Библиотеке» (скан завершён, файл не в «ошибках»); затем «Переиндексировать поиск» |
+| Неверный исполнитель или альбом | Поправьте теги файла или шаблон путей и запустите скан |
+| Хранилище в статусе «Ошибка» | Текст ошибки на карточке; диск смонтирован (`findmnt`), NFS доступен с сервера; «Проверить» |
+| Волна однообразная | Идёт ли аудиоанализ («Библиотека → Аудиоанализ»); чем больше прослушиваний, тем точнее волна |
+| Загрузка застряла в «Обработке» | `docker compose logs api | grep upload`; повторный импорт — «Одобрить» ещё раз |
+| Пользователь не может войти | Не заблокирован ли; «Сбросить пароль» |
+| Сервис перезапускается по кругу | `docker compose logs <сервис>`; часто — закончилось место на диске |
+
+Остальное — [install-guide.md](install-guide.md#12-если-что-то-не-работает).

docs/ci-cd.md

@@ -103,7 +103,7 @@ container:
     - /opt/ci-cache/**   # постоянные кэши Gradle и Android SDK для job android в release.yml
 ```
 
-Сборка APK ограничена сама (`release.yml`: контейнер `--cpus=3 --memory=6g` без свопа, CMake / ninja / Gradle
+Сборка APK ограничена сама (`release.yml`: контейнер `--cpus=3 --memory=7g` без свопа, Gradle `-Xmx2g`, Metro `--max-old-space-size=1536`, таймаут 60 мин, CMake / ninja / Gradle
 по 2 потока, `nice` / `ionice`). Если раннер — VM в гипервизоре (Proxmox), дополнительно ограничьте её там:
 фиксированная RAM без ballooning, сумма RAM всех VM меньше RAM хоста, `cpulimit` ≤ половины ядер хоста,
 лимит дискового I/O — иначе тяжёлая сборка может подвесить весь хост.

docs/deployment.md

@@ -77,7 +77,7 @@
 | `BOOTSTRAP_ADMIN_PASSWORD` | пусто → сгенерировать и вывести в лог | |
 | `TRANSCODE_CACHE_LIMIT_GB` | `50` | |
 | `TRANSCODE_CONCURRENCY` | `2` | |
-| `GITEA_URL`, `GITEA_REPO`, `GITEA_TOKEN` | `https://git.home.lan`, `owner/pipu-music`, read-only токен | Для самообновления Android |
+| `GITEA_URL`, `GITEA_REPO`, `GITEA_TOKEN` | пусто — из `git remote` (`install.sh`, `update.sh`); токен — для закрытого репозитория | Самообновление Android и страница `/android` |
 | `PIPU_FILE_UID`, `PIPU_FILE_GID` | `1000` | Владелец файлов, которые агент записывает в принимающие хранилища |
 | `UPLOADS_DIR` | `/uploads` | Staging очереди на добавление (лимит очереди задаётся в админке) |
 | `LOG_LEVEL` | `info` | |
@@ -97,7 +97,21 @@
 
 ## Бэкапы
 
-- `pg_dump` ежедневно (cron-контейнер `backup`), хранить 14 дней + еженедельные 8 недель → `/srv/pipu/backups`.
+- Контейнер `backup` (`deploy/backup.sh loop`): каждый день в `BACKUP_HOUR`:30 UTC (по умолчанию 3:30) —
+  `pg_dump -Fc` → `/srv/pipu/backups/daily/`, хранится `BACKUP_KEEP_DAILY` = 14 последних; первая копия за неделю
+  копируется в `weekly/` (`BACKUP_KEEP_WEEKLY` = 8). Рядом с копией — `*.counts`: число строк в каждой таблице.
+- Раз в неделю копия **проверяется восстановлением**: разворачивается во временную базу `pipu_verify`, сверяются
+  таблицы и число строк, база удаляется; время последней успешной проверки — `backups/.last-verify`, ошибки —
+  в `docker compose logs backup` («ПРОВЕРКА НЕ ПРОЙДЕНА»). Тот же цикл копия → проверка → восстановление
+  выполняется в CI (`ci / db`) на базе после сквозного сценария.
+- `update.sh` перед обновлением делает внеочередную копию.
+- Вручную: `docker compose run --rm backup once` — копия сейчас; `docker compose run --rm backup verify /backups/daily/<файл>`.
+- Восстановление: `./restore.sh` — список копий, `./restore.sh daily/pipu-….dump` — останавливает api, рекомендации и
+  анализ, проверяет копию, переименовывает текущую базу в `pipu_before_restore_<время>` (страховка; удалить —
+  `docker compose exec postgres dropdb -U pipu <имя>`), восстанавливает и запускает сервисы; поиск переиндексируется
+  при старте api. Redis (сессии волны, очереди) не восстанавливается — пользователи просто начнут новую волну.
+- Копии лежат на том же сервере: для защиты от потери диска синхронизируйте `/srv/pipu/backups` на другую машину
+  (например, `rclone sync` или `rsync` по cron).
 - Meilisearch, кэши и модели **не бэкапятся** — восстанавливаются (`reindex`, повторный транскод / анализ).
 - Признаки анализа хранятся в Postgres — после восстановления из бэкапа повторный многочасовой анализ не нужен.
 - Сама музыка — на NFS, вне зоны ответственности приложения.

docs/design.md

@@ -48,8 +48,9 @@
 | `elev` | `#111726` | `#FFFFFF` | Поповеры, меню |
 | `hover` | `rgba(120,150,255,.07)` | `rgba(30,60,140,.06)` | Подсветка при наведении |
 | `line` / `line2` | `rgba(130,160,255,.10)` / `.18` | `rgba(20,35,80,.10)` / `.17` | Разделители / рамки |
-| `text` / `text2` / `text3` | `#EDF1FF` / `#A0ABC6` / `#737F9C` | `#0A0F1E` / `#4B5675` / `#677290` | Текст: основной / вторичный / подписи |
+| `text` / `text2` / `text3` | `#EDF1FF` / `#A0ABC6` / `#7F8BA8` | `#0A0F1E` / `#4B5675` / `#5C6785` | Текст: основной / вторичный / подписи |
 | `accent` / `accent2` | `#2F80FF` / `#5E9BFF` | `#1F6FF2` / `#1F6FF2` | Основной акцент, ссылки |
+| `accent-fill` / `accent-fill2` | `#1A66E6` / `#1F6FF2` | `#1A63DB` / `#165ED6` | Заливка под белым текстом (кнопки, выбранные сегменты) и её hover — контраст ≥ 4.5:1 |
 | `accent-soft` | `rgba(47,128,255,.15)` | `rgba(31,111,242,.10)` | Активный пункт меню, фокус |
 | `violet` / `violet-soft` | `#9B7CFF` / `rgba(124,92,255,.16)` | `#6A47F0` / `.10` | Второй акцент (волна, бейджи) |
 | `ok` / `ok-soft` | `#2FD39A` | `#0E9465` | Успех |

docs/install-guide.md

@@ -250,8 +250,10 @@ curl -s https://music.example.com/readyz
    приложение попросит обновиться.
 
 Дальше приложение обновляется само: с версии M5 оно проверяет новые релизы через ваш сервер
-и предлагает обновиться ([mobile.md](mobile.md#самообновление)). Для этого в `.env` сервера нужно заполнить
-`GITEA_URL`, `GITEA_REPO` и `GITEA_TOKEN` (токен только на чтение).
+и предлагает обновиться ([mobile.md](mobile.md#самообновление)). Адрес Gitea и репозиторий (`GITEA_URL`, `GITEA_REPO`)
+`install.sh` и `update.sh` берут из `git remote` клона; `GITEA_TOKEN` (только на чтение) нужен, если репозиторий
+закрытый. Если сервер не видит Gitea по внешнему адресу — впишите внутренний в `GITEA_URL`. Раздать приложение —
+ссылка `https://<ваш-домен>/android`.
 
 > Приложению нужен настоящий сертификат. С самоподписанным сертификатом и голым IP-адресом подключиться не получится.
 > Поэтому нужен домен с Let's Encrypt, как в этой инструкции.
@@ -314,12 +316,21 @@ cd /opt/pipu-music/deploy && ./update.sh
 пересобирает образы и перезапускает сервисы; старые образы удаляются. Миграции БД применяются
 автоматически при старте API.
 
-Бэкап базы (всё остальное восстанавливается само — см. [deployment.md](deployment.md#бэкапы)):
+Бэкапы базы делаются сами: каждую ночь в `/srv/pipu/backups`, раз в неделю копия проверяется восстановлением,
+перед каждым `update.sh` — внеочередная копия. Всё остальное восстанавливается само — см.
+[deployment.md](deployment.md#бэкапы). Копия сейчас и восстановление:
 
 ```bash
-docker compose exec -T postgres pg_dump -U pipu -Fc pipu > /srv/pipu/backups/pipu-$(date +%F).dump
+cd /opt/pipu-music/deploy && docker compose run --rm backup once
 ```
 
+```bash
+cd /opt/pipu-music/deploy && ./restore.sh
+```
+
+Без аргумента `restore.sh` показывает список копий; с именем файла (`./restore.sh daily/pipu-20261020-033000.dump`)
+восстанавливает базу, сохранив прежнюю рядом.
+
 Остановить сервис, сохранив данные:
 
 ```bash
@@ -339,6 +350,8 @@ cd /opt/pipu-music/deploy && docker compose down
 | Сборка падает на скачивании зависимостей | Нет интернета или DNS на сервере; повторите `./update.sh` — уже собранные слои берутся из кэша |
 | Сборка падает: «no space left on device» | Очистите кэш сборки: `docker builder prune` |
 | `permission denied … docker.sock` | Пользователь не в группе `docker` (шаг 3) или вы не перелогинились |
+| Сервисы не стартуют: `… is not a shared or slave mount` | `sudo mount --make-rshared /` (и добавьте в автозагрузку); на systemd-системах корень и так shared |
+| `update.sh`: «LIBRARY_HOST … пуст» | Диск с музыкой не смонтирован: `findmnt /mnt/music`, `sudo mount -a`; если папка и должна быть пустой — `PIPU_ALLOW_EMPTY_LIBRARY=1 ./update.sh` |
 | Сервисы не стартуют: `bind source path does not exist: /mnt/music` | Диск не смонтирован: `findmnt /mnt/music`, `sudo mount -a`; путь в `LIBRARY_HOST` в `.env` |
 | Хранилище «Локальная папка» пустое или ошибка доступа | Диск смонтирован (`ls /mnt/music`); права на чтение для всех — `sudo chmod -R a+rX /mnt/music` (шаг 4) |
 | `storage-agent` не стартует, ошибка про propagation / shared mount | Ещё раз `sudo ./install.sh`; на хосте `findmnt -o TARGET,PROPAGATION /srv/pipu/library` должно показать `shared` |

docs/library-and-storage.md

@@ -35,8 +35,7 @@
   `fsync`, сверка SHA-256, атомарный `rename`. Перезапись существующих файлов и удаление запрещены на уровне кода агента.
 - Права на NFS-сервере: экспорт должен разрешать запись для UID/GID агента (`PIPU_FILE_UID` / `PIPU_FILE_GID`,
   задаются в `.env` под владельца музыки на файловом сервере); новые файлы — `0644`, каталоги — `0755`.
-- `POST /admin/sources/{id}/test` для такого источника дополнительно проверяет запись: создаёт и удаляет
-  `.pipu-write-test` в корне.
+- `POST /admin/sources/{id}/test` для такого источника дополнительно проверяет право записи — без создания файлов.
 - У источника задаётся `write_template` — шаблон пути для новых файлов, с автоподбором по существующей структуре
   и проверкой обратимости через регэкспы источника (подробно — [uploads.md](uploads.md#7-раскладка-в-хранилище-как-принято-на-сервере)).
 
@@ -44,8 +43,11 @@
 - Агент: `POST /internal/files` `{source_id, local_path?, rel_path, staging_path, sha256}` → `{rel_path, size, renamed}`;
   `POST /internal/files/test` — проверка записи. NFS с `accepts_uploads` монтируется rw в `/library-rw/<id>` (каталог
   внутри контейнера агента), а в `/library/<id>` — bind этой точки с `remount,ro`. Local-источники пишутся через
-  `/library-host-rw` (тот же `LIBRARY_HOST`, на запись — только у агента). Итоговое имя создаётся жёсткой ссылкой
-  на временный файл (`link` не перезаписывает, в отличие от `rename`); занято — ` (2)`, ` (3)`…
+  `/library-host-rw` (тот же `LIBRARY_HOST`, на запись — только у агента). На музыкальный диск не пишется ничего,
+  кроме самих треков: файл создаётся сразу под итоговым именем (`O_EXCL` — существующий не перезаписывается;
+  занято — ` (2)`, ` (3)`…), `fsync`, сверка SHA-256; при ошибке агент удаляет свой недописанный файл и созданные
+  для него пустые каталоги. Проверка записи — `access(W_OK)` и флаг read-only файловой системы, без пробного файла.
+  Остальные сервисы видят музыку только на чтение (`read_only` в compose).
   Владелец новых файлов и каталогов — `PIPU_FILE_UID` / `PIPU_FILE_GID` (`-1` — не менять).
 - Шаблон: `meta.ParseTemplate` / `Render` (очистка имён, пределы длины), `meta.SuggestTemplate` (регэксп → шаблон через
   `regexp/syntax`: именованные группы → поля, `(?:(?P<disc>\d)-)?` → `{disc:1-}`, необязательная группа → `[ ]`,
@@ -159,7 +161,9 @@ Meilisearch, индексы:
 - Ранжирование: стандартные правила Meilisearch + `popularity:desc` (глобальные засчитанные прослушивания за 90 дней).
 - `/search/suggest` использует `multi-search` (один запрос — три индекса), отдаёт ≤ 3/3/5. Клиент делает debounce 150 мс,
   отменяет предыдущий запрос (`AbortController`).
-- Персонализация (опционально, этап 2): треки, которые пользователь лайкал / часто слушал, поднимаются выше
-  в выдаче `suggest` (re-rank первых 20 на стороне `api`).
+- Персонализация: `suggest` берёт из Meilisearch втрое больше кандидатов и переранжирует их в `api`
+  (`internal/search/personal.go`). Вес объекта — прослушивания + 2 × доигрывания − ранние скипы, лайк трека ±10,
+  реакция на исполнителя ±20; альбом и исполнитель суммируют вес своих треков. Знакомое поднимается на
+  2·ln(1+вес) позиций, нелюбимое опускается на 3 — релевантность остаётся основой порядка.
 - Синхронизация: `api` после изменения каталога ставит документы в батч-очередь; полная переиндексация — задача
   `reindex_search` (индекс собирается во временном индексе и подменяется через `swap-indexes`, без даунтайма).

docs/mobile.md

@@ -16,6 +16,18 @@
 | i18n | i18next, словари из `packages/i18n` |
 | Минимальная версия | Android 8.0 (API 26), target — актуальный API |
 
+## Сборка APK: ABI и 16 КБ страницы
+
+- APK только под `arm64-v8a` (`plugins/withArm64Only.js`): нативные модули собираются под одну ABI, а без фильтра
+  в APK попадали неполные каталоги `x86`, `x86_64`, `armeabi-v7a` из библиотек React Native — эмулятор x86 и
+  32-битные устройства выбирали их и падали при старте (`couldn't find DSO to load: libexpo-modules-core.so`).
+  Эмулятор для проверки — образ arm64 или настоящее устройство.
+- Все `.so` выровнены по 16 КБ: устройства с Android 15+ и 16 КБ страницами памяти не загружают библиотеки
+  с выравниванием 4 КБ, приложение закрывается сразу после запуска. Skia 2.0.0-next.4 собиралась без
+  `ANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES` — флаг добавлен pnpm-патчем (`patches/`).
+- `scripts/check-apk.mjs` в релизе проверяет ABI, наличие ключевых библиотек и выравнивание; без этого релиз
+  не публикуется.
+
 ## Экраны
 
 Макет — `Pipu Android.dc.html`, сводка решений — [design.md](design.md#android).
@@ -82,6 +94,8 @@
 
 ## Самообновление
 
+Первая установка — публичная страница `/android` веб-клиента: последний APK, адрес сервера и инструкция.
+
 Приложение распространяется только через Gitea Releases (не Google Play).
 
 **Поток:**

docs/recommendations.md

@@ -152,6 +152,16 @@ score = 0.35·cos(e, session_vec) + 0.25·max_c cos(e, centroid_c) + 0.15·artis
 Обучение — ночью; новая модель активируется, только если офлайн-NDCG@10 не хуже активной более чем на 2%.
 Пока размеченных показов меньше ~20k, используется v1 (переключение автоматическое по порогу).
 
+Реализация (`pipu_rec/train/ranker.py`): при каждом показе волна пишет вектор признаков кандидата
+в `rec_impression_features` (29 признаков, `FEATURE_NAMES` в `wave/engine.py`; порядок версионируется
+`FEATURES_VERSION`). Ночью признаки соединяются с исходами `wave_impressions`, группа — сессия волны;
+валидация — сессии последних 7 дней. Модель включается, если её NDCG@10 не ниже порядка по оценке v1
+и не хуже активной более чем на 2%. Модель хранится строкой в `model_versions.artifact` (kind `ranker`),
+сервис загружает активную при старте и после ночного обучения; в выдаче её порядок заменяет оценку v1,
+MMR-разнообразие и квоты остаются. Пока модели нет, `model_ver` показа — версия v1.
+Онлайн-сравнение — админка «Библиотека → Моя волна»: доля доигрываний, ранних скипов и лайков
+за 7 дней отдельно по каждому `model_ver` показа.
+
 ### 6.4 Занятия и настроения
 
 Каждый контекст — профиль целевых значений аудиопризнаков (`services/recommender/config/contexts.yaml`,
@@ -191,6 +201,11 @@ score = 0.35·cos(e, session_vec) + 0.25·max_c cos(e, centroid_c) + 0.15·artis
 что одному пользователю лучше заходит `fresh`, а другому — `rediscover`. Параметры затухают
 (×0.99 в день), чтобы подстраиваться под смену вкуса.
 
+Реализация (`pipu_rec/train/bandit.py`): параметры пересчитываются ночью по `wave_impressions` за 90 дней
+(награда — `complete` / `like`) в `user_profiles_rec.bandit`; при сборке пачки источник получает бонус
+`0.2·(θ − 0.5)`, где θ ~ Beta(α, β) (источник без наблюдений — нейтральные 0.5). `exploration` следует за
+успехом `fresh` относительно остальных источников (0.05–0.4).
+
 ### 6.7 Реакция в реальном времени
 
 - Клиент держит в очереди 2 трека вперёд и запрашивает новую пачку, когда осталось ≤ 2.
@@ -204,6 +219,10 @@ score = 0.35·cos(e, session_vec) + 0.25·max_c cos(e, centroid_c) + 0.15·artis
 - **Новый пользователь**: опциональный онбординг (выбрать 3+ жанра или исполнителя) → начальные центроиды.
   Без онбординга — первые пачки из `popular` и максимально разнообразных кластеров библиотеки
   (по одному треку из разных кластеров), exploration 40% на первые 30 треков.
+- Реализация онбординга: `GET /onboarding` (40 исполнителей с наибольшим числом треков, 24 жанра; `required` —
+  не пройден и своей истории < 10 треков), `PUT /me/onboarding` → `user_profiles_rec.onboarding`; пустой выбор —
+  пропуск. Рекомендатель, пока своих оценок < 30, добавляет псевдооценки: треки выбранных исполнителей +1,
+  жанров +0.5 (до 300 треков). Веб показывает онбординг на главной вместо волны.
 - **Новый трек**: сразу доступен через `audio_sim` / `fresh` (как только проанализирован), без единого прослушивания.
 
 ## 8. Обучение на всех пользователях

docs/roadmap.md

@@ -49,10 +49,15 @@
 - ALS, центроиды вкусов, LightGBM-ранжировщик, бандит, онбординг, ночное обучение с проверкой метрик.
 - Персонализация suggest.
 - **Готово, когда:** на накопленных данных v2 лучше v1 по офлайн-NDCG и онлайн early-skip rate.
+- **Состояние:** всё реализовано (v0.8, v1.0). Ранжировщик включается сам после ~20 тыс. размеченных показов;
+  критерий проверяется по метрикам версий в админке («Библиотека → Моя волна») и NDCG в `model_versions`.
 
 ## M7 — Стабилизация (v1.0)
 - Нагрузочный smoke, бэкапы и восстановление (проверено), документация администратора,
   доступность, полировка анимаций, багфиксы.
+- **Состояние:** v1.0 — бэкапы с еженедельной проверкой восстановления (и цикл копия → проверка → восстановление
+  в CI), [руководство администратора](admin-guide.md), аудит доступности WCAG 2.1 AA, k6-smoke
+  (`tests/load/smoke.js`, запускается вручную на сервере перед релизом).
 
 ## Дальше (идеи)
 - Плейлисты, волна по исполнителю / треку, ежедневные подборки, тексты песен, Chromecast / DLNA,

docs/testing.md

@@ -49,4 +49,28 @@
 - Покрытие: Go и Python ≥ 70% по строкам для `internal/*/service` и `pipu_rec/*`; для `auth/policy` — 100% веток.
 - Тест на каждый исправленный баг.
 - Flaky-тесты помечаются и чинятся в течение недели, а не перезапускаются бесконечно.
-- Нагрузочный smoke (k6, вручную перед релизом): 100 одновременных слушателей, 20 rps на suggest — p95 в рамках целей.
+- Нагрузочный smoke (k6, вручную перед релизом) — см. ниже.
+
+## Нагрузочный smoke
+
+`tests/load/smoke.js` (k6 ≥ 0.50), 3 минуты: 100 одновременных слушателей волны (старт волны, начало потока
+каждого трека — первые 64 КБ, события прослушивания, следующая пачка с отзывами) и 20 запросов подсказок поиска
+в секунду. Пороги — цели из [api.md](api.md) и [recommendations.md](recommendations.md#10-требования-к-производительности):
+
+| Запрос | p95 |
+|---|---|
+| `GET /search/suggest` | < 50 мс |
+| `POST /wave/sessions/{id}/next` | < 150 мс |
+| `POST /wave/sessions` | < 300 мс |
+| начало потока (`Range: bytes=0-65535`) | < 300 мс |
+| `POST /events` | < 100 мс |
+
+Ошибок < 1%. k6 завершается с ненулевым кодом, если порог не выполнен.
+
+```bash
+k6 run -e BASE_URL=https://music.example.com -e PIPU_USER=loadtest -e PIPU_PASSWORD=… tests/load/smoke.js
+```
+
+Пользователь — отдельный обычный (`role=user`): тест наполняет его историю и лайки. Нагрузку можно менять:
+`-e LISTENERS=20 -e SUGGEST_RPS=5 -e DURATION=1m`. Запускать с машины в той же сети, что и сервер, —
+иначе в цифрах будет задержка канала.

docs/uploads.md

@@ -161,9 +161,9 @@
 2. Запросить у `storage-agent` запись: `POST /internal/files` `{source_id, rel_path, staging_path}`.
    Агент:
    - создаёт каталоги;
-   - копирует во временный файл `.<name>.pipu-tmp` в целевой папке, `fsync`;
-   - сверяет SHA-256 копии со staging;
-   - атомарно переименовывает в итоговое имя.
+   - создаёт файл сразу под итоговым именем (`O_EXCL`, существующий не перезаписывается), копирует, `fsync`;
+   - сверяет SHA-256 копии со staging; при ошибке удаляет свой файл и созданные пустые каталоги —
+     на музыкальный диск не попадает ничего, кроме треков.
 3. Запустить точечный скан файла (`scan_path`) → трек появляется в каталоге и поиске, ставится в аудиоанализ.
    В `media_files` сохраняется `upload_id` — история происхождения.
 4. Удалить файл из staging, освободить квоту, статус `imported`, запись в `audit_log`.

docs/web.md

@@ -101,3 +101,15 @@ apps/web/src/
 
 ## Доступность
 - Вся навигация с клавиатуры, видимый фокус, ARIA-роли у плеера и поиска, контраст AA.
+
+## Доступность
+
+Цель — WCAG 2.1 AA. Проверено axe-core на всех экранах в тёмной и светлой темах (с играющим треком и открытой
+очередью) — нарушений нет. Правила, которые держим:
+- текст на заливке акцента — только `--accent-fill` (белый текст ≥ 4.5:1), вторичный текст `--text3` — ≥ 4.5:1
+  на фоне и поверхностях;
+- у каждого экрана есть `h1`; у кнопок-иконок — `aria-label`, у переключателей — `aria-pressed`;
+- списки треков — `role="list"` / `listitem` (строка фокусируется, Enter запускает трек, лайк и ссылки — отдельные
+  элементы); прогресс-бары подписаны через `aria-labelledby`;
+- выезжающие панели (очередь) забирают фокус при открытии, закрываются по Escape и возвращают фокус на кнопку;
+- `:focus-visible` — обводка акцентом; `prefers-reduced-motion` — анимации и Ambient выключены, волна замедлена.

package.json

@@ -13,7 +13,7 @@
     "generate": "turbo run generate",
     "i18n:check": "pnpm --filter @pipu/i18n check",
     "version:info": "node scripts/version.mjs",
-    "test:scripts": "node --test scripts/version.test.mjs scripts/release.test.mjs"
+    "test:scripts": "node --test scripts/version.test.mjs scripts/release.test.mjs scripts/check-apk.test.mjs"
   },
   "devDependencies": {
     "turbo": "2.5.4",

packages/api-client/src/generated/schema.ts

@@ -880,6 +880,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/admin/library/analysis/retry": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Вернуть в очередь треки, которые не удалось проанализировать (admin) */
+        post: operations["retryAnalysis"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/admin/search/reindex": {
         parameters: {
             query?: never;
@@ -1066,6 +1083,43 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/onboarding": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Онбординг вкуса — исполнители и жанры библиотеки для выбора
+         * @description `required` — показать онбординг: пользователь его не проходил и не пропускал, а своей истории почти нет.
+         */
+        get: operations["getOnboarding"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/me/onboarding": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Сохранить выбор онбординга (или пропуск — пустые списки) */
+        put: operations["saveOnboarding"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/wave/options": {
         parameters: {
             query?: never;
@@ -1181,6 +1235,26 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
+        Onboarding: {
+            required: boolean;
+            artists: {
+                /** Format: uuid */
+                id: string;
+                name: string;
+                track_count: number;
+                /** @description Обложка самого большого альбома исполнителя */
+                cover_url: string | null;
+                cover_colors: string[];
+            }[];
+            genres: {
+                name: string;
+                track_count: number;
+            }[];
+        };
+        OnboardingChoice: {
+            artist_ids: string[];
+            genres: string[];
+        };
         UserRef: {
             /** Format: uuid */
             id: string;
@@ -1435,6 +1509,11 @@ export interface components {
             wave_variant?: "orb" | "liquid";
             /** @enum {string} */
             web_player?: "bar" | "island";
+            /**
+             * @description Где в топбаре веба поиск (по умолчанию center)
+             * @enum {string}
+             */
+            search_position?: "center" | "left" | "right";
             /** @enum {string} */
             mobile_player?: "cover" | "wave";
             ambient?: boolean;
@@ -1955,6 +2034,8 @@ export interface components {
             done: number;
             failed: number;
             analyzer_ver: string | null;
+            /** @description Самая частая ошибка среди неудавшихся — подсказка, что чинить */
+            top_error: string | null;
         };
         /** @description Метрики волны за 7 дней */
         WaveMetrics: {
@@ -1964,6 +2045,15 @@ export interface components {
             /** @description Лайков на 100 треков */
             like_rate: number | null;
             sessions: number;
+            /** @description Те же метрики по версии модели показа (v1 / ALS / ранжировщик) — сравнение онлайн */
+            by_model: components["schemas"]["WaveModelMetrics"][];
+        };
+        WaveModelMetrics: {
+            model_ver: string;
+            served: number;
+            listen_through_rate: number | null;
+            early_skip_rate: number | null;
+            like_rate: number | null;
         };
         AndroidRelease: {
             /** @example 0.6.1 */
@@ -3289,6 +3379,29 @@ export interface operations {
             default: components["responses"]["Problem"];
         };
     };
+    retryAnalysis: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Сколько задач снова в очереди */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        requeued: number;
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
     reindexSearch: {
         parameters: {
             query?: never;
@@ -3599,6 +3712,50 @@ export interface operations {
             default: components["responses"]["Problem"];
         };
     };
+    getOnboarding: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Варианты и состояние */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Onboarding"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    saveOnboarding: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["OnboardingChoice"];
+            };
+        };
+        responses: {
+            /** @description Сохранено */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
     getWaveOptions: {
         parameters: {
             query?: never;

packages/design-tokens/src/generated/tokens.css

@@ -22,9 +22,11 @@
   --line2: rgba(130,160,255,.18);
   --text: #EDF1FF;
   --text2: #A0ABC6;
-  --text3: #737F9C;
+  --text3: #7F8BA8;
   --accent: #2F80FF;
   --accent2: #5E9BFF;
+  --accent-fill: #1A66E6;
+  --accent-fill2: #1F6FF2;
   --accent-soft: rgba(47,128,255,.15);
   --violet: #9B7CFF;
   --violet-soft: rgba(124,92,255,.16);
@@ -56,9 +58,11 @@
     --line2: rgba(20,35,80,.17);
     --text: #0A0F1E;
     --text2: #4B5675;
-    --text3: #677290;
+    --text3: #5C6785;
     --accent: #1F6FF2;
     --accent2: #1F6FF2;
+    --accent-fill: #1A63DB;
+    --accent-fill2: #165ED6;
     --accent-soft: rgba(31,111,242,.10);
     --violet: #6A47F0;
     --violet-soft: rgba(106,71,240,.10);
@@ -90,9 +94,11 @@
   --line2: rgba(20,35,80,.17);
   --text: #0A0F1E;
   --text2: #4B5675;
-  --text3: #677290;
+  --text3: #5C6785;
   --accent: #1F6FF2;
   --accent2: #1F6FF2;
+  --accent-fill: #1A63DB;
+  --accent-fill2: #165ED6;
   --accent-soft: rgba(31,111,242,.10);
   --violet: #6A47F0;
   --violet-soft: rgba(106,71,240,.10);
@@ -123,9 +129,11 @@
   --line2: rgba(130,160,255,.18);
   --text: #EDF1FF;
   --text2: #A0ABC6;
-  --text3: #737F9C;
+  --text3: #7F8BA8;
   --accent: #2F80FF;
   --accent2: #5E9BFF;
+  --accent-fill: #1A66E6;
+  --accent-fill2: #1F6FF2;
   --accent-soft: rgba(47,128,255,.15);
   --violet: #9B7CFF;
   --violet-soft: rgba(124,92,255,.16);

packages/design-tokens/src/generated/tokens.ts

@@ -13,9 +13,11 @@ export const tokens = {
       "line2": "rgba(130,160,255,.18)",
       "text": "#EDF1FF",
       "text2": "#A0ABC6",
-      "text3": "#737F9C",
+      "text3": "#7F8BA8",
       "accent": "#2F80FF",
       "accent2": "#5E9BFF",
+      "accent-fill": "#1A66E6",
+      "accent-fill2": "#1F6FF2",
       "accent-soft": "rgba(47,128,255,.15)",
       "violet": "#9B7CFF",
       "violet-soft": "rgba(124,92,255,.16)",
@@ -42,9 +44,11 @@ export const tokens = {
       "line2": "rgba(20,35,80,.17)",
       "text": "#0A0F1E",
       "text2": "#4B5675",
-      "text3": "#677290",
+      "text3": "#5C6785",
       "accent": "#1F6FF2",
       "accent2": "#1F6FF2",
+      "accent-fill": "#1A63DB",
+      "accent-fill2": "#165ED6",
       "accent-soft": "rgba(31,111,242,.10)",
       "violet": "#6A47F0",
       "violet-soft": "rgba(106,71,240,.10)",

packages/design-tokens/tokens.json

@@ -1,11 +1,11 @@
 {
-  "$comment": "Источник истины дизайн-токенов (docs/design.md). После правки: pnpm --filter @pipu/design-tokens generate",
+  "$comment": "Источник истины дизайн-токенов (docs/design.md). После правки: pnpm --filter @pipu/design-tokens generate. accent-fill — заливка под белым текстом (контраст ≥ 4.5:1, WCAG AA)",
   "color": {
     "dark": {
       "bg": "#05070D", "bg2": "#080B14", "surface": "#0B0F1A", "surface2": "#121827", "surface3": "#1A2236",
       "elev": "#111726", "hover": "rgba(120,150,255,.07)", "line": "rgba(130,160,255,.10)", "line2": "rgba(130,160,255,.18)",
-      "text": "#EDF1FF", "text2": "#A0ABC6", "text3": "#737F9C",
-      "accent": "#2F80FF", "accent2": "#5E9BFF", "accent-soft": "rgba(47,128,255,.15)",
+      "text": "#EDF1FF", "text2": "#A0ABC6", "text3": "#7F8BA8",
+      "accent": "#2F80FF", "accent2": "#5E9BFF", "accent-fill": "#1A66E6", "accent-fill2": "#1F6FF2", "accent-soft": "rgba(47,128,255,.15)",
       "violet": "#9B7CFF", "violet-soft": "rgba(124,92,255,.16)",
       "ok": "#2FD39A", "ok-soft": "rgba(47,211,154,.14)", "warn": "#FFB547", "warn-soft": "rgba(255,181,71,.14)",
       "danger": "#FF5C70", "danger-soft": "rgba(255,92,112,.14)",
@@ -14,8 +14,8 @@
     "light": {
       "bg": "#F3F5FA", "bg2": "#EBEEF5", "surface": "#FFFFFF", "surface2": "#F0F3F9", "surface3": "#E4E9F3",
       "elev": "#FFFFFF", "hover": "rgba(30,60,140,.06)", "line": "rgba(20,35,80,.10)", "line2": "rgba(20,35,80,.17)",
-      "text": "#0A0F1E", "text2": "#4B5675", "text3": "#677290",
-      "accent": "#1F6FF2", "accent2": "#1F6FF2", "accent-soft": "rgba(31,111,242,.10)",
+      "text": "#0A0F1E", "text2": "#4B5675", "text3": "#5C6785",
+      "accent": "#1F6FF2", "accent2": "#1F6FF2", "accent-fill": "#1A63DB", "accent-fill2": "#165ED6", "accent-soft": "rgba(31,111,242,.10)",
       "violet": "#6A47F0", "violet-soft": "rgba(106,71,240,.10)",
       "ok": "#0E9465", "ok-soft": "rgba(14,148,101,.10)", "warn": "#A86200", "warn-soft": "rgba(168,98,0,.10)",
       "danger": "#D32F47", "danger-soft": "rgba(211,47,71,.09)",

packages/i18n/locales/en/admin.json

@@ -158,7 +158,10 @@
     "wave_sessions": "Sessions",
     "wave_listen": "Played ≥ 50%",
     "wave_early_skip": "Early skips",
-    "wave_likes": "Likes per 100"
+    "wave_likes": "Likes per 100",
+    "wave_model": "Model version",
+    "wave_by_model": "Wave model versions compared",
+    "analysis_retry": "Retry"
   },
   "write_template": {
     "title": "Uploads and path template",

packages/i18n/locales/en/auth.json

@@ -20,5 +20,19 @@
     "min_length": "At least {{min}} characters",
     "submit": "Save and continue",
     "logout": "Sign out"
+  },
+  "app": {
+    "link": "Android app",
+    "title": "pipu for Android",
+    "subtitle": "Your music from this server on your phone: My Wave, your collection and offline listening.",
+    "download": "Download APK",
+    "version": "version {{version}}",
+    "step_install": "Open the downloaded file. If Android asks, allow installs from this source.",
+    "step_server": "Launch pipu and enter the server address:",
+    "copy_server": "Copy the server address",
+    "step_updates": "Sign in with your account. The app offers new versions by itself.",
+    "checksum": "SHA-256 checksum",
+    "unavailable": "The app is not available yet: release downloads are not configured on this server (docs/deployment.md).",
+    "to_login": "Sign in to the web app"
   }
 }

packages/i18n/locales/en/common.json

@@ -39,7 +39,8 @@
   "profile": {
     "menu": "Profile menu",
     "settings": "Settings",
-    "logout": "Sign out"
+    "logout": "Sign out",
+    "android_app": "Android app"
   },
   "roles": {
     "admin": "Administrator",
@@ -81,7 +82,8 @@
     "source_wave": "My Wave",
     "source_queue": "Queue",
     "queue": "Queue",
-    "source_wave_seed": "Artist wave · {{label}}"
+    "source_wave_seed": "Artist wave · {{label}}",
+    "queue_wave": "The wave never ends: next tracks are picked as you listen"
   },
   "settings": {
     "title": "Settings",
@@ -113,7 +115,11 @@
     "player_island": "Island",
     "ambient": "Ambient background",
     "on": "On",
-    "off": "Off"
+    "off": "Off",
+    "search_position": "Search position",
+    "search_left": "Left",
+    "search_center": "Center",
+    "search_right": "Right"
   },
   "form": {
     "show_password": "Show password",
@@ -278,5 +284,17 @@
     "cache": "Recent tracks cache",
     "cache_clear": "Clear ({{size}} MB)",
     "cache_pending": "Will be cleared on next launch"
+  },
+  "onboarding": {
+    "title": "What do you like to listen to?",
+    "subtitle": "Pick a few artists and genres to start My Wave. After that it learns from what you play.",
+    "artists": "Artists",
+    "genres": "Genres",
+    "skip": "Skip",
+    "done": "Done — to the wave",
+    "pick_more_one": "Pick {{count}} more artist",
+    "pick_more_few": "Pick {{count}} more artists",
+    "pick_more_many": "Pick {{count}} more artists",
+    "pick_more_other": "Pick {{count}} more artists"
   }
 }

packages/i18n/locales/ru/admin.json

@@ -158,7 +158,10 @@
     "wave_sessions": "Сессий",
     "wave_listen": "Дослушано ≥ 50%",
     "wave_early_skip": "Ранние скипы",
-    "wave_likes": "Лайков на 100"
+    "wave_likes": "Лайков на 100",
+    "wave_model": "Версия модели",
+    "wave_by_model": "Сравнение версий модели волны",
+    "analysis_retry": "Повторить"
   },
   "write_template": {
     "title": "Приём загрузок и шаблон пути",

packages/i18n/locales/ru/auth.json

@@ -20,5 +20,19 @@
     "min_length": "Не короче {{min}} символов",
     "submit": "Сохранить и продолжить",
     "logout": "Выйти"
+  },
+  "app": {
+    "link": "Приложение для Android",
+    "title": "pipu для Android",
+    "subtitle": "Ваша музыка с этого сервера на телефоне: «Моя волна», коллекция и офлайн-прослушивание.",
+    "download": "Скачать APK",
+    "version": "версия {{version}}",
+    "step_install": "Откройте скачанный файл. Если Android спросит — разрешите установку из этого источника.",
+    "step_server": "Запустите pipu и введите адрес сервера:",
+    "copy_server": "Скопировать адрес сервера",
+    "step_updates": "Войдите своим логином. Новые версии приложение предложит установить само.",
+    "checksum": "Контрольная сумма SHA-256",
+    "unavailable": "Приложение пока недоступно: на сервере не настроена загрузка релизов (docs/deployment.md).",
+    "to_login": "Войти в веб-версию"
   }
 }

packages/i18n/locales/ru/common.json

@@ -39,7 +39,8 @@
   "profile": {
     "menu": "Меню профиля",
     "settings": "Настройки",
-    "logout": "Выйти"
+    "logout": "Выйти",
+    "android_app": "Приложение для Android"
   },
   "roles": {
     "admin": "Администратор",
@@ -81,7 +82,8 @@
     "source_wave": "Моя волна",
     "source_queue": "Очередь",
     "queue": "Очередь",
-    "source_wave_seed": "Волна по исполнителю · {{label}}"
+    "source_wave_seed": "Волна по исполнителю · {{label}}",
+    "queue_wave": "Волна бесконечна: следующие треки подбираются по ходу прослушивания"
   },
   "settings": {
     "title": "Настройки",
@@ -113,7 +115,11 @@
     "player_island": "Остров",
     "ambient": "Живой фон",
     "on": "Вкл.",
-    "off": "Выкл."
+    "off": "Выкл.",
+    "search_position": "Расположение поиска",
+    "search_left": "Слева",
+    "search_center": "По центру",
+    "search_right": "Справа"
   },
   "form": {
     "show_password": "Показать пароль",
@@ -278,5 +284,17 @@
     "cache": "Кэш недавних треков",
     "cache_clear": "Очистить ({{size}} МБ)",
     "cache_pending": "Очистится при следующем запуске"
+  },
+  "onboarding": {
+    "title": "Что вы любите слушать?",
+    "subtitle": "Отметьте несколько исполнителей и жанров — с них начнётся «Моя волна». Дальше она будет учиться на ваших прослушиваниях.",
+    "artists": "Исполнители",
+    "genres": "Жанры",
+    "skip": "Пропустить",
+    "done": "Готово — к волне",
+    "pick_more_one": "Выберите ещё {{count}} исполнителя",
+    "pick_more_few": "Выберите ещё {{count}} исполнителя",
+    "pick_more_many": "Выберите ещё {{count}} исполнителей",
+    "pick_more_other": "Выберите ещё {{count}} исполнителя"
   }
 }

patches/@shopify__react-native-skia@2.0.0-next.4.patch

@@ -0,0 +1,15 @@
+diff --git a/android/build.gradle b/android/build.gradle
+index c5431ee7db4fccb4a67fc790ef95db00b5b545dc..bc5feca88bf56c0bf5ac5c4b03f8ab57b693eef5 100644
+--- a/android/build.gradle
++++ b/android/build.gradle
+@@ -156,7 +156,9 @@ android {
+                 arguments '-DANDROID_STL=c++_shared',
+                           "-DREACT_NATIVE_VERSION=${REACT_NATIVE_VERSION}",
+                           "-DNODE_MODULES_DIR=${nodeModules}",
+-                          "-DPREBUILT_DIR=${prebuiltDir}"
++                          "-DPREBUILT_DIR=${prebuiltDir}",
++                          // 16 КБ страницы памяти (Android 15+): иначе librnskia.so не загружается на таких устройствах
++                          "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+ 
+             }
+         }

pnpm-lock.yaml

@@ -4,6 +4,9 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+patchedDependencies:
+  '@shopify/react-native-skia@2.0.0-next.4': ae341532dba11d4a93999214787e561932c027da2a86640d9f1bcad8ba5910b7
+
 importers:
 
   .:
@@ -37,7 +40,7 @@ importers:
         version: 11.4.1(react-native@0.79.6(@babel/core@7.29.7)(@types/react@19.0.14)(react@19.0.0)(supports-color@10.2.2))
       '@shopify/react-native-skia':
         specifier: 2.0.0-next.4
-        version: 2.0.0-next.4(react-native-reanimated@3.17.5(@babel/core@7.29.7)(react-native@0.79.6(@babel/core@7.29.7)(@types/react@19.0.14)(react@19.0.0)(supports-color@10.2.2))(react@19.0.0))(react-native@0.79.6(@babel/core@7.29.7)(@types/react@19.0.14)(react@19.0.0)(supports-color@10.2.2))(react@19.0.0)
+        version: 2.0.0-next.4(patch_hash=ae341532dba11d4a93999214787e561932c027da2a86640d9f1bcad8ba5910b7)(react-native-reanimated@3.17.5(@babel/core@7.29.7)(react-native@0.79.6(@babel/core@7.29.7)(@types/react@19.0.14)(react@19.0.0)(supports-color@10.2.2))(react@19.0.0))(react-native@0.79.6(@babel/core@7.29.7)(@types/react@19.0.14)(react@19.0.0)(supports-color@10.2.2))(react@19.0.0)
       '@tanstack/react-query':
         specifier: ^5.104.4
         version: 5.104.4(@types/react@19.0.14)(react@19.0.0)
@@ -5396,7 +5399,7 @@ snapshots:
   '@rollup/rollup-win32-x64-msvc@4.64.10':
     optional: true
 
-  '@shopify/react-native-skia@2.0.0-next.4(react-native-reanimated@3.17.5(@babel/core@7.29.7)(react-native@0.79.6(@babel/core@7.29.7)(@types/react@19.0.14)(react@19.0.0)(supports-color@10.2.2))(react@19.0.0))(react-native@0.79.6(@babel/core@7.29.7)(@types/react@19.0.14)(react@19.0.0)(supports-color@10.2.2))(react@19.0.0)':
+  '@shopify/react-native-skia@2.0.0-next.4(patch_hash=ae341532dba11d4a93999214787e561932c027da2a86640d9f1bcad8ba5910b7)(react-native-reanimated@3.17.5(@babel/core@7.29.7)(react-native@0.79.6(@babel/core@7.29.7)(@types/react@19.0.14)(react@19.0.0)(supports-color@10.2.2))(react@19.0.0))(react-native@0.79.6(@babel/core@7.29.7)(@types/react@19.0.14)(react@19.0.0)(supports-color@10.2.2))(react@19.0.0)':
     dependencies:
       canvaskit-wasm: 0.40.0
       react: 19.0.0

pnpm-workspace.yaml

@@ -6,6 +6,9 @@ packages:
 allowBuilds:
   esbuild: true
 
+patchedDependencies:
+  '@shopify/react-native-skia@2.0.0-next.4': patches/@shopify__react-native-skia@2.0.0-next.4.patch
+
 # Изолированная раскладка node_modules (pnpm 11). Expo вычисляет react-native.config.js пакета expo
 # по пути через симлинк apps/mobile/node_modules/expo, и оттуда require('expo-modules-autolinking')
 # находится только в корневом node_modules. Без этого autolinking молча генерирует неверный импорт

scripts/check-apk.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// Проверка собранного APK перед публикацией (release.yml):
+//  - нативные библиотеки только под arm64-v8a: неполный каталог другой ABI роняет приложение при старте
+//    («couldn't find DSO to load: libexpo-modules-core.so» на x86-эмуляторе);
+//  - есть библиотеки, без которых приложение не запустится;
+//  - PT_LOAD-сегменты каждой .so выровнены по 16 КБ: иначе на устройствах с 16 КБ страницами памяти
+//    (Android 15+) библиотека не загружается и приложение закрывается сразу после запуска.
+// Запуск: node scripts/check-apk.mjs app-release.apk
+import { readFileSync } from 'node:fs';
+import { inflateRawSync } from 'node:zlib';
+
+export const ABI = 'arm64-v8a';
+export const REQUIRED = ['libreactnative.so', 'libhermes.so', 'libexpo-modules-core.so', 'librnskia.so', 'libreanimated.so'];
+const PAGE = 16384;
+
+/** Файлы ZIP по центральному каталогу: имя → содержимое. */
+export function zipEntries(buf) {
+  let eocd = buf.length - 22;
+  while (eocd >= 0 && buf.readUInt32LE(eocd) !== 0x06054b50) eocd--;
+  if (eocd < 0) throw new Error('not a zip file');
+  const count = buf.readUInt16LE(eocd + 10);
+  let p = buf.readUInt32LE(eocd + 16);
+  const out = new Map();
+  for (let i = 0; i < count; i++) {
+    const method = buf.readUInt16LE(p + 10);
+    const size = buf.readUInt32LE(p + 20);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const local = buf.readUInt32LE(p + 42);
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+    out.set(name, () => {
+      const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28);
+      const raw = buf.subarray(start, start + size);
+      return method === 0 ? raw : inflateRawSync(raw);
+    });
+    p += 46 + nameLen + extraLen + commentLen;
+  }
+  return out;
+}
+
+/** Наименьшее выравнивание PT_LOAD-сегментов 64-битной ELF-библиотеки. */
+export function loadAlignment(elf) {
+  if (elf.readUInt32BE(0) !== 0x7f454c46 || elf[4] !== 2) throw new Error('not a 64-bit ELF');
+  const phoff = Number(elf.readBigUInt64LE(0x20));
+  const phentsize = elf.readUInt16LE(0x36);
+  const phnum = elf.readUInt16LE(0x38);
+  let min = Infinity;
+  for (let i = 0; i < phnum; i++) {
+    const off = phoff + i * phentsize;
+    if (elf.readUInt32LE(off) === 1) min = Math.min(min, Number(elf.readBigUInt64LE(off + 0x30)));
+  }
+  return min;
+}
+
+export function checkApk(buf) {
+  const problems = [];
+  const entries = zipEntries(buf);
+  const libs = [...entries.keys()].filter((n) => n.startsWith('lib/') && n.endsWith('.so'));
+  const abis = new Set(libs.map((n) => n.split('/')[1]));
+  for (const abi of abis) if (abi !== ABI) problems.push(`лишняя ABI в APK: lib/${abi}/`);
+  const mine = new Set(libs.filter((n) => n.startsWith(`lib/${ABI}/`)).map((n) => n.split('/')[2]));
+  for (const lib of REQUIRED) if (!mine.has(lib)) problems.push(`нет lib/${ABI}/${lib}`);
+  for (const name of libs.filter((n) => n.startsWith(`lib/${ABI}/`))) {
+    const align = loadAlignment(entries.get(name)());
+    if (align < PAGE) problems.push(`${name}: сегменты выровнены по ${align} байт, нужно ${PAGE} (16 КБ страницы)`);
+  }
+  return { libs: mine.size, problems };
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('check-apk.mjs')) {
+  const file = process.argv[2];
+  if (!file) {
+    console.error('usage: node scripts/check-apk.mjs <apk>');
+    process.exit(2);
+  }
+  const { libs, problems } = checkApk(readFileSync(file));
+  if (problems.length) {
+    for (const p of problems) console.error(`✗ ${p}`);
+    process.exit(1);
+  }
+  console.log(`APK: ${libs} библиотек ${ABI}, все выровнены по 16 КБ`);
+}

scripts/check-apk.test.mjs

@@ -0,0 +1,71 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { checkApk, loadAlignment, REQUIRED } from './check-apk.mjs';
+
+/** ELF64 с одним PT_LOAD и заданным выравниванием. */
+function elf(align) {
+  const b = Buffer.alloc(64 + 56);
+  b.writeUInt32BE(0x7f454c46, 0);
+  b[4] = 2;
+  b.writeBigUInt64LE(64n, 0x20);
+  b.writeUInt16LE(56, 0x36);
+  b.writeUInt16LE(1, 0x38);
+  b.writeUInt32LE(1, 64);
+  b.writeBigUInt64LE(BigInt(align), 64 + 0x30);
+  return b;
+}
+
+/** ZIP без сжатия из пар [имя, содержимое]. */
+function zip(files) {
+  const locals = [];
+  const central = [];
+  let offset = 0;
+  for (const [name, data] of files) {
+    const n = Buffer.from(name);
+    const lh = Buffer.alloc(30);
+    lh.writeUInt32LE(0x04034b50, 0);
+    lh.writeUInt32LE(data.length, 18);
+    lh.writeUInt32LE(data.length, 22);
+    lh.writeUInt16LE(n.length, 26);
+    locals.push(lh, n, data);
+    const ch = Buffer.alloc(46);
+    ch.writeUInt32LE(0x02014b50, 0);
+    ch.writeUInt32LE(data.length, 20);
+    ch.writeUInt32LE(data.length, 24);
+    ch.writeUInt16LE(n.length, 28);
+    ch.writeUInt32LE(offset, 42);
+    central.push(ch, n);
+    offset += 30 + n.length + data.length;
+  }
+  const cd = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(files.length, 8);
+  end.writeUInt16LE(files.length, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, end]);
+}
+
+test('reads the smallest PT_LOAD alignment', () => {
+  assert.equal(loadAlignment(elf(16384)), 16384);
+  assert.equal(loadAlignment(elf(4096)), 4096);
+});
+
+test('accepts an arm64-only APK aligned to 16 KB', () => {
+  const apk = zip(REQUIRED.map((l) => [`lib/arm64-v8a/${l}`, elf(16384)]));
+  assert.deepEqual(checkApk(apk).problems, []);
+});
+
+test('rejects other ABIs, missing libraries and 4 KB alignment', () => {
+  const libs = REQUIRED.filter((l) => l !== 'libexpo-modules-core.so').map((l) => [
+    `lib/arm64-v8a/${l}`,
+    elf(l === 'librnskia.so' ? 4096 : 16384),
+  ]);
+  const { problems } = checkApk(zip([...libs, ['lib/x86_64/libjsi.so', elf(16384)]]));
+  assert.equal(problems.length, 3);
+  assert.match(problems.join('\n'), /lib\/x86_64/);
+  assert.match(problems.join('\n'), /libexpo-modules-core\.so/);
+  assert.match(problems.join('\n'), /librnskia\.so.*4096/);
+});

services/api/cmd/api/e2e_test.go

@@ -271,6 +271,27 @@ func TestUserJourney(t *testing.T) {
 	c.ok("GET", "/api/v1/me/likes", nil, &likes)
 	require.Equal(t, 1, likes.Total)
 
+	// Персональные подсказки: лайкнутый трек — первым среди треков альбома.
+	var sug struct {
+		Tracks []track `json:"tracks"`
+	}
+	c.ok("GET", "/api/v1/search/suggest?q="+url.QueryEscape("кино"), nil, &sug)
+	require.NotEmpty(t, sug.Tracks)
+	require.Equal(t, tr.ID, sug.Tracks[0].ID)
+
+	// 7½. Онбординг: варианты из библиотеки, выбор сохраняется, второй раз не предлагается.
+	var onb struct {
+		Required bool `json:"required"`
+		Artists  []struct {
+			ID string `json:"id"`
+		} `json:"artists"`
+	}
+	c.ok("GET", "/api/v1/onboarding", nil, &onb)
+	require.NotEmpty(t, onb.Artists)
+	c.ok("PUT", "/api/v1/me/onboarding", map[string]any{"artist_ids": []string{onb.Artists[0].ID}, "genres": []string{}}, nil)
+	c.ok("GET", "/api/v1/onboarding", nil, &onb)
+	require.False(t, onb.Required)
+
 	// 8. «Моя волна»: рекомендатель недоступен — запасная волна из библиотеки.
 	var wave struct {
 		SessionID string  `json:"session_id"`

services/api/cmd/api/main.go

@@ -170,7 +170,7 @@ func newApp(ctx context.Context, cfg config.API, pool *pgxpool.Pool, rdb *redis.
 		Auth:        auth.NewHandler(authSvc, cfg.CookieSecure),
 		AuthService: authSvc,
 		Library:     library.NewHandler(libSvc, libStore, dto, covers, cfg.XAccel),
-		Search:      search.NewHandler(meili, libStore, indexer, dto, log),
+		Search:      search.NewHandler(meili, libStore, indexer, search.NewAffinity(pool), dto, log),
 		Playback:    pb,
 		Wave: wave.NewHandler(pool, &wave.Recommender{URL: cfg.RecommenderURL, Token: cfg.InternalToken,
 			Client: &http.Client{}}, libStore, func() library.DTO { return dto }, log),

services/api/go.mod

@@ -6,6 +6,7 @@ tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen
 
 require (
 	github.com/caarlos0/env/v11 v11.3.1
+	github.com/cespare/xxhash/v2 v2.3.0
 	github.com/getkin/kin-openapi v0.127.0
 	github.com/go-chi/chi/v5 v5.2.2
 	github.com/golang-jwt/jwt/v5 v5.2.2
@@ -16,11 +17,12 @@ require (
 	github.com/redis/go-redis/v9 v9.10.0
 	github.com/stretchr/testify v1.10.0
 	golang.org/x/crypto v0.38.0
+	golang.org/x/sys v0.33.0
+	golang.org/x/text v0.25.0
 )
 
 require (
 	github.com/apapsch/go-jsonmerge/v2 v2.0.0 // indirect
-	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
 	github.com/dprotaso/go-yit v0.0.0-20220510233725-9ba8df137936 // indirect
@@ -43,8 +45,6 @@ require (
 	go.uber.org/multierr v1.11.0 // indirect
 	golang.org/x/mod v0.17.0 // indirect
 	golang.org/x/sync v0.14.0 // indirect
-	golang.org/x/sys v0.33.0 // indirect
-	golang.org/x/text v0.25.0 // indirect
 	golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

services/api/internal/appupdate/appupdate.go

@@ -100,8 +100,10 @@ func NewHandler(cfg Config, log *slog.Logger) *Handler {
 	return &Handler{cfg: cfg, client: &http.Client{Timeout: 10 * time.Minute}, log: log}
 }
 
+// configured — адрес и репозиторий заданы, и это не заглушка из .env.example.
 func (h *Handler) configured() bool {
-	return h.cfg.GiteaURL != "" && h.cfg.Repo != ""
+	return h.cfg.GiteaURL != "" && h.cfg.Repo != "" &&
+		!strings.Contains(h.cfg.GiteaURL, "example.") && !strings.HasPrefix(h.cfg.Repo, "owner/")
 }
 
 func (h *Handler) get(ctx context.Context, url string) (*http.Response, error) {

services/api/internal/auth/auth_test.go

@@ -565,5 +565,6 @@ func TestPublicRoutes(t *testing.T) {
 	e := newEnv(t)
 	assert.Equal(t, http.StatusOK, e.do(http.MethodGet, "/api/v1/server-info", nil).Code)
 	assert.Equal(t, http.StatusOK, e.do(http.MethodGet, "/healthz", nil).Code)
+	assert.NotEqual(t, http.StatusUnauthorized, e.do(http.MethodGet, "/api/v1/app/android/latest", nil).Code, "APK page is public")
 	assert.Equal(t, http.StatusUnauthorized, e.do(http.MethodGet, "/api/v1/unknown", nil).Code)
 }

services/api/internal/auth/handler.go

@@ -241,13 +241,14 @@ func MeDTO(u User) gen.Me {
 
 func uiPrefsDTO(p UIPrefs) gen.UiPrefs {
 	return gen.UiPrefs{
-		Theme:        (*gen.UiPrefsTheme)(p.Theme),
-		WaveVariant:  (*gen.UiPrefsWaveVariant)(p.WaveVariant),
-		WebPlayer:    (*gen.UiPrefsWebPlayer)(p.WebPlayer),
-		MobilePlayer: (*gen.UiPrefsMobilePlayer)(p.MobilePlayer),
-		Ambient:      p.Ambient,
-		CrossfadeS:   p.CrossfadeS,
-		Normalize:    p.Normalize,
+		Theme:          (*gen.UiPrefsTheme)(p.Theme),
+		WaveVariant:    (*gen.UiPrefsWaveVariant)(p.WaveVariant),
+		WebPlayer:      (*gen.UiPrefsWebPlayer)(p.WebPlayer),
+		SearchPosition: (*gen.UiPrefsSearchPosition)(p.SearchPos),
+		MobilePlayer:   (*gen.UiPrefsMobilePlayer)(p.MobilePlayer),
+		Ambient:        p.Ambient,
+		CrossfadeS:     p.CrossfadeS,
+		Normalize:      p.Normalize,
 	}
 }
 
@@ -256,6 +257,7 @@ func uiPrefsFromDTO(p gen.UiPrefs) UIPrefs {
 		Theme:        (*string)(p.Theme),
 		WaveVariant:  (*string)(p.WaveVariant),
 		WebPlayer:    (*string)(p.WebPlayer),
+		SearchPos:    (*string)(p.SearchPosition),
 		MobilePlayer: (*string)(p.MobilePlayer),
 		Ambient:      p.Ambient,
 		CrossfadeS:   p.CrossfadeS,

services/api/internal/auth/middleware.go

@@ -55,6 +55,8 @@ var publicRoutes = map[string]bool{
 	"GET /api/v1/server-info":   true,
 	"POST /api/v1/auth/login":   true,
 	"POST /api/v1/auth/refresh": true,
+	// Android-приложение раздаётся по ссылке /android без входа: в APK нет ничего, кроме клиента.
+	"GET /api/v1/app/android/latest": true,
 }
 
 // Что разрешено, пока пользователь обязан сменить учётные данные / пароль.
@@ -90,7 +92,8 @@ func Middleware(svc *Service, log *slog.Logger) func(http.Handler) http.Handler
 			// Обложки открывает <img> без заголовка Authorization — ссылку защищает подпись.
 			// Аудио открывает <audio> — тоже без заголовка; ссылка подписана для пользователя.
 			cover := (r.Method == http.MethodGet || r.Method == http.MethodHead) &&
-				(strings.HasPrefix(r.URL.Path, "/api/v1/covers/") || strings.HasPrefix(r.URL.Path, "/api/v1/stream/"))
+				(strings.HasPrefix(r.URL.Path, "/api/v1/covers/") || strings.HasPrefix(r.URL.Path, "/api/v1/stream/") ||
+					strings.HasPrefix(r.URL.Path, "/api/v1/app/android/download/"))
 			if !strings.HasPrefix(r.URL.Path, "/api/v1/") || publicRoutes[route] || cover {
 				next.ServeHTTP(w, r.WithContext(ctx))
 				return

services/api/internal/auth/model.go

@@ -37,6 +37,7 @@ type UIPrefs struct {
 	Theme        *string `json:"theme,omitempty"`
 	WaveVariant  *string `json:"wave_variant,omitempty"`
 	WebPlayer    *string `json:"web_player,omitempty"`
+	SearchPos    *string `json:"search_position,omitempty"`
 	MobilePlayer *string `json:"mobile_player,omitempty"`
 	Ambient      *bool   `json:"ambient,omitempty"`
 	CrossfadeS   *int    `json:"crossfade_s,omitempty"`

services/api/internal/auth/validate.go

@@ -86,10 +86,11 @@ var commonPasswords = func() map[string]struct{} {
 }()
 
 var uiPrefEnums = map[string][]string{
-	"theme":         {"dark", "light", "system"},
-	"wave_variant":  {"orb", "liquid"},
-	"web_player":    {"bar", "island"},
-	"mobile_player": {"cover", "wave"},
+	"theme":           {"dark", "light", "system"},
+	"wave_variant":    {"orb", "liquid"},
+	"web_player":      {"bar", "island"},
+	"search_position": {"center", "left", "right"},
+	"mobile_player":   {"cover", "wave"},
 }
 
 // ValidateUIPrefs проверяет значения перечислений и диапазон кроссфейда.
@@ -107,6 +108,7 @@ func ValidateUIPrefs(p UIPrefs) error {
 	}
 	for name, v := range map[string]*string{
 		"theme": p.Theme, "wave_variant": p.WaveVariant, "web_player": p.WebPlayer, "mobile_player": p.MobilePlayer,
+		"search_position": p.SearchPos,
 	} {
 		if err := check(name, v); err != nil {
 			return err
@@ -130,6 +132,9 @@ func MergeUIPrefs(base, patch UIPrefs) UIPrefs {
 	if patch.WebPlayer != nil {
 		base.WebPlayer = patch.WebPlayer
 	}
+	if patch.SearchPos != nil {
+		base.SearchPos = patch.SearchPos
+	}
 	if patch.MobilePlayer != nil {
 		base.MobilePlayer = patch.MobilePlayer
 	}

services/api/internal/dbtest/integration_test.go

@@ -103,7 +103,8 @@ func TestLibraryAndUploads(t *testing.T) {
 	assert.True(t, src.AcceptsUploads)
 	require.NotNil(t, src.WriteTemplate)
 
-	scanner := library.NewScanner(lib, fakeProber{}, library.NewProgressBoard(), log)
+	board := library.NewProgressBoard()
+	scanner := library.NewScanner(lib, fakeProber{}, board, log)
 	var fileIDs []uuid.UUID
 	for _, rel := range []string{"Кино/Группа крови/Кино - Группа крови.flac", "Кино/Группа крови/Кино - Закрой за мной дверь.flac"} {
 		id, err := scanner.ScanFile(ctx, src, root, rel)
@@ -114,6 +115,15 @@ func TestLibraryAndUploads(t *testing.T) {
 	require.NoError(t, err)
 	assert.Equal(t, fileIDs[0], again, "rescan keeps the file row")
 
+	// Пустой каталог при известных файлах (диск не смонтирован) — скан прерывается и ничего не помечает пропавшим.
+	require.NoError(t, scanner.Start(src, t.TempDir(), false))
+	require.Eventually(t, func() bool { p, ok := board.Get(src.ID); return ok && !p.Running }, 10*time.Second, 50*time.Millisecond)
+	p, _ := board.Get(src.ID)
+	assert.Contains(t, p.Error, "is the disk mounted")
+	var missing int
+	require.NoError(t, pool.QueryRow(ctx, `SELECT count(*) FROM media_files WHERE source_id = $1 AND missing_since IS NOT NULL`, src.ID).Scan(&missing))
+	assert.Zero(t, missing)
+
 	// --- Отпечатки ---
 	todo, err := lib.FilesToFingerprint(ctx, true, uuid.Nil, 10)
 	require.NoError(t, err)

services/api/internal/library/fingerprint.go

@@ -198,6 +198,7 @@ func (fp *Fingerprinter) chromaprint() bool {
 func (fp *Fingerprinter) Run(ctx context.Context) {
 	withFP := fp.chromaprint()
 	roots := map[uuid.UUID]string{}
+	unavailable := map[uuid.UUID]bool{} // каталог источника пуст или не открывается — диск не смонтирован
 	var after uuid.UUID
 	for ctx.Err() == nil {
 		todo, err := fp.store.FilesToFingerprint(ctx, withFP, after, 200)
@@ -213,6 +214,9 @@ func (fp *Fingerprinter) Run(ctx context.Context) {
 				return
 			}
 			after = f.ID
+			if unavailable[f.SourceID] {
+				continue
+			}
 			root, ok := roots[f.SourceID]
 			if !ok {
 				if root, err = fp.rootOf(ctx, f.SourceID); err != nil {
@@ -220,12 +224,31 @@ func (fp *Fingerprinter) Run(ctx context.Context) {
 					continue
 				}
 				roots[f.SourceID] = root
+				if empty, err := dirEmpty(root); empty || err != nil {
+					fp.log.Warn("fingerprints: source folder is empty or unreadable, skipped — is the disk mounted?",
+						"source_id", f.SourceID, "root", root, "err", err)
+					unavailable[f.SourceID] = true
+					continue
+				}
 			}
 			fp.process(ctx, f, filepath.Join(root, filepath.FromSlash(f.RelPath)), withFP)
 		}
 	}
 }
 
+func dirEmpty(dir string) (bool, error) {
+	d, err := os.Open(dir)
+	if err != nil {
+		return false, err
+	}
+	defer func() { _ = d.Close() }()
+	names, err := d.Readdirnames(1)
+	if errors.Is(err, io.EOF) {
+		return true, nil
+	}
+	return len(names) == 0, err
+}
+
 func (fp *Fingerprinter) process(ctx context.Context, f FingerprintTodo, abs string, withFP bool) {
 	sum := f.SHA256
 	if sum == nil {

services/api/internal/library/handler.go

@@ -292,6 +292,15 @@ func (h *Handler) ScanSource(ctx context.Context, req gen.ScanSourceRequestObjec
 	return gen.ScanSource202JSONResponse(progressDTO(p)), nil
 }
 
+// RetryAnalysis реализует gen.StrictServerInterface.
+func (h *Handler) RetryAnalysis(ctx context.Context, _ gen.RetryAnalysisRequestObject) (gen.RetryAnalysisResponseObject, error) {
+	n, err := h.svc.RetryAnalysis(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return gen.RetryAnalysis200JSONResponse{Requeued: n}, nil
+}
+
 // GetLibraryStatus реализует gen.StrictServerInterface.
 func (h *Handler) GetLibraryStatus(ctx context.Context, _ gen.GetLibraryStatusRequestObject) (gen.GetLibraryStatusResponseObject, error) {
 	st, err := h.svc.Status(ctx)
@@ -304,13 +313,19 @@ func (h *Handler) GetLibraryStatus(ctx context.Context, _ gen.GetLibraryStatusRe
 		MissingFiles: int(c.Missing), FileErrors: int(c.Errors), Sources: []gen.SourceStatusItem{},
 		Analysis: gen.AnalysisStatus{
 			Queued: st.Analysis.Queued, Running: st.Analysis.Running, Done: st.Analysis.Done,
-			Failed: st.Analysis.Failed, AnalyzerVer: st.Analysis.AnalyzerVer,
+			Failed: st.Analysis.Failed, AnalyzerVer: st.Analysis.AnalyzerVer, TopError: st.Analysis.TopError,
 		},
 		Wave: gen.WaveMetrics{
 			Served: st.Wave.Served, Sessions: st.Wave.Sessions, ListenThroughRate: st.Wave.ListenThrough,
-			EarlySkipRate: st.Wave.EarlySkip, LikeRate: st.Wave.LikeRate,
+			EarlySkipRate: st.Wave.EarlySkip, LikeRate: st.Wave.LikeRate, ByModel: []gen.WaveModelMetrics{},
 		},
 	}
+	for _, m := range st.Wave.ByModel {
+		out.Wave.ByModel = append(out.Wave.ByModel, gen.WaveModelMetrics{
+			ModelVer: m.ModelVer, Served: m.Served, ListenThroughRate: m.ListenThrough,
+			EarlySkipRate: m.EarlySkip, LikeRate: m.LikeRate,
+		})
+	}
 	for _, s := range st.Sources {
 		dto := h.sourceDTO(s)
 		out.Sources = append(out.Sources, gen.SourceStatusItem{

services/api/internal/library/scanner.go

@@ -119,6 +119,15 @@ type walked struct {
 	hash  []byte
 }
 
+func hasPresent(files map[string]FileRow) bool {
+	for _, f := range files {
+		if !f.Missing {
+			return true
+		}
+	}
+	return false
+}
+
 // job — файл, который нужно прочитать.
 type job struct {
 	walked
@@ -135,6 +144,11 @@ type probed struct {
 // ErrScanRunning — скан источника уже идёт.
 var ErrScanRunning = errors.New("library: scan already running")
 
+// ErrSourceEmpty — в каталоге источника нет ни одного файла, а в библиотеке они есть: скорее всего, диск
+// не смонтирован. Скан прерывается, чтобы не пометить всю библиотеку отсутствующей (и через MissingRetention —
+// не удалить треки вместе с историей).
+var ErrSourceEmpty = errors.New("library: source folder is empty but the library has its files — is the disk mounted?")
+
 // Start запускает скан в фоне. root — каталог источника в файловой системе api.
 func (sc *Scanner) Start(src Source, root string, full bool) error {
 	if !sc.board.start(src.ID, full, sc.now()) {
@@ -192,6 +206,9 @@ func (sc *Scanner) run(ctx context.Context, src Source, root string, full bool)
 	if err != nil {
 		return err
 	}
+	if len(found) == 0 && hasPresent(existing) {
+		return ErrSourceEmpty
+	}
 	sc.board.update(src.ID, func(p *Progress) { p.Found = len(found) })
 
 	var (

services/api/internal/library/service.go

@@ -587,6 +587,15 @@ func (s *Service) previewOne(ctx context.Context, root, rel string, patterns []m
 }
 
 // StartScan запускает скан источника в фоне.
+// RetryAnalysis возвращает в очередь треки, которые анализатор не смог обработать (например, пока диск
+// не был смонтирован).
+func (s *Service) RetryAnalysis(ctx context.Context) (int, error) {
+	if err := requirePerm(ctx, auth.PermManageLibrary); err != nil {
+		return 0, err
+	}
+	return s.store.RetryFailedAnalysis(ctx)
+}
+
 func (s *Service) StartScan(ctx context.Context, id uuid.UUID, full bool) (Progress, error) {
 	if err := requirePerm(ctx, auth.PermManageLibrary); err != nil {
 		return Progress{}, err

services/api/internal/library/store.go

@@ -605,7 +605,7 @@ func (st *Store) AlbumCoverPath(ctx context.Context, albumID uuid.UUID) (*string
 // AnalysisCounts — состояние очереди аудиоанализа.
 type AnalysisCounts struct {
 	Queued, Running, Done, Failed int
-	AnalyzerVer                   *string
+	AnalyzerVer, TopError         *string
 }
 
 // AnalysisCounts считает задачи анализа по статусам и текущую версию анализатора.
@@ -614,20 +614,59 @@ func (st *Store) AnalysisCounts(ctx context.Context) (AnalysisCounts, error) {
 	err := st.pool.QueryRow(ctx, `
 		SELECT count(*) FILTER (WHERE status = 'queued'), count(*) FILTER (WHERE status = 'running'),
 			count(*) FILTER (WHERE status = 'done'), count(*) FILTER (WHERE status = 'failed'),
-			(SELECT analyzer_ver FROM track_features ORDER BY analyzed_at DESC LIMIT 1)
-		FROM analysis_jobs`).Scan(&c.Queued, &c.Running, &c.Done, &c.Failed, &c.AnalyzerVer)
+			(SELECT analyzer_ver FROM track_features ORDER BY analyzed_at DESC LIMIT 1),
+			(SELECT error FROM analysis_jobs WHERE status = 'failed' AND error IS NOT NULL
+			 GROUP BY error ORDER BY count(*) DESC LIMIT 1)
+		FROM analysis_jobs`).Scan(&c.Queued, &c.Running, &c.Done, &c.Failed, &c.AnalyzerVer, &c.TopError)
 	if err != nil {
 		return AnalysisCounts{}, fmt.Errorf("library: analysis counts: %w", err)
 	}
 	return c, nil
 }
 
+// RetryFailedAnalysis возвращает неудавшиеся задачи анализа в очередь с нуля попыток.
+func (st *Store) RetryFailedAnalysis(ctx context.Context) (int, error) {
+	tag, err := st.pool.Exec(ctx, `
+		UPDATE analysis_jobs SET status = 'queued', attempts = 0, error = NULL, updated_at = now()
+		WHERE status = 'failed'`)
+	if err != nil {
+		return 0, fmt.Errorf("library: retry analysis: %w", err)
+	}
+	return int(tag.RowsAffected()), nil
+}
+
 // WaveMetrics — метрики волны за 7 дней (docs/recommendations.md#1-цели-и-как-измеряем-успех).
 type WaveMetrics struct {
-	Served, Sessions                   int
+	Served, Sessions int
+	WaveRates
+	ByModel []WaveModelMetrics
+}
+
+// WaveRates — доли по показам с известным исходом (nil — исходов ещё нет).
+type WaveRates struct {
 	ListenThrough, EarlySkip, LikeRate *float32
 }
 
+// WaveModelMetrics — метрики показов одной версии модели.
+type WaveModelMetrics struct {
+	ModelVer string
+	Served   int
+	WaveRates
+}
+
+func rates(judged, through, early, liked int) WaveRates {
+	if judged == 0 {
+		return WaveRates{}
+	}
+	lt, es, lr := float32(through)/float32(judged), float32(early)/float32(judged), float32(liked)*100/float32(judged)
+	return WaveRates{ListenThrough: &lt, EarlySkip: &es, LikeRate: &lr}
+}
+
+const waveOutcomes = `count(outcome),
+			count(*) FILTER (WHERE outcome IN ('complete', 'like')),
+			count(*) FILTER (WHERE outcome IN ('skip_early', 'dislike')),
+			count(*) FILTER (WHERE outcome = 'like')`
+
 // WaveMetrics считает метрики по показам с известным исходом.
 func (st *Store) WaveMetrics(ctx context.Context) (WaveMetrics, error) {
 	var (
@@ -635,20 +674,32 @@ func (st *Store) WaveMetrics(ctx context.Context) (WaveMetrics, error) {
 		judged, through, early, liked int
 	)
 	err := st.pool.QueryRow(ctx, `
-		SELECT count(*), count(DISTINCT wave_session_id), count(outcome),
-			count(*) FILTER (WHERE outcome IN ('complete', 'like')),
-			count(*) FILTER (WHERE outcome IN ('skip_early', 'dislike')),
-			count(*) FILTER (WHERE outcome = 'like')
+		SELECT count(*), count(DISTINCT wave_session_id), `+waveOutcomes+`
 		FROM wave_impressions WHERE served_at > now() - interval '7 days'`).
 		Scan(&m.Served, &m.Sessions, &judged, &through, &early, &liked)
 	if err != nil {
 		return WaveMetrics{}, fmt.Errorf("library: wave metrics: %w", err)
 	}
-	if judged > 0 {
-		lt, es, lr := float32(through)/float32(judged), float32(early)/float32(judged), float32(liked)*100/float32(judged)
-		m.ListenThrough, m.EarlySkip, m.LikeRate = &lt, &es, &lr
+	m.WaveRates = rates(judged, through, early, liked)
+
+	rows, err := st.pool.Query(ctx, `
+		SELECT coalesce(model_ver, ''), count(*), `+waveOutcomes+`
+		FROM wave_impressions WHERE served_at > now() - interval '7 days'
+		GROUP BY 1 ORDER BY 2 DESC`)
+	if err != nil {
+		return WaveMetrics{}, fmt.Errorf("library: wave metrics by model: %w", err)
 	}
-	return m, nil
+	defer rows.Close()
+	m.ByModel = []WaveModelMetrics{}
+	for rows.Next() {
+		var mm WaveModelMetrics
+		if err := rows.Scan(&mm.ModelVer, &mm.Served, &judged, &through, &early, &liked); err != nil {
+			return WaveMetrics{}, fmt.Errorf("library: wave metrics by model: %w", err)
+		}
+		mm.WaveRates = rates(judged, through, early, liked)
+		m.ByModel = append(m.ByModel, mm)
+	}
+	return m, rows.Err()
 }
 
 // FingerprintTodo — файл, которому нужны отпечатки.

services/api/internal/search/meili.go

@@ -77,6 +77,7 @@ func (m *Meili) wait(ctx context.Context, t taskRef) error {
 			Status string `json:"status"`
 			Error  *struct {
 				Message string `json:"message"`
+				Code    string `json:"code"`
 			} `json:"error"`
 		}
 		if err := m.do(ctx, http.MethodGet, fmt.Sprintf("/tasks/%d", t.TaskUID), nil, &task); err != nil {
@@ -88,6 +89,10 @@ func (m *Meili) wait(ctx context.Context, t taskRef) error {
 		case "failed", "canceled":
 			msg := task.Status
 			if task.Error != nil {
+				// Удаление отсутствующего индекса принимается (202) и падает уже в задаче.
+				if task.Error.Code == "index_not_found" {
+					return fmt.Errorf("%w: task %d: %s", ErrMeiliNotFound, t.TaskUID, task.Error.Message)
+				}
 				msg = task.Error.Message
 			}
 			return fmt.Errorf("meilisearch: task %d: %s", t.TaskUID, msg)

services/api/internal/search/meili_test.go

@@ -0,0 +1,28 @@
+package search
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// На чистом Meilisearch удаление несуществующего индекса падает в задаче, а не ответом 404.
+func TestCallMapsFailedIndexTaskToNotFound(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.Method == http.MethodDelete {
+			w.WriteHeader(http.StatusAccepted)
+			_, _ = w.Write([]byte(`{"taskUid":0}`))
+			return
+		}
+		_, _ = w.Write([]byte(`{"status":"failed","error":{"code":"index_not_found","message":"Index ` + "`x`" + ` not found."}}`))
+	}))
+	defer srv.Close()
+
+	err := NewMeili(srv.URL, "").call(context.Background(), http.MethodDelete, "/indexes/x", nil)
+	if !errors.Is(err, ErrMeiliNotFound) {
+		t.Fatalf("err = %v, want ErrMeiliNotFound", err)
+	}
+}

services/api/internal/search/personal.go

@@ -0,0 +1,83 @@
+package search
+
+import (
+	"context"
+	"math"
+	"sort"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// suggestPool — во сколько раз больше кандидатов берётся из Meilisearch для переранжирования подсказок.
+const suggestPool = 3
+
+// Affinity — насколько пользователь «знает» исполнителей, альбомы и треки: прослушивания, доигрывания,
+// лайки и дизлайки. Отрицательное — не любит. Нужен для персональных подсказок поиска.
+type Affinity struct{ pool *pgxpool.Pool }
+
+// NewAffinity создаёт источник предпочтений.
+func NewAffinity(pool *pgxpool.Pool) *Affinity { return &Affinity{pool: pool} }
+
+// Of возвращает вес для каждого из ids, о котором что-то известно.
+func (a *Affinity) Of(ctx context.Context, user uuid.UUID, ids []uuid.UUID) (map[uuid.UUID]float64, error) {
+	rows, err := a.pool.Query(ctx, `
+		WITH s AS (
+			SELECT track_id, sum(w) AS w FROM (
+				SELECT track_id, (play_count + 2 * complete_count - early_skip_count)::float8 AS w
+				FROM user_track_stats WHERE user_id = $1
+				UNION ALL
+				SELECT track_id, CASE reaction WHEN 'like' THEN 10 ELSE -10 END FROM track_reactions WHERE user_id = $1
+			) x GROUP BY track_id
+		)
+		SELECT track_id, w FROM s WHERE track_id = ANY($2)
+		UNION ALL
+		SELECT t.album_id, sum(s.w) FROM s JOIN tracks t ON t.id = s.track_id WHERE t.album_id = ANY($2) GROUP BY t.album_id
+		UNION ALL
+		SELECT ta.artist_id, sum(s.w) FROM s JOIN track_artists ta ON ta.track_id = s.track_id
+		WHERE ta.artist_id = ANY($2) GROUP BY ta.artist_id
+		UNION ALL
+		SELECT artist_id, CASE reaction WHEN 'like' THEN 20 ELSE -20 END FROM artist_reactions
+		WHERE user_id = $1 AND artist_id = ANY($2)`, user, ids)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := map[uuid.UUID]float64{}
+	for rows.Next() {
+		var id uuid.UUID
+		var w float64
+		if err := rows.Scan(&id, &w); err != nil {
+			return nil, err
+		}
+		out[id] += w
+	}
+	return out, rows.Err()
+}
+
+// personalize переставляет найденное: знакомое и любимое поднимается на несколько позиций, нелюбимое
+// опускается; релевантность Meilisearch остаётся основой порядка. Возвращает не больше n.
+func personalize(found []string, aff map[uuid.UUID]float64, n int) []string {
+	type item struct {
+		id  string
+		key float64
+	}
+	items := make([]item, len(found))
+	for i, s := range found {
+		key := float64(i)
+		if id, err := uuid.Parse(s); err == nil {
+			if w := aff[id]; w > 0 {
+				key -= 2 * math.Log1p(w)
+			} else if w < 0 {
+				key += 3
+			}
+		}
+		items[i] = item{s, key}
+	}
+	sort.SliceStable(items, func(i, j int) bool { return items[i].key < items[j].key })
+	out := make([]string, 0, min(n, len(items)))
+	for _, it := range items[:min(n, len(items))] {
+		out = append(out, it.id)
+	}
+	return out
+}

services/api/internal/search/service.go

@@ -28,12 +28,15 @@ type Handler struct {
 	meili   *Meili
 	catalog *library.Store
 	indexer *Indexer
+	aff     *Affinity
 	log     *slog.Logger
 }
 
 // NewHandler создаёт обработчик поиска.
-func NewHandler(meili *Meili, catalog *library.Store, indexer *Indexer, dto library.DTO, log *slog.Logger) *Handler {
-	return &Handler{meili: meili, catalog: catalog, indexer: indexer, dto: dto, log: log}
+func NewHandler(
+	meili *Meili, catalog *library.Store, indexer *Indexer, aff *Affinity, dto library.DTO, log *slog.Logger,
+) *Handler {
+	return &Handler{meili: meili, catalog: catalog, indexer: indexer, aff: aff, dto: dto, log: log}
 }
 
 type limits struct{ artists, albums, tracks, offset int }
@@ -150,10 +153,16 @@ func (h *Handler) hydrate(ctx context.Context, f found, corrected string) (gen.S
 
 // SearchSuggest реализует gen.StrictServerInterface.
 func (h *Handler) SearchSuggest(ctx context.Context, req gen.SearchSuggestRequestObject) (gen.SearchSuggestResponseObject, error) {
-	f, corrected, err := h.run(ctx, req.Params.Q, limits{artists: 3, albums: 3, tracks: 5})
+	want := limits{artists: 3, albums: 3, tracks: 5}
+	l := want
+	if h.aff != nil {
+		l = limits{artists: want.artists * suggestPool, albums: want.albums * suggestPool, tracks: want.tracks * suggestPool}
+	}
+	f, corrected, err := h.run(ctx, req.Params.Q, l)
 	if err != nil {
 		return nil, err
 	}
+	f = h.personal(ctx, f, want)
 	out, err := h.hydrate(ctx, f, corrected)
 	if err != nil {
 		return nil, err
@@ -161,6 +170,23 @@ func (h *Handler) SearchSuggest(ctx context.Context, req gen.SearchSuggestReques
 	return gen.SearchSuggest200JSONResponse(out), nil
 }
 
+// personal оставляет в подсказках по want.* лучших с учётом вкуса пользователя.
+// Без пользователя или при сбое — просто первые по релевантности.
+func (h *Handler) personal(ctx context.Context, f found, want limits) found {
+	var aff map[uuid.UUID]float64
+	if p, ok := auth.PrincipalFrom(ctx); ok && h.aff != nil {
+		all := ids(append(append(append([]string{}, f.artists...), f.albums...), f.tracks...))
+		var err error
+		if aff, err = h.aff.Of(ctx, p.UserID, all); err != nil {
+			h.log.WarnContext(ctx, "suggest personalization failed", "err", err)
+		}
+	}
+	f.artists = personalize(f.artists, aff, want.artists)
+	f.albums = personalize(f.albums, aff, want.albums)
+	f.tracks = personalize(f.tracks, aff, want.tracks)
+	return f
+}
+
 // Search реализует gen.StrictServerInterface.
 func (h *Handler) Search(ctx context.Context, req gen.SearchRequestObject) (gen.SearchResponseObject, error) {
 	typ := gen.All

services/api/internal/search/translit_test.go

@@ -3,6 +3,8 @@ package search
 import (
 	"testing"
 
+	"github.com/google/uuid"
+
 	"github.com/stretchr/testify/assert"
 )
 
@@ -20,3 +22,14 @@ func TestSwitchLayout(t *testing.T) {
 	assert.Equal(t, "кино", SwitchLayout("rbyj"))
 	assert.Equal(t, "", SwitchLayout("123"))
 }
+
+func TestPersonalizeLiftsFamiliarAndSinksDisliked(t *testing.T) {
+	liked, disliked := uuid.New(), uuid.New()
+	other := []string{uuid.NewString(), uuid.NewString(), uuid.NewString()}
+	found := []string{other[0], disliked.String(), other[1], other[2], liked.String()}
+	aff := map[uuid.UUID]float64{liked: 30, disliked: -10}
+
+	got := personalize(found, aff, 3)
+	assert.Equal(t, []string{liked.String(), other[0], other[1]}, got)
+	assert.Equal(t, found[:2], personalize(found, nil, 2), "без вкуса — порядок релевантности")
+}

services/api/internal/storageagent/access_other.go

@@ -0,0 +1,20 @@
+//go:build !unix
+
+package storageagent
+
+import (
+	"errors"
+	"os"
+)
+
+// canWrite — запасная проверка для не-Unix (только разработка): бит записи у каталога.
+func canWrite(dir string) error {
+	info, err := os.Stat(dir)
+	if err != nil {
+		return err
+	}
+	if info.Mode().Perm()&0o200 == 0 {
+		return errors.New("directory is not writable")
+	}
+	return nil
+}

services/api/internal/storageagent/access_unix.go

@@ -0,0 +1,18 @@
+//go:build unix
+
+package storageagent
+
+import (
+	"errors"
+
+	"golang.org/x/sys/unix"
+)
+
+// canWrite — можно ли создавать файлы в каталоге (без пробной записи); read-only монтирование — ошибка.
+func canWrite(dir string) error {
+	var st unix.Statfs_t
+	if err := unix.Statfs(dir, &st); err == nil && st.Flags&unix.ST_RDONLY != 0 {
+		return errors.New("filesystem is mounted read-only")
+	}
+	return unix.Access(dir, unix.W_OK|unix.X_OK)
+}

services/api/internal/storageagent/files.go

@@ -142,27 +142,19 @@ func (a *agent) writeFile(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, res)
 }
 
-// write копирует staging во временный файл рядом с целью, fsync, сверяет SHA-256 и создаёт итоговое имя
-// жёсткой ссылкой (не перезаписывает существующий файл, в отличие от rename), затем убирает временный.
+// write копирует staging сразу под итоговым именем (O_EXCL — существующий файл не перезаписывается, при
+// конфликте — « (2)»), fsync, сверяет SHA-256 копии. На музыкальный диск не попадает ничего, кроме самого трека:
+// ни временных файлов, ни служебных пометок. При любой ошибке недописанный файл и созданные для него пустые
+// каталоги удаляются — агент убирает только то, что создал сам.
 func (a *agent) write(root, rel, staging string, want []byte) (WriteResult, error) {
-	target := filepath.Join(root, filepath.FromSlash(rel))
-	dir := filepath.Dir(target)
-	if err := a.mkdirs(root, dir); err != nil {
-		return WriteResult{}, err
-	}
-	tmp := filepath.Join(dir, "."+filepath.Base(target)+".pipu-tmp")
-	size, err := a.copyTemp(staging, tmp)
-	if err != nil {
-		_ = os.Remove(tmp)
-		return WriteResult{}, err
-	}
-	defer func() { _ = os.Remove(tmp) }()
-	got, err := fileSHA256(tmp)
+	dir := filepath.Dir(filepath.Join(root, filepath.FromSlash(rel)))
+	created, err := a.mkdirs(root, dir)
 	if err != nil {
 		return WriteResult{}, err
 	}
-	if !bytes.Equal(got, want) {
-		return WriteResult{}, fmt.Errorf("checksum mismatch: copy %x, expected %x", got, want)
+	fail := func(err error) (WriteResult, error) {
+		removeEmpty(created)
+		return WriteResult{}, err
 	}
 
 	ext := path.Ext(rel)
@@ -172,24 +164,39 @@ func (a *agent) write(root, rel, staging string, want []byte) (WriteResult, erro
 		if n > 1 {
 			name = fmt.Sprintf("%s (%d)%s", base, n, ext)
 		}
-		err := os.Link(tmp, filepath.Join(root, filepath.FromSlash(name)))
+		target := filepath.Join(root, filepath.FromSlash(name))
+		dst, err := os.OpenFile(target, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
+		if os.IsExist(err) {
+			continue
+		}
+		if err != nil {
+			return fail(fmt.Errorf("create: %w", err))
+		}
+		size, err := copyInto(dst, staging)
 		if err == nil {
-			syncDir(dir)
-			return WriteResult{RelPath: name, Size: size, Renamed: n > 1}, nil
+			var got []byte
+			if got, err = fileSHA256(target); err == nil && !bytes.Equal(got, want) {
+				err = fmt.Errorf("checksum mismatch: copy %x, expected %x", got, want)
+			}
 		}
-		if !os.IsExist(err) {
-			return WriteResult{}, fmt.Errorf("link: %w", err)
+		if err != nil {
+			_ = os.Remove(target) // наш собственный недописанный / испорченный файл
+			return fail(err)
 		}
+		a.chown(target)
+		syncDir(dir)
+		return WriteResult{RelPath: name, Size: size, Renamed: n > 1}, nil
 	}
-	return WriteResult{}, errors.New("too many files with the same name")
+	return fail(errors.New("too many files with the same name"))
 }
 
-// mkdirs создаёт недостающие каталоги от root до dir (0755, владелец — FileUID/FileGID).
-func (a *agent) mkdirs(root, dir string) error {
+// mkdirs создаёт недостающие каталоги от root до dir (0755, владелец — FileUID/FileGID) и возвращает созданные.
+func (a *agent) mkdirs(root, dir string) ([]string, error) {
 	rel, err := filepath.Rel(root, dir)
 	if err != nil || strings.HasPrefix(rel, "..") {
-		return errBadPath
+		return nil, errBadPath
 	}
+	var created []string
 	cur := root
 	for _, seg := range strings.Split(rel, string(filepath.Separator)) {
 		if seg == "." || seg == "" {
@@ -200,24 +207,30 @@ func (a *agent) mkdirs(root, dir string) error {
 			if os.IsExist(err) {
 				continue
 			}
-			return fmt.Errorf("mkdir: %w", err)
+			removeEmpty(created)
+			return nil, fmt.Errorf("mkdir: %w", err)
 		}
+		created = append(created, cur)
 		a.chown(cur)
 	}
-	return nil
+	return created, nil
 }
 
-func (a *agent) copyTemp(staging, tmp string) (int64, error) {
+// removeEmpty удаляет созданные каталоги от глубоких к верхним; os.Remove не трогает непустые.
+func removeEmpty(dirs []string) {
+	for i := len(dirs) - 1; i >= 0; i-- {
+		_ = os.Remove(dirs[i])
+	}
+}
+
+// copyInto копирует staging в открытый файл и делает fsync; файл закрывается.
+func copyInto(dst *os.File, staging string) (int64, error) {
 	src, err := os.Open(staging)
 	if err != nil {
+		_ = dst.Close()
 		return 0, fmt.Errorf("staging: %w", err)
 	}
 	defer func() { _ = src.Close() }()
-	_ = os.Remove(tmp) // остаток прерванной попытки
-	dst, err := os.OpenFile(tmp, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
-	if err != nil {
-		return 0, fmt.Errorf("create temp: %w", err)
-	}
 	n, err := io.Copy(dst, src)
 	if err == nil {
 		err = dst.Sync()
@@ -228,7 +241,6 @@ func (a *agent) copyTemp(staging, tmp string) (int64, error) {
 	if err != nil {
 		return 0, fmt.Errorf("copy: %w", err)
 	}
-	a.chown(tmp)
 	return n, nil
 }
 
@@ -240,7 +252,8 @@ func (a *agent) chown(p string) {
 	}
 }
 
-// testWrite создаёт и удаляет .pipu-write-test в корне источника на запись.
+// testWrite проверяет право записи в корень источника, ничего не создавая на диске (access(W_OK);
+// на NFS ответ даёт сам сервер с учётом root_squash и прав экспорта).
 func (a *agent) testWrite(w http.ResponseWriter, r *http.Request) {
 	var req WriteTestRequest
 	if !a.decode(w, r, &req) {
@@ -251,16 +264,7 @@ func (a *agent) testWrite(w http.ResponseWriter, r *http.Request) {
 		writeJSON(w, http.StatusOK, WriteTestResult{Message: err.Error()})
 		return
 	}
-	p := filepath.Join(root, ".pipu-write-test")
-	f, err := os.OpenFile(p, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o644)
-	if err == nil {
-		_, err = f.WriteString("pipu")
-		if cerr := f.Close(); err == nil {
-			err = cerr
-		}
-	}
-	_ = os.Remove(p)
-	if err != nil {
+	if err := canWrite(root); err != nil {
 		writeJSON(w, http.StatusOK, WriteTestResult{Message: "cannot write: " + err.Error()})
 		return
 	}

services/api/internal/storageagent/files_test.go

@@ -9,6 +9,7 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -74,6 +75,7 @@ func TestWriteFile(t *testing.T) {
 	assert.True(t, res.Renamed)
 	entries, _ := os.ReadDir(dir)
 	assert.Len(t, entries, 2)
+	assertOnlyMusic(t, filepath.Join(e.paths.LibraryRW, srcID))
 
 	// Local-источник пишется в LIBRARY_HOST.
 	local := "music"
@@ -103,8 +105,21 @@ func TestWriteFileRejects(t *testing.T) {
 	other := sha256.Sum256([]byte("other"))
 	rec := e.post("/internal/files", WriteRequest{SourceID: srcID, RelPath: "A/x.flac", StagingPath: "u1/f1", SHA256: hex.EncodeToString(other[:])})
 	assert.Equal(t, http.StatusInternalServerError, rec.Code)
-	entries, _ := os.ReadDir(filepath.Join(e.paths.LibraryRW, srcID, "A"))
-	assert.Empty(t, entries)
+	// Созданная под файл папка тоже убрана: на диске не остаётся следов неудачной записи.
+	assert.NoDirExists(t, filepath.Join(e.paths.LibraryRW, srcID, "A"))
+	assertOnlyMusic(t, filepath.Join(e.paths.LibraryRW, srcID))
+}
+
+// assertOnlyMusic — в дереве хранилища только аудиофайлы и каталоги: ни временных, ни служебных файлов.
+func assertOnlyMusic(t *testing.T, root string) {
+	t.Helper()
+	require.NoError(t, filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return err
+		}
+		assert.True(t, audioExt[strings.ToLower(filepath.Ext(p))] && !strings.HasPrefix(d.Name(), "."), "unexpected file %s", p)
+		return nil
+	}))
 }
 
 func TestWritableMount(t *testing.T) {
@@ -120,7 +135,8 @@ func TestWritableMount(t *testing.T) {
 	var res WriteTestResult
 	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &res))
 	assert.True(t, res.OK, res.Message)
-	assert.NoFileExists(t, filepath.Join(rw, ".pipu-write-test"))
+	entries, _ := os.ReadDir(rw)
+	assert.Empty(t, entries, "write check creates nothing")
 
 	// Без accepts_uploads rw-точка снимается.
 	e.post("/internal/mounts", MountRequest{SourceID: srcID, NFSSpec: NFSSpec{Server: "nas", Export: "/music"}})

services/api/internal/wave/onboarding.go

@@ -0,0 +1,141 @@
+package wave
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/google/uuid"
+
+	"pipu/api/internal/api/gen"
+)
+
+// Онбординг вкуса (docs/recommendations.md#7): новый пользователь отмечает исполнителей и жанры — рекомендатель
+// берёт их как начальный вкус, пока своей истории мало. Пропуск сохраняется пустым выбором.
+
+const (
+	onboardingArtists = 40
+	onboardingGenres  = 24
+	// История, после которой онбординг уже не предлагается: вкус и так виден по прослушиваниям.
+	onboardingMinHistory = 10
+)
+
+// GetOnboarding реализует gen.StrictServerInterface.
+func (h *Handler) GetOnboarding(ctx context.Context, _ gen.GetOnboardingRequestObject) (gen.GetOnboardingResponseObject, error) {
+	p, err := principal(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out := gen.GetOnboarding200JSONResponse{}
+	var done bool
+	var plays int
+	if err := h.pool.QueryRow(ctx, `
+		SELECT EXISTS (SELECT 1 FROM user_profiles_rec WHERE user_id = $1 AND onboarding IS NOT NULL),
+			(SELECT count(*) FROM user_track_stats WHERE user_id = $1)`, p.UserID).Scan(&done, &plays); err != nil {
+		return nil, fmt.Errorf("wave: onboarding state: %w", err)
+	}
+
+	rows, err := h.pool.Query(ctx, `
+		SELECT a.id, a.name, count(*) AS n,
+			(SELECT al.id FROM albums al WHERE al.album_artist_id = a.id
+				ORDER BY (SELECT count(*) FROM tracks t WHERE t.album_id = al.id) DESC, al.id LIMIT 1)
+		FROM artists a JOIN track_artists ta ON ta.artist_id = a.id AND ta.role = 'main'
+		GROUP BY a.id ORDER BY n DESC, a.name LIMIT $1`, onboardingArtists)
+	if err != nil {
+		return nil, fmt.Errorf("wave: onboarding artists: %w", err)
+	}
+	type artist struct {
+		id, album *uuid.UUID
+		name      string
+		n         int
+	}
+	var artists []artist
+	for rows.Next() {
+		var a artist
+		var id uuid.UUID
+		if err := rows.Scan(&id, &a.name, &a.n, &a.album); err != nil {
+			rows.Close()
+			return nil, fmt.Errorf("wave: onboarding artists: %w", err)
+		}
+		a.id = &id
+		artists = append(artists, a)
+	}
+	rows.Close()
+	dto := h.dto()
+	for _, a := range artists {
+		item := struct {
+			CoverColors []string  `json:"cover_colors"`
+			CoverUrl    *string   `json:"cover_url"`
+			Id          uuid.UUID `json:"id"`
+			Name        string    `json:"name"`
+			TrackCount  int       `json:"track_count"`
+		}{Id: *a.id, Name: a.name, TrackCount: a.n, CoverColors: []string{}}
+		if a.album != nil {
+			if al, err := h.catalog.Album(ctx, *a.album); err == nil {
+				sum := dto.AlbumSummary(al)
+				item.CoverUrl, item.CoverColors = sum.CoverUrl, sum.CoverColors
+			}
+		}
+		out.Artists = append(out.Artists, item)
+	}
+
+	grows, err := h.pool.Query(ctx, `
+		SELECT g.name, count(DISTINCT tg.track_id) AS n FROM track_genres tg JOIN genres g ON g.id = tg.genre_id
+		GROUP BY g.name ORDER BY n DESC, g.name LIMIT $1`, onboardingGenres)
+	if err != nil {
+		return nil, fmt.Errorf("wave: onboarding genres: %w", err)
+	}
+	for grows.Next() {
+		var g struct {
+			Name       string `json:"name"`
+			TrackCount int    `json:"track_count"`
+		}
+		if err := grows.Scan(&g.Name, &g.TrackCount); err != nil {
+			grows.Close()
+			return nil, fmt.Errorf("wave: onboarding genres: %w", err)
+		}
+		out.Genres = append(out.Genres, g)
+	}
+	grows.Close()
+	if out.Artists == nil {
+		out.Artists = []struct {
+			CoverColors []string  `json:"cover_colors"`
+			CoverUrl    *string   `json:"cover_url"`
+			Id          uuid.UUID `json:"id"`
+			Name        string    `json:"name"`
+			TrackCount  int       `json:"track_count"`
+		}{}
+	}
+	if out.Genres == nil {
+		out.Genres = []struct {
+			Name       string `json:"name"`
+			TrackCount int    `json:"track_count"`
+		}{}
+	}
+	out.Required = !done && plays < onboardingMinHistory && len(out.Artists) > 0
+	return out, nil
+}
+
+// SaveOnboarding реализует gen.StrictServerInterface.
+func (h *Handler) SaveOnboarding(ctx context.Context, req gen.SaveOnboardingRequestObject) (gen.SaveOnboardingResponseObject, error) {
+	p, err := principal(ctx)
+	if err != nil {
+		return nil, err
+	}
+	ids := req.Body.ArtistIds
+	if ids == nil {
+		ids = []uuid.UUID{}
+	}
+	genres := req.Body.Genres
+	if genres == nil {
+		genres = []string{}
+	}
+	raw, _ := json.Marshal(map[string]any{"artist_ids": ids, "genres": genres})
+	if _, err := h.pool.Exec(ctx, `
+		INSERT INTO user_profiles_rec (user_id, onboarding, updated_at) VALUES ($1, $2, now())
+		ON CONFLICT (user_id) DO UPDATE SET onboarding = EXCLUDED.onboarding, updated_at = now()`,
+		p.UserID, raw); err != nil {
+		return nil, fmt.Errorf("wave: save onboarding: %w", err)
+	}
+	return gen.SaveOnboarding204Response{}, nil
+}

services/api/migrations/00009_onboarding.sql

@@ -0,0 +1,7 @@
+-- +goose Up
+-- Онбординг «Моей волны» (docs/recommendations.md#7): выбранные исполнители и жанры — начальный вкус,
+-- пока своей истории мало. NULL — онбординг ещё не пройден и не пропущен.
+ALTER TABLE user_profiles_rec ADD COLUMN onboarding jsonb;
+
+-- +goose Down
+ALTER TABLE user_profiles_rec DROP COLUMN onboarding;

services/api/migrations/00010_ranker.sql

@@ -0,0 +1,17 @@
+-- +goose Up
+-- Ранжировщик волны v2 (docs/recommendations.md#6.3): признаки кандидата в момент показа — для обучения
+-- LightGBM на исходах показов (wave_impressions.outcome); артефакт модели хранится в model_versions.
+CREATE TABLE rec_impression_features (
+  wave_session_id uuid NOT NULL REFERENCES wave_sessions(id) ON DELETE CASCADE,
+  track_id        uuid NOT NULL,
+  features        real[] NOT NULL,
+  served_at       timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (wave_session_id, track_id)
+);
+CREATE INDEX rec_impression_features_served_idx ON rec_impression_features (served_at);
+
+ALTER TABLE model_versions ADD COLUMN artifact text;
+
+-- +goose Down
+ALTER TABLE model_versions DROP COLUMN artifact;
+DROP TABLE rec_impression_features;

services/recommender/Dockerfile

@@ -15,8 +15,8 @@ COPY services/recommender/ ./
 RUN --mount=type=cache,target=/root/.cache/uv uv sync --frozen --no-dev
 
 FROM python:3.12-slim
-# ffmpeg декодирует аудио для анализатора.
-RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*     && useradd --system --uid 10001 pipu
+# ffmpeg декодирует аудио для анализатора; libgomp1 нужен LightGBM (ранжировщик волны).
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg libgomp1 && rm -rf /var/lib/apt/lists/*     && useradd --system --uid 10001 pipu
 COPY --from=build /app /app
 ARG VERSION=0.0.0-dev
 ENV PATH=/app/.venv/bin:$PATH PIPU_VERSION=${VERSION} PYTHONUNBUFFERED=1

services/recommender/pipu_rec/analysis/worker.py

@@ -20,6 +20,7 @@ log = logging.getLogger(__name__)
 MAX_ATTEMPTS = 3
 MAX_DURATION_S = 15 * 60
 IDLE_SLEEP_S = 10.0
+MISSING_SLEEP_S = 60.0  # файлы пропали целиком — ждём, пока смонтируют диск
 
 
 @dataclass(frozen=True)
@@ -168,6 +169,18 @@ class Worker:
         )
         conn.commit()
 
+    def postpone(self, conn: psycopg.Connection[Any], track_ids: list[str]) -> None:
+        """Файла нет на диске (не смонтирован?) — обратно в очередь, попытка не засчитывается."""
+        conn.execute(
+            """
+            UPDATE analysis_jobs SET status = 'queued', attempts = greatest(attempts - 1, 0),
+                error = 'file not found — is the disk mounted?', updated_at = now()
+            WHERE track_id = ANY(%s::uuid[])
+            """,
+            (track_ids,),
+        )
+        conn.commit()
+
     def requeue_stale(self, conn: psycopg.Connection[Any]) -> None:
         """Задачи, брошенные упавшим воркером, и признаки старой версии анализатора — снова в очередь."""
         conn.execute(
@@ -189,6 +202,16 @@ class Worker:
             self.requeue_stale(conn)
             while True:
                 jobs = self.claim(conn, self.workers * 2)
+                missing = [j for j in jobs if not Path(j.path).exists()]
+                if missing:
+                    self.postpone(conn, [j.track_id for j in missing])
+                    jobs = [j for j in jobs if j not in missing]
+                    if not jobs:
+                        log.warning(
+                            "analysis: %d files not found, waiting — is the disk mounted?", len(missing)
+                        )
+                        time.sleep(MISSING_SLEEP_S)
+                        continue
                 if not jobs:
                     time.sleep(IDLE_SLEEP_S)
                     continue

services/recommender/pipu_rec/cli.py

@@ -30,7 +30,7 @@ def _serve(settings: Settings) -> None:
     wave = WaveService(settings.database_url, settings.redis_url, load_contexts(settings.contexts_path))
     if settings.train_hour >= 0:
         # После активации новой модели каталог перечитывается сразу — горячая подмена векторов.
-        NightlyTrainer(settings.database_url, settings.train_hour, on_done=wave.index.refresh).start()
+        NightlyTrainer(settings.database_url, settings.train_hour, on_done=wave.reload).start()
     app = create_app(settings, {"postgres": check_postgres, "redis": check_redis}, wave)
     uvicorn.run(app, host=settings.http_host, port=settings.http_port, log_level=settings.log_level)
 

services/recommender/pipu_rec/train/bandit.py

@@ -0,0 +1,68 @@
+"""Бандит по источникам кандидатов (docs/recommendations.md#6.6): Beta(α, β) на пару (пользователь, источник).
+
+Награда — трек из источника доигран или лайкнут; скип и дизлайк — неудача. Наблюдения затухают ×0.99 в день,
+чтобы бандит подстраивался под смену вкуса. Доля «нового» (exploration) следует за успехом источника `fresh`.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from typing import Any
+
+import psycopg
+
+DAILY_DECAY = 0.99
+REWARD = {"complete": 1.0, "like": 1.0, "skip": 0.0, "skip_early": 0.0, "dislike": 0.0}
+EXPLORATION_MIN, EXPLORATION_MAX = 0.05, 0.4
+
+Params = dict[str, list[float]]  # источник → [α, β]
+
+
+def compute(rows: list[tuple[str, str, str, float]], now: float) -> dict[str, Params]:
+    """rows: (user, source, outcome, served_at) → user → source → [α, β] с приором Beta(1, 1)."""
+    out: dict[str, Params] = defaultdict(dict)
+    for user, source, outcome, ts in rows:
+        r = REWARD.get(outcome)
+        if r is None:
+            continue
+        w = DAILY_DECAY ** max((now - ts) / 86400.0, 0.0)
+        ab = out[user].setdefault(source, [1.0, 1.0])
+        ab[0] += w * r
+        ab[1] += w * (1.0 - r)
+    return {u: {s: [round(a, 4), round(b, 4)] for s, (a, b) in p.items()} for u, p in out.items()}
+
+
+def exploration(params: Params, default: float = 0.15) -> float:
+    """Доля «нового»: успешнее `fresh` относительно остальных источников — больше исследования."""
+    fresh = params.get("fresh")
+    others = [a / (a + b) for s, (a, b) in params.items() if s != "fresh"]
+    if fresh is None or not others:
+        return default
+    rate = fresh[0] / (fresh[0] + fresh[1])
+    base = sum(others) / len(others)
+    value = default * (rate / base if base > 0 else 1.0)
+    return round(min(max(value, EXPLORATION_MIN), EXPLORATION_MAX), 3)
+
+
+def update_bandits(conn: psycopg.Connection[Any], now: float) -> int:
+    """Пересчитывает параметры по показам волны за 90 дней. Возвращает число пользователей."""
+    rows = conn.execute(
+        """
+        SELECT ws.user_id::text, wi.candidate_source, wi.outcome, extract(epoch FROM wi.served_at)::float8
+        FROM wave_impressions wi JOIN wave_sessions ws ON ws.id = wi.wave_session_id
+        WHERE wi.outcome IS NOT NULL AND wi.served_at > now() - interval '90 days'
+        """
+    ).fetchall()
+    params = compute([(u, s, o, float(ts)) for u, s, o, ts in rows], now)
+    with conn.transaction(), conn.cursor() as cur:
+        cur.executemany(
+            """
+            INSERT INTO user_profiles_rec (user_id, bandit, exploration, updated_at)
+            VALUES (%s, %s, %s, now())
+            ON CONFLICT (user_id) DO UPDATE SET bandit = EXCLUDED.bandit, exploration = EXCLUDED.exploration,
+                updated_at = now()
+            """,
+            [(u, json.dumps(p), exploration(p)) for u, p in params.items()],
+        )
+    return len(params)