docs(api-key): correct stale "show-once" comments for the reveal/copy flow (#557)

The reveal/copy flow makes several pre-existing docstrings false (they claimed the
token is shown/returned only ONCE and is "never retrievable"). Comment-only fixes,
no logic change:

- api-key.service.ts create(): the token is not "returned ONCE"; no token material
  is ever stored (self-contained JWT) and it is re-obtainable by the owner via a
  deterministic re-mint under a step-up (POST /api-keys/reveal).
- api-key.controller.ts: drop "never retrievable again"; the JWT is returned in a
  body on create OR via /api-keys/reveal, never logged, never stored.
- client api-key-service.ts / api-key-query.ts / types.ts: drop "show-once modal"
  and "shown exactly once"; the create flow discards the token and it is copied
  later via the per-row reveal action.

Tests unchanged: 62 server / 28 client green; tsc clean on touched files.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.env.example

@@ -198,6 +198,42 @@ MCP_DOCMOST_PASSWORD=
 # A slow/hung embeddings endpoint fails after this and the batch continues.
 # AI_EMBEDDING_TIMEOUT_MS=120000
 
+# ─── #530 Semantic search (Phase B) ──────────────────────────────────────────
+# The GLOBAL embedding provider used by search (query embed) AND the indexer
+# (document embed) when a workspace has NO embedding provider of its own. It is
+# an OpenAI-compatible endpoint — the docker-compose `embeddings` (TEI) sidecar.
+# A workspace that configures its own embedding provider OVERRIDES all of this.
+# When neither resolves, search runs lexical-only (semantic.reason=no-provider).
+EMBEDDING_ENDPOINT=http://embeddings:80/v1
+EMBEDDING_MODEL=intfloat/multilingual-e5-small
+# Dummy — the self-hosted TEI sidecar is keyless.
+EMBEDDING_API_KEY=unused
+EMBEDDING_DIMENSIONS=384
+# PLACEHOLDER — set to a PINNED intfloat/multilingual-e5-small commit sha (used
+# both as the TEI --revision and as part of the embedding fingerprint). Keep this
+# in lockstep with docker-compose; a bump changes the fingerprint (PR-2 handles
+# the generational swap/GC — PR-1 uses a single active fingerprint).
+EMBEDDING_REVISION=REPLACE_WITH_PINNED_E5_SMALL_COMMIT_SHA
+# e5 models require these input prefixes. Empty them for a non-e5 model.
+EMBEDDING_QUERY_PREFIX="query: "
+EMBEDDING_DOC_PREFIX="passage: "
+# Per-request timeout (ms) for the interactive SEARCH query embed — much shorter
+# than the batch indexer timeout: a slow/hung sidecar degrades search fast to the
+# lexical-only path instead of blocking the request. Default 800.
+# SEARCH_EMBED_TIMEOUT_MS=800
+# RRF weight of the vector leg relative to each lexical leg (1.0 = equal). Default 1.0.
+# SEARCH_VECTOR_WEIGHT=1.0
+# Vector top-N pulled into the fused candidate union per request. Default 50.
+# SEARCH_VECTOR_CANDIDATES=50
+# Per-statement timeout (ms) bounding ONLY the fused vector query (the brute-force
+# KNN seq scan — there is no ANN index). If the vector scan exceeds this it is
+# cancelled and search degrades to lexical-only (never hangs the request). Scoped
+# per-query (SET LOCAL), so it never affects other queries. Default 2000.
+# SEARCH_VECTOR_STATEMENT_TIMEOUT_MS=2000
+# Kill-switch: set to `off` to disable the semantic layer entirely (search then
+# runs the byte-identical Phase-A lexical path). Default on.
+# SEARCH_SEMANTIC=on
+
 # Silence timeout (ms) for streaming chat/agent AI calls AND external-MCP traffic.
 # Bounds time-to-first-byte and the gap BETWEEN chunks (NOT the total turn length),
 # so an arbitrarily long turn that keeps streaming is never cut. Finite so a hung
@@ -251,16 +287,6 @@ MCP_DOCMOST_PASSWORD=
 # Default 120000 (2 min).
 # AI_MCP_CALL_TIMEOUT_MS=120000
 
-# Kill-switch for the agent API-key feature (#501). Default ON when unset — a
-# deploy that never sets it must NOT silently kill every agent. STRICT parse:
-# only the literals `true` / `false` are accepted; a typo like `=0`/`=off`/`=False`
-# FAILS AT BOOT by design (never silently read as "enabled"), so the switch is
-# guaranteed to actually flip when an operator flips it during an incident. When
-# set to `false`: all api-key auth is DENIED (every api-key token is rejected) and
-# the api-key management endpoints return 404. The resolved state is logged at boot
-# (`API keys: ENABLED/DISABLED (API_KEYS_ENABLED=...)`) so it is verifiable per deploy.
-# API_KEYS_ENABLED=true
-
 # Max JSON/urlencoded request body size (bytes). Fastify's 1 MiB default is too
 # small for a long AI-chat research turn: the client resends the FULL message
 # history (every tool call + search result) on each turn, so a deep conversation's

NewDesign/CommentsPanel.tsx

@@ -1,460 +0,0 @@
-/**
- * CommentsPanel — редизайн панели комментариев с фокусом на агентские правки.
- * Mantine v7. Узкая колонка ~340–400px, светлая/тёмная темы.
- *
- * Реализованные решения (см. README.md):
- *  - Дифф-первая карточка: цитата = старая строка диффа (без тройного дублирования)
- *  - Группировка серии прогона под одной шапкой ("Корректор · 28 правок")
- *  - Пакетное "Accept all" на фронте (по одной под капотом) с полоской прогресса
- *  - Метки важности/категории парсятся клиентом из тегов "[Корректура][Существенно]"
- *  - Фильтры по важности/категории
- *  - Безопасный Dismiss через undo-тост (удаление откладывается на клиенте)
- *  - Состояния: pending / applied / dismissed / conflict (потерян якорь)
- *  - Крайние диффы: вставка (␣), удаление, одна буква, дефис→тире, длинный абзац
- *  - Человеческий тред не деградирует (та же система, другое наполнение)
- *  - Вкладки Open/Resolved сохранены
- */
-import { useMemo, useState, useCallback, useRef } from 'react';
-import {
-  Box, Group, Stack, Text, Badge, Button, ActionIcon, Tabs, Progress,
-  Avatar, Tooltip, ScrollArea, useMantineColorScheme, useMantineTheme,
-} from '@mantine/core';
-import { notifications } from '@mantine/notifications';
-
-/* ─────────────────────────── Типы данных ─────────────────────────── */
-
-export type Severity = 'critical' | 'major' | 'minor';
-export type Category = string; // "Корректура" | "Факт" | "Стиль" | …
-
-/** Один сегмент интра-диффа: изменённый фрагмент подсвечивается. */
-export interface DiffSegment {
-  text: string;
-  changed: boolean;
-}
-
-/** Правка: сервер уже отдаёт посегментную разметку обеих строк. */
-export interface SuggestedEdit {
-  before: DiffSegment[]; // "было" (пустой массив ⇒ чистая вставка)
-  after: DiffSegment[];  // "стало" (пустой массив ⇒ чистое удаление)
-}
-
-export type CommentStatus = 'pending' | 'applied' | 'dismissed' | 'conflict';
-
-export interface Comment {
-  id: string;
-  runId?: string;          // id прогона агента — для группировки серии
-  authorName: string;      // "Корректор" | "Нарратор" | имя человека
-  authorKind: 'agent' | 'human';
-  triggeredBy?: string;    // кто запустил агента ("vvzvlad")
-  createdAtLabel: string;  // "15 ч", "2 дн" — форматируется вызывающим кодом
-  /** Сырой текст комментария от агента, метки в квадратных скобках. */
-  bodyRaw: string;
-  edit?: SuggestedEdit;    // есть ⇒ агентская правка; нет ⇒ обычный тред
-  status: CommentStatus;
-  replyCount?: number;
-  anchorLost?: boolean;    // сервер ответил конфликтом якоря
-}
-
-export interface CommentsPanelProps {
-  comments: Comment[];
-  /** Применить одну правку. Резолвит тред на сервере. */
-  onApply: (id: string) => Promise<void>;
-  /** Жёсткое удаление на сервере (для треда без ответов). Вызывается ПОСЛЕ окна undo. */
-  onDismiss: (id: string) => Promise<void>;
-  /** Резолв обычного треда. */
-  onResolve?: (id: string) => Promise<void>;
-  /** Клик по карточке/цитате — скролл документа к якорю и подсветка. */
-  onNavigateToAnchor: (id: string) => void;
-  onClose?: () => void;
-  /** Мс до фактического удаления после Dismiss (окно undo). По умолчанию 5000. */
-  dismissUndoMs?: number;
-}
-
-/* ───────────────────── Клиентский парсинг меток ───────────────────── */
-
-const SEVERITY_WORDS: Record<string, Severity> = {
-  'существенно': 'major', 'критично': 'critical', 'критическая': 'critical',
-  'незначительно': 'minor', 'мелко': 'minor', 'major': 'major',
-  'minor': 'minor', 'critical': 'critical',
-};
-
-interface ParsedBody {
-  category?: Category;
-  severity: Severity;
-  text: string; // тело без скобочных тегов
-}
-
-/** "[Корректура] [Существенно] Пробел…" → {category, severity, text}. */
-export function parseBody(raw: string): ParsedBody {
-  const tags: string[] = [];
-  const text = raw.replace(/\[([^\]]+)\]/g, (_, t) => { tags.push(t.trim()); return ''; }).trim();
-  let severity: Severity = 'minor';
-  let category: Category | undefined;
-  for (const t of tags) {
-    const sv = SEVERITY_WORDS[t.toLowerCase()];
-    if (sv) severity = sv; else if (!category) category = t;
-  }
-  return { category, severity, text };
-}
-
-const SEV_COLOR: Record<Severity, string> = {
-  critical: 'red', major: 'orange', minor: 'gray',
-};
-
-/* ──────────────────────────── Дифф ──────────────────────────── */
-
-/** Делает невидимые символы видимыми в подсветке (пробел, таб). */
-function visibleWhitespace(s: string): string {
-  return s.replace(/ /g, '␣').replace(/\t/g, '⇥');
-}
-
-function DiffLine({ segments, kind }: { segments: DiffSegment[]; kind: 'del' | 'ins' }) {
-  const theme = useMantineTheme();
-  const { colorScheme } = useMantineColorScheme();
-  const dark = colorScheme === 'dark';
-  const isDel = kind === 'del';
-  const sign = isDel ? '−' : '+';
-  const signColor = isDel ? theme.colors.red[dark ? 5 : 6] : theme.colors.green[dark ? 5 : 6];
-  const baseColor = isDel
-    ? (dark ? theme.colors.gray[5] : theme.colors.gray[6])
-    : (dark ? theme.colors.gray[1] : theme.colors.dark[9]);
-  const markBg = isDel
-    ? (dark ? 'rgba(224,49,49,.22)' : '#ffe3e3')
-    : (dark ? 'rgba(47,158,68,.22)' : '#d3f9d8');
-  const markFg = isDel
-    ? (dark ? theme.colors.red[3] : theme.colors.red[8])
-    : (dark ? theme.colors.green[3] : theme.colors.green[9]);
-
-  return (
-    <Group gap={7} wrap="nowrap" align="flex-start">
-      <Text ff="monospace" fw={600} fz={12} c={signColor} w={11} ta="center" style={{ flex: 'none', lineHeight: 1.5 }}>{sign}</Text>
-      <Text fz={13.5} c={baseColor} style={{ lineHeight: 1.45 }}>
-        {segments.map((seg, i) =>
-          seg.changed ? (
-            <Box key={i} component="mark" px={3} fw={600}
-              style={{ background: markBg, color: markFg, borderRadius: 3,
-                textDecoration: isDel ? 'line-through' : 'none' }}>
-              {visibleWhitespace(seg.text)}
-            </Box>
-          ) : (
-            <Box key={i} component="span" style={{ textDecoration: isDel ? 'line-through' : 'none' }}>{seg.text}</Box>
-          )
-        )}
-      </Text>
-    </Group>
-  );
-}
-
-function DiffBlock({ edit }: { edit: SuggestedEdit }) {
-  const pureInsert = edit.before.length === 0;
-  const pureDelete = edit.after.length === 0;
-  return (
-    <Stack gap={1}>
-      {!pureInsert && <DiffLine segments={edit.before} kind="del" />}
-      {!pureDelete && <DiffLine segments={edit.after} kind="ins" />}
-    </Stack>
-  );
-}
-
-/* ──────────────────────── Карточка правки ──────────────────────── */
-
-function EditCard({ c, onApply, onDismiss, onNavigateToAnchor, dismissUndoMs = 5000 }: {
-  c: Comment;
-  onApply: CommentsPanelProps['onApply'];
-  onDismiss: CommentsPanelProps['onDismiss'];
-  onNavigateToAnchor: CommentsPanelProps['onNavigateToAnchor'];
-  dismissUndoMs?: number;
-}) {
-  const parsed = useMemo(() => parseBody(c.bodyRaw), [c.bodyRaw]);
-  const [busy, setBusy] = useState(false);
-  const timer = useRef<number>();
-
-  const apply = useCallback(async () => {
-    setBusy(true);
-    try { await onApply(c.id); } finally { setBusy(false); }
-  }, [c.id, onApply]);
-
-  // Безопасный Dismiss: прячем сразу, удаляем на сервере после окна undo.
-  const dismiss = useCallback(() => {
-    let undone = false;
-    const nid = notifications.show({
-      message: 'Edit dismissed',
-      color: 'gray',
-      autoClose: dismissUndoMs,
-      withCloseButton: false,
-      // Кнопка "Вернуть" — см. README про кастомный рендер экшена.
-    });
-    timer.current = window.setTimeout(() => {
-      if (!undone) onDismiss(c.id);
-    }, dismissUndoMs);
-    // undo вызывается из UI: clearTimeout(timer.current); undone = true;
-    return { nid, cancel: () => { undone = true; clearTimeout(timer.current); } };
-  }, [c.id, onDismiss, dismissUndoMs]);
-
-  const conflict = c.status === 'conflict' || c.anchorLost;
-
-  return (
-    <Box
-      p="10px 12px"
-      onClick={() => onNavigateToAnchor(c.id)}
-      style={(t) => ({
-        cursor: 'pointer',
-        borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}`,
-      })}
-    >
-      <Stack gap={8}>
-        {c.edit && <DiffBlock edit={c.edit} />}
-
-        {conflict && (
-          <Group gap={7} wrap="nowrap" p="6px 8px"
-            style={(t) => ({ background: t.colorScheme === 'dark' ? 'rgba(230,180,20,.12)' : '#fff9db', borderRadius: 7 })}>
-            <Text fz={12}>⚠</Text>
-            <Text fz={12} c="yellow.8" style={{ lineHeight: 1.4 }}>Text changed — this edit can’t be applied</Text>
-          </Group>
-        )}
-
-        {parsed.text && !conflict && (
-          <Text fz={12.5} c="dimmed" style={{ lineHeight: 1.45 }}>{parsed.text}</Text>
-        )}
-
-        <Group gap={8} wrap="nowrap" onClick={(e) => e.stopPropagation()}>
-          <Box w={8} h={8} style={(t) => ({ flex: 'none', borderRadius: '50%', background: t.colors[SEV_COLOR[parsed.severity]][6] })} />
-          <Text fz={10} fw={600} tt="uppercase" c="dimmed" style={{ letterSpacing: '.06em', flex: 1, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>
-            {[parsed.category, parsed.severity === 'major' ? 'Major' : parsed.severity === 'critical' ? 'Critical' : null].filter(Boolean).join(' · ')}
-          </Text>
-
-          {c.status === 'applied' ? (
-            <Badge color="green" variant="light" radius="xl" size="sm">✓ Applied</Badge>
-          ) : c.status === 'dismissed' ? (
-            <Badge color="gray" variant="light" radius="xl" size="sm">Dismissed</Badge>
-          ) : conflict ? (
-            <Button size="compact-sm" variant="default" onClick={() => onNavigateToAnchor(c.id)}>Go to text</Button>
-          ) : (
-            <>
-              <Button size="compact-sm" variant="default" color="gray" onClick={dismiss}>Dismiss</Button>
-              <Button size="compact-sm" color="green" loading={busy} onClick={apply}>Apply</Button>
-            </>
-          )}
-        </Group>
-      </Stack>
-    </Box>
-  );
-}
-
-/* ──────────────────────── Человеческий тред ──────────────────────── */
-
-function HumanThread({ c, onResolve, onNavigateToAnchor }: {
-  c: Comment; onResolve?: CommentsPanelProps['onResolve']; onNavigateToAnchor: CommentsPanelProps['onNavigateToAnchor'];
-}) {
-  const parsed = useMemo(() => parseBody(c.bodyRaw), [c.bodyRaw]);
-  return (
-    <Box p="12px 14px" style={(t) => ({ borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}` })}>
-      <Stack gap={9}>
-        <Group gap={8} wrap="nowrap">
-          <Avatar size={26} radius="xl" color="orange">{c.authorName[0]}</Avatar>
-          <Text fz={12.5} fw={600}>{c.authorName}
-            <Text span c="dimmed" fw={400}> · {c.triggeredBy ? `${c.triggeredBy} · ` : ''}{c.createdAtLabel}</Text>
-          </Text>
-          <Box style={{ flex: 1 }} />
-          <Tooltip label="Resolve"><ActionIcon variant="default" size="md" onClick={() => onResolve?.(c.id)}>✓</ActionIcon></Tooltip>
-          <ActionIcon variant="default" size="md">⋯</ActionIcon>
-        </Group>
-        <Text fz={13.5} style={{ lineHeight: 1.5 }}>{parsed.text}</Text>
-        <Group gap={8}>
-          {c.replyCount ? <Text fz={12} c="dimmed">{c.replyCount} replies</Text> : null}
-          <Box style={{ flex: 1 }} />
-          <Button variant="subtle" size="compact-sm">Reply</Button>
-        </Group>
-      </Stack>
-    </Box>
-  );
-}
-
-/* ──────────────────── Шапка серии + прогресс ──────────────────── */
-
-function RunHeader({ runComments, onAcceptAll, progress }: {
-  runComments: Comment[];
-  onAcceptAll: () => void;
-  progress?: { done: number; total: number } | null;
-}) {
-  const head = runComments[0];
-  const majors = runComments.filter((c) => parseBody(c.bodyRaw).severity !== 'minor').length;
-  const applied = runComments.filter((c) => c.status === 'applied').length;
-  return (
-    <Box>
-      <Group gap={10} wrap="nowrap" p="11px 13px" style={(t) => ({ borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}` })}>
-        <Box style={{ position: 'relative', width: 30, height: 30, flex: 'none' }}>
-          <Avatar size={30} radius={8} color="teal">{head.authorName[0]}</Avatar>
-          {head.triggeredBy && (
-            <Avatar size={14} radius="xl" color="gray"
-              style={{ position: 'absolute', right: -4, bottom: -4, border: '2px solid var(--mantine-color-body)' }} />
-          )}
-        </Box>
-        <Stack gap={1} style={{ minWidth: 0 }}>
-          <Text fz={13} fw={600}>{head.authorName}
-            <Text span c="dimmed" fw={400}> · {head.triggeredBy} · {head.createdAtLabel}</Text>
-          </Text>
-          <Text fz={11.5} c="dimmed">
-            {runComments.length} edits · <Text span c="orange.7" fw={600}>{majors} major</Text> · {applied} applied
-          </Text>
-        </Stack>
-        <Box style={{ flex: 1 }} />
-        {!progress && <Button size="compact-sm" color="green" onClick={onAcceptAll}>Accept all</Button>}
-      </Group>
-      {progress && (
-        <Box p="9px 13px 11px" style={(t) => ({ background: t.colorScheme === 'dark' ? 'rgba(47,158,68,.08)' : '#f8fbf9', borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[2]}` })}>
-          <Group gap={8} mb={6}>
-            <Text fz={12} fw={600} c="green.7">Applying {progress.done} of {progress.total}…</Text>
-            <Box style={{ flex: 1 }} />
-            <Button variant="subtle" color="gray" size="compact-xs">Stop</Button>
-          </Group>
-          <Progress value={(progress.done / progress.total) * 100} color="green" size="sm" radius="xl" />
-        </Box>
-      )}
-    </Box>
-  );
-}
-
-/* ──────────────────────────── Панель ──────────────────────────── */
-
-/** Роль-автор для фильтра: у агентов — имя роли, у людей — «Пользователь». */
-function roleOf(c: Comment): string {
-  return c.authorKind === 'human' ? 'Пользователь' : c.authorName;
-}
-
-export function CommentsPanel(props: CommentsPanelProps) {
-  const { comments, onApply, onDismiss, onResolve, onNavigateToAnchor, onClose, dismissUndoMs } = props;
-  const [tab, setTab] = useState<'open' | 'resolved'>('open');
-  const [roleFilter, setRoleFilter] = useState<string | null>(null);
-  const [progress, setProgress] = useState<Record<string, { done: number; total: number }>>({});
-
-  const open = comments.filter((c) => c.status === 'pending' || c.status === 'conflict');
-  const resolved = comments.filter((c) => c.status === 'applied' || c.status === 'dismissed');
-  const list = tab === 'open' ? open : resolved;
-
-  const filtered = list.filter((c) => !roleFilter || roleOf(c) === roleFilter);
-
-  // Роли и счётчики для чипов-фильтров (только роли: Корректор / Фактчекер / Пользователь …).
-  const roles = useMemo(() => {
-    const order: string[] = [];
-    const count: Record<string, number> = {};
-    for (const c of list) {
-      const r = roleOf(c);
-      if (!(r in count)) { count[r] = 0; order.push(r); }
-      count[r]++;
-    }
-    return order.map((r) => ({ role: r, count: count[r] }));
-  }, [list]);
-
-  // Группировка агентских правок по runId; человеческие треды — по одному.
-  const groups = useMemo(() => {
-    const map = new Map<string, Comment[]>();
-    const singles: Comment[] = [];
-    for (const c of filtered) {
-      if (c.authorKind === 'agent' && c.runId && c.edit) {
-        if (!map.has(c.runId)) map.set(c.runId, []);
-        map.get(c.runId)!.push(c);
-      } else singles.push(c);
-    }
-    return { runs: [...map.entries()], singles };
-  }, [filtered]);
-
-  // Пакетное "Accept all" — по одной на фронте, обновляем прогресс.
-  const acceptAll = useCallback(async (runId: string, items: Comment[]) => {
-    const minor = items.filter((c) => parseBody(c.bodyRaw).severity === 'minor' && c.status === 'pending');
-    for (let i = 0; i < minor.length; i++) {
-      setProgress((p) => ({ ...p, [runId]: { done: i, total: minor.length } }));
-      try { await onApply(minor[i].id); } catch { /* конфликт — пропускаем, копим для сводки */ }
-    }
-    setProgress((p) => { const n = { ...p }; delete n[runId]; return n; });
-    notifications.show({ color: 'green', message: `${minor.length} applied` });
-  }, [onApply]);
-
-  return (
-    <Stack gap={0} h="100%" style={{ width: 380, maxWidth: '100%', borderLeft: '1px solid var(--mantine-color-default-border)' }}>
-      {/* Вкладки — статусная ось. Open/Resolved сохранены. */}
-      <Group gap={4} p="10px 14px" style={(t) => ({ borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[2]}` })}>
-        <Tabs value={tab} onChange={(v) => setTab(v as 'open' | 'resolved')} variant="pills">
-          <Tabs.List>
-            <Tabs.Tab value="open" rightSection={<Badge size="sm" variant="light" color="blue">{open.length}</Badge>}>Open</Tabs.Tab>
-            <Tabs.Tab value="resolved" rightSection={<Badge size="sm" variant="light" color="gray">{resolved.length}</Badge>}>Resolved</Tabs.Tab>
-          </Tabs.List>
-        </Tabs>
-        <Box style={{ flex: 1 }} />
-        {onClose && <ActionIcon variant="subtle" color="gray" onClick={onClose}>✕</ActionIcon>}
-      </Group>
-
-      {/* Фильтры-чипы: только по ролям (Корректор / Фактчекер / Пользователь). */}
-      {tab === 'open' && roles.length > 1 && (
-        <ScrollArea type="never" p="8px 14px" style={(t) => ({ borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}` })}>
-          <Group gap={6} wrap="nowrap">
-            <FilterChip active={!roleFilter} onClick={() => setRoleFilter(null)} label={`All ${list.length}`} solid />
-            {roles.map(({ role, count }) => (
-              <FilterChip key={role} active={roleFilter === role} onClick={() => setRoleFilter(roleFilter === role ? null : role)} label={`${role} ${count}`} />
-            ))}
-          </Group>
-        </ScrollArea>
-      )}
-
-      {/* Лента */}
-      <ScrollArea style={{ flex: 1 }} bg="var(--mantine-color-default-hover)">
-        {filtered.length === 0 ? (
-          <EmptyState tab={tab} />
-        ) : (
-          <>
-            {groups.runs.map(([runId, items]) => (
-              <Box key={runId} m="6px 10px" bg="var(--mantine-color-body)" style={{ border: '1px solid var(--mantine-color-default-border)', borderRadius: 10, overflow: 'hidden' }}>
-                <RunHeader runComments={items} progress={progress[runId] ?? null} onAcceptAll={() => acceptAll(runId, items)} />
-                {items.map((c) => (
-                  <EditCard key={c.id} c={c} onApply={onApply} onDismiss={onDismiss} onNavigateToAnchor={onNavigateToAnchor} dismissUndoMs={dismissUndoMs} />
-                ))}
-              </Box>
-            ))}
-            {groups.singles.map((c) => (
-              <Box key={c.id} m="6px 10px" bg="var(--mantine-color-body)" style={{ border: '1px solid var(--mantine-color-default-border)', borderRadius: 10, overflow: 'hidden' }}>
-                {c.edit
-                  ? <EditCard c={c} onApply={onApply} onDismiss={onDismiss} onNavigateToAnchor={onNavigateToAnchor} dismissUndoMs={dismissUndoMs} />
-                  : <HumanThread c={c} onResolve={onResolve} onNavigateToAnchor={onNavigateToAnchor} />}
-              </Box>
-            ))}
-          </>
-        )}
-      </ScrollArea>
-    </Stack>
-  );
-}
-
-/* ─────────────────────── Мелкие компоненты ─────────────────────── */
-
-function FilterChip({ label, active, onClick, dot, solid }: {
-  label: string; active: boolean; onClick: () => void; dot?: string; solid?: boolean;
-}) {
-  return (
-    <Button
-      onClick={onClick}
-      size="compact-sm"
-      radius="xl"
-      variant={active ? 'filled' : 'default'}
-      color={active ? (solid ? 'dark' : 'blue') : 'gray'}
-      leftSection={dot ? <Box w={7} h={7} style={(t) => ({ borderRadius: '50%', background: t.colors[dot][6] })} /> : undefined}
-      styles={{ root: { flex: 'none' }, label: { fontWeight: 600, fontSize: 12 } }}
-    >
-      {label}
-    </Button>
-  );
-}
-
-function EmptyState({ tab }: { tab: 'open' | 'resolved' }) {
-  const isOpen = tab === 'open';
-  return (
-    <Stack align="center" gap={6} p="40px 20px">
-      <Avatar size={40} radius="xl" color={isOpen ? 'green' : 'gray'}>{isOpen ? '✓' : '◌'}</Avatar>
-      <Text fw={600} fz={13}>{isOpen ? 'All caught up' : 'Nothing here yet'}</Text>
-      <Text fz={12} c="dimmed" ta="center" style={{ lineHeight: 1.45 }}>
-        {isOpen ? 'No edits waiting on you.' : 'Applied and closed items will appear here.'}
-      </Text>
-    </Stack>
-  );
-}
-
-export default CommentsPanel;

NewDesign/TimeWorkedModal.tsx

@@ -1,234 +0,0 @@
-/**
- * TimeWorkedModal — редизайн окна «Time worked on this article».
- * Mantine v7. Light/dark.
- *
- * ─────────────────────────────────────────────────────────────────────────
- * ЧТО ЭТО
- * ─────────────────────────────────────────────────────────────────────────
- * Сводка трудозатрат по дням в виде суточных таймлайнов. Главное отличие от
- * старой версии: на барах ВИДНО время суток. Реализовано двумя способами
- * (проп `axis`):
- *   - 'grid'   — ось часов 00–06–12–18–24 сверху + вертикальные деления,
- *                ночные часы (0–6, 21–24) слегка затемнены. По умолчанию.
- *   - 'phases' — цветные полосы фаз дня за блоками (Ночь/Утро/День/Вечер),
- *                период суток читается сразу, без счёта делений.
- *
- * Блоки позиционируются по времени: left = start/24, width = dur/24.
- * Интенсивность (opacity) блока = длительность/плотность работы, чтобы
- * очень короткие сессии не терялись (минимальная видимая ширина задана).
- * Hover-тултип на блоке: начало–конец · длительность.
- *
- * ─────────────────────────────────────────────────────────────────────────
- * УСТАНОВКА / ИСПОЛЬЗОВАНИЕ
- * ─────────────────────────────────────────────────────────────────────────
- *   import { TimeWorkedModal, DaySummary } from './TimeWorkedModal';
- *
- *   <TimeWorkedModal
- *     opened={open}
- *     onClose={() => setOpen(false)}
- *     totalLabel="≈ 34h"
- *     agentLabel="≈ 1h 20m"          // undefined → строку agent не показываем
- *     days={days}                     // DaySummary[]
- *     axis="grid"                     // 'grid' | 'phases'
- *     tz="Europe/Moscow"
- *     inactivityGapMin={15}
- *   />
- *
- * Требует MantineProvider на корне.
- *
- * ─────────────────────────────────────────────────────────────────────────
- * ФОРМАТ ДАННЫХ
- * ─────────────────────────────────────────────────────────────────────────
- *   interface Block {
- *     start: number;   // час начала в сутках, 0..24 (напр. 13.7 = 13:42)
- *     end: number;     // час конца
- *     kind: 'work' | 'agent';
- *   }
- *   interface DaySummary {
- *     label: string;       // «Mon 29 Jun»
- *     totalLabel: string;  // «1h 24m» | «—» для пустого дня
- *     blocks: Block[];     // [] → пустой день (полупрозрачная дорожка, итог «—»)
- *     isToday?: boolean;   // сегодня — неполные сутки (рисуем границу «сейчас»)
- *     nowFraction?: number;// 0..1 позиция «сейчас» для isToday
- *   }
- *
- * Данные уже есть в бэкенде трудозатрат: сессии с началом/концом + тип
- * (work/agent). Часы = локальные к tz. Изменений API не требуется.
- *
- * ─────────────────────────────────────────────────────────────────────────
- * СОСТОЯНИЯ (нарисованы/поддержаны)
- * ─────────────────────────────────────────────────────────────────────────
- *  - День: с активностью (work+agent) / только work / только agent / пустой (—).
- *  - Сегодня: граница «сейчас» на дорожке (nowFraction).
- *  - Короткий блок: минимальная ширина, не исчезает.
- *  - Пустая панель целиком: нет трудозатрат → EmptyState.
- *  - Длинный период: вертикальный скролл списка дней, шапка/легенда липкие.
- *  - Тёмная тема: токены Mantine.
- */
-import { Modal, Box, Group, Stack, Text, ActionIcon, ScrollArea, Tooltip, useMantineColorScheme } from '@mantine/core';
-
-/* ─────────────────────────── Типы ─────────────────────────── */
-
-export interface Block { start: number; end: number; kind: 'work' | 'agent'; }
-export interface DaySummary {
-  label: string;
-  totalLabel: string;
-  blocks: Block[];
-  isToday?: boolean;
-  nowFraction?: number;
-}
-export interface TimeWorkedModalProps {
-  opened: boolean;
-  onClose: () => void;
-  totalLabel: string;
-  agentLabel?: string;
-  days: DaySummary[];
-  axis?: 'grid' | 'phases';
-  tz?: string;
-  inactivityGapMin?: number;
-}
-
-const WORK = '#3b82f6';
-const AGENT = '#c026d3';
-
-const PHASES = [
-  { name: 'Ночь', s: 0, e: 6, bg: 'rgba(99,102,241,.10)', lg: '#e8eaff', fg: '#5b60c9' },
-  { name: 'Утро', s: 6, e: 12, bg: 'rgba(245,159,0,.10)', lg: '#fff2dc', fg: '#b5820e' },
-  { name: 'День', s: 12, e: 18, bg: 'rgba(56,178,172,.10)', lg: '#dcf5f2', fg: '#1a857d' },
-  { name: 'Вечер', s: 18, e: 24, bg: 'rgba(139,92,246,.11)', lg: '#efe7ff', fg: '#6d43c0' },
-];
-
-/* ─────────────────────────── Блок активности ─────────────────────────── */
-
-function fmtHour(h: number) {
-  const hh = Math.floor(h);
-  const mm = Math.round((h - hh) * 60);
-  return `${String(hh).padStart(2, '0')}:${String(mm).padStart(2, '0')}`;
-}
-function fmtDur(h: number) {
-  const total = Math.round(h * 60);
-  const hh = Math.floor(total / 60), mm = total % 60;
-  return hh ? `${hh}h ${mm}m` : `${mm}m`;
-}
-
-function ActivityBlock({ b }: { b: Block }) {
-  const left = (b.start / 24) * 100;
-  const width = Math.max(((b.end - b.start) / 24) * 100, 0.6);
-  const dur = b.end - b.start;
-  const opacity = dur < 0.16 ? 0.5 : dur < 0.35 ? 0.8 : 1;
-  return (
-    <Tooltip label={`${fmtHour(b.start)} – ${fmtHour(b.end)} · ${fmtDur(dur)}`} withArrow openDelay={120} fz={11}>
-      <Box style={{
-        position: 'absolute', top: 5, height: 14, left: `${left}%`, width: `${width}%`,
-        borderRadius: 2, background: b.kind === 'agent' ? AGENT : WORK, opacity, cursor: 'default',
-      }} />
-    </Tooltip>
-  );
-}
-
-/* ─────────────────────────── Дорожка дня ─────────────────────────── */
-
-function DayTrack({ d, axis, dark }: { d: DaySummary; axis: 'grid' | 'phases'; dark: boolean }) {
-  const trackBg = axis === 'grid'
-    ? 'linear-gradient(90deg, rgba(90,100,130,.10) 0 25%, rgba(90,100,130,.02) 25% 87.5%, rgba(90,100,130,.10) 87.5% 100%)'
-    : (dark ? 'rgba(255,255,255,.04)' : '#f6f8fa');
-
-  return (
-    <Group gap={0} h={30} wrap="nowrap">
-      <Text style={{ flex: 'none', width: 92 }} fz={13} c="dimmed">{d.label}</Text>
-      <Box style={{ position: 'relative', flex: 1, height: 24, margin: '0 4px', borderRadius: 5, overflow: 'hidden', background: trackBg }}>
-        {/* фон: полосы фаз или деления сетки */}
-        {axis === 'phases'
-          ? PHASES.map((ph) => (
-              <Box key={ph.name} style={{ position: 'absolute', top: 0, bottom: 0, left: `${(ph.s / 24) * 100}%`, width: `${((ph.e - ph.s) / 24) * 100}%`, background: ph.bg }} />
-            ))
-          : [25, 50, 75].map((p) => (
-              <Box key={p} style={{ position: 'absolute', top: 0, bottom: 0, left: `${p}%`, width: 1, background: 'rgba(120,130,150,.16)' }} />
-            ))}
-        {/* блоки */}
-        {d.blocks.map((b, i) => <ActivityBlock key={i} b={b} />)}
-        {/* граница «сейчас» для сегодняшнего дня */}
-        {d.isToday && d.nowFraction != null && (
-          <Box style={{ position: 'absolute', top: 0, bottom: 0, left: `${d.nowFraction * 100}%`, width: 2, background: '#fa5252' }} />
-        )}
-      </Box>
-      <Text style={{ flex: 'none', width: 64, textAlign: 'right' }} fz={12.5} fw={500} c={d.totalLabel === '—' ? 'dimmed' : undefined}>
-        {d.totalLabel}
-      </Text>
-    </Group>
-  );
-}
-
-/* ─────────────────────────── Окно ─────────────────────────── */
-
-export function TimeWorkedModal(props: TimeWorkedModalProps) {
-  const { opened, onClose, totalLabel, agentLabel, days, axis = 'grid', tz = 'Europe/Moscow', inactivityGapMin = 15 } = props;
-  const { colorScheme } = useMantineColorScheme();
-  const dark = colorScheme === 'dark';
-  const isEmpty = days.length === 0 || days.every((d) => d.blocks.length === 0);
-
-  return (
-    <Modal opened={opened} onClose={onClose} withCloseButton={false} size="46rem" radius="lg" padding={0}
-      overlayProps={{ backgroundOpacity: 0.5, blur: 1 }}>
-      <Box p="22px 24px 20px">
-        {/* header */}
-        <Group mb={14}>
-          <Text fz={17} fw={600}>Time worked on this article</Text>
-          <Box style={{ flex: 1 }} />
-          <ActionIcon variant="subtle" color="gray" size="lg" onClick={onClose}>✕</ActionIcon>
-        </Group>
-
-        {/* summary */}
-        <Group align="baseline" gap={16} mb={axis === 'grid' ? 8 : 16}>
-          <Text fz={22} fw={700}>{totalLabel}</Text>
-          {agentLabel && <Text fz={13} c="dimmed">agent: {agentLabel}</Text>}
-        </Group>
-
-        {/* legend (grid only) */}
-        {axis === 'grid' && (
-          <Group gap={16} mb={16}>
-            <Group gap={6}><Box w={12} h={12} style={{ borderRadius: 3, background: WORK }} /><Text fz={12} fw={500} c="dimmed">Work</Text></Group>
-            <Group gap={6}><Box w={12} h={12} style={{ borderRadius: 3, background: AGENT }} /><Text fz={12} fw={500} c="dimmed">Agent</Text></Group>
-          </Group>
-        )}
-
-        {isEmpty ? (
-          <Stack align="center" gap={6} p="48px 20px">
-            <Text fw={600} fz={14}>No time tracked yet</Text>
-            <Text fz={12.5} c="dimmed" ta="center">По этой статье ещё нет трудозатрат.</Text>
-          </Stack>
-        ) : (
-          <>
-            {/* axis header (sticky) */}
-            <Group gap={0} mb={5} wrap="nowrap" style={{ position: 'sticky', top: 0, zIndex: 2, background: 'var(--mantine-color-body)' }}>
-              <Box style={{ flex: 'none', width: 92 }} />
-              {axis === 'grid' ? (
-                <Box style={{ flex: 1, position: 'relative', height: 14, margin: '0 4px' }}>
-                  {[['0%', '00', 'flex-start'], ['25%', '06', 'center'], ['50%', '12', 'center'], ['75%', '18', 'center'], ['100%', '24', 'flex-end']].map(([l, t, al]) => (
-                    <Text key={t as string} fz={10} fw={500} c="dimmed" style={{ position: 'absolute', left: l as string, transform: al === 'center' ? 'translateX(-50%)' : al === 'flex-end' ? 'translateX(-100%)' : undefined }}>{t}</Text>
-                  ))}
-                </Box>
-              ) : (
-                <Box style={{ flex: 1, display: 'flex', height: 16, margin: '0 4px', borderRadius: 4, overflow: 'hidden' }}>
-                  {PHASES.map((ph) => (
-                    <Box key={ph.name} style={{ flex: ph.e - ph.s, display: 'flex', alignItems: 'center', justifyContent: 'center', background: ph.lg, color: ph.fg, font: '600 9.5px system-ui' }}>{ph.name}</Box>
-                  ))}
-                </Box>
-              )}
-              <Box style={{ flex: 'none', width: 64 }} />
-            </Group>
-
-            {/* day rows */}
-            <ScrollArea.Autosize mah="60vh" type="hover">
-              {days.map((d, i) => <DayTrack key={i} d={d} axis={axis} dark={dark} />)}
-            </ScrollArea.Autosize>
-          </>
-        )}
-
-        <Text mt={16} fz={11.5} c="dimmed">Estimate · timezone {tz} · inactivity gap {inactivityGapMin} min</Text>
-      </Box>
-    </Modal>
-  );
-}
-
-export default TimeWorkedModal;

apps/client/public/locales/en-US/translation.json

@@ -1,4 +1,7 @@
 {
+  "1 year": "1 year",
+  "30 days": "30 days",
+  "90 days": "90 days",
   "A new version is available": "A new version is available",
   "Account": "Account",
   "Active": "Active",
@@ -10,11 +13,24 @@
   "Add space members": "Add space members",
   "Add to favorites": "Add to favorites",
   "Admin": "Admin",
+  "API key copied to clipboard": "API key copied to clipboard",
+  "API key created": "API key created",
+  "API key revoked": "API key revoked",
+  "Confirm your password": "Confirm your password",
+  "Copy API key": "Copy API key",
+  "Copy to clipboard": "Copy to clipboard",
+  "Copy {{name}}": "Copy {{name}}",
+  "Enter your password to copy the API key \"{{name}}\" to your clipboard.": "Enter your password to copy the API key \"{{name}}\" to your clipboard.",
+  "Failed to copy API key": "Failed to copy API key",
+  "Incorrect password": "Incorrect password",
+  "API keys across the workspace.": "API keys across the workspace.",
   "Are you sure you want to delete this group? Members will lose access to resources this group has access to.": "Are you sure you want to delete this group? Members will lose access to resources this group has access to.",
   "Are you sure you want to delete this page?": "Are you sure you want to delete this page?",
   "Are you sure you want to remove this user from the group? The user will lose access to resources this group has access to.": "Are you sure you want to remove this user from the group? The user will lose access to resources this group has access to.",
   "Are you sure you want to remove this user from the space? The user will lose all access to this space.": "Are you sure you want to remove this user from the space? The user will lose all access to this space.",
   "Are you sure you want to restore this version? Any changes not versioned will be lost.": "Are you sure you want to restore this version? Any changes not versioned will be lost.",
+  "Are you sure you want to revoke \"{{name}}\"? Any client using this key will immediately lose access. This cannot be undone.": "Are you sure you want to revoke \"{{name}}\"? Any client using this key will immediately lose access. This cannot be undone.",
+  "Author": "Author",
   "Can become members of groups and spaces in workspace": "Can become members of groups and spaces in workspace",
   "Can create and edit pages in space.": "Can create and edit pages in space.",
   "Can edit": "Can edit",
@@ -33,11 +49,14 @@
   "Confirm": "Confirm",
   "Copy as Markdown": "Copy as Markdown",
   "Copy link": "Copy link",
+  "Copy your API key now and store it somewhere safe. For security reasons it will not be shown again.": "Copy your API key now and store it somewhere safe. For security reasons it will not be shown again.",
   "Create": "Create",
+  "Create API key": "Create API key",
   "Create group": "Create group",
   "Create page": "Create page",
   "Create space": "Create space",
   "Create workspace": "Create workspace",
+  "Critical": "Critical",
   "Current password": "Current password",
   "Dark": "Dark",
   "Date": "Date",
@@ -55,7 +74,14 @@
   "e.g Sales": "e.g Sales",
   "e.g Space for product team": "e.g Space for product team",
   "e.g Space for sales team to collaborate": "e.g Space for sales team to collaborate",
+  "e.g. CI deploy token": "e.g. CI deploy token",
   "Edit": "Edit",
+  "Expiring soon": "Expiring soon",
+  "Failed to create API key": "Failed to create API key",
+  "Failed to load API keys.": "Failed to load API keys.",
+  "Failed to revoke API key": "Failed to revoke API key",
+  "Never used": "Never used",
+  "No API keys yet": "No API keys yet",
   "Read": "Read",
   "Edit group": "Edit group",
   "Email": "Email",
@@ -108,6 +134,7 @@
   "Link copied": "Link copied",
   "Login": "Login",
   "Logout": "Logout",
+  "Major": "Major",
   "Manage Group": "Manage Group",
   "Manage members": "Manage members",
   "member": "member",
@@ -134,6 +161,8 @@
   "page": "page",
   "Page deleted successfully": "Page deleted successfully",
   "Page history": "Page history",
+  "Revoke API key": "Revoke API key",
+  "Revoke {{name}}": "Revoke {{name}}",
   "Select version": "Select version",
   "Highlight changes": "Highlight changes",
   "Page import is in progress. Please do not close this tab.": "Page import is in progress. Please do not close this tab.",
@@ -189,6 +218,9 @@
   "Template": "Template",
   "Templates": "Templates",
   "Theme": "Theme",
+  "This key expires within 30 days": "This key expires within 30 days",
+  "This key has expired": "This key has expired",
+  "This key never expires": "This key never expires",
   "To change your email, you have to enter your password and new email.": "To change your email, you have to enter your password and new email.",
   "Toggle full page width": "Toggle full page width",
   "Unable to import pages. Please try again.": "Unable to import pages. Please try again.",
@@ -196,6 +228,7 @@
   "Untitled": "Untitled",
   "Updated successfully": "Updated successfully",
   "User": "User",
+  "Within the last hour": "Within the last hour",
   "Workspace": "Workspace",
   "Workspace Name": "Workspace Name",
   "Workspace settings": "Workspace settings",
@@ -426,9 +459,12 @@
   "Write anything. Enter \"/\" for commands": "Write anything. Enter \"/\" for commands",
   "Write...": "Write...",
   "Column count": "Column count",
+  "Your personal API keys.": "Your personal API keys.",
   "{{count}} Columns": "{{count}} Columns",
   "{{count}} command available_one": "1 command available",
   "{{count}} command available_other": "{{count}} commands available",
+  "{{count}} edits": "{{count}} edits",
+  "{{count}} major": "{{count}} major",
   "{{count}} result available_one": "1 result available",
   "{{count}} result available_other": "{{count}} results available",
   "{{count}} result found_one": "{{count}} result found",
@@ -1440,6 +1476,7 @@
   "agent: {{value}}": "agent: {{value}}",
   "Work": "Work",
   "Agent": "Agent",
+  "{{start}} – {{end}} · {{duration}}": "{{start}} – {{end}} · {{duration}}",
   "≈ {{hours}}h {{minutes}}m": "≈ {{hours}}h {{minutes}}m",
   "≈ {{hours}}h": "≈ {{hours}}h",
   "≈ {{minutes}}m": "≈ {{minutes}}m",

apps/client/public/locales/ru-RU/translation.json

@@ -1,4 +1,7 @@
 {
+  "1 year": "1 год",
+  "30 days": "30 дней",
+  "90 days": "90 дней",
   "A new version is available": "Доступна новая версия",
   "Account": "Аккаунт",
   "Active": "Активный",
@@ -10,11 +13,24 @@
   "Add space members": "Добавить участников пространства",
   "Add to favorites": "Добавить в избранное",
   "Admin": "Администратор",
+  "API key copied to clipboard": "API ключ скопирован в буфер обмена",
+  "API key created": "API ключ создан",
+  "API key revoked": "API ключ отозван",
+  "Confirm your password": "Подтвердите пароль",
+  "Copy API key": "Скопировать API ключ",
+  "Copy to clipboard": "Скопировать в буфер обмена",
+  "Copy {{name}}": "Скопировать {{name}}",
+  "Enter your password to copy the API key \"{{name}}\" to your clipboard.": "Введите пароль, чтобы скопировать API ключ «{{name}}» в буфер обмена.",
+  "Failed to copy API key": "Не удалось скопировать API ключ",
+  "Incorrect password": "Неверный пароль",
+  "API keys across the workspace.": "API ключи всего рабочего пространства.",
   "Are you sure you want to delete this group? Members will lose access to resources this group has access to.": "Вы уверены, что хотите удалить эту группу? Участники потеряют доступ к материалам, к которым у этой группы есть доступ.",
   "Are you sure you want to delete this page?": "Вы уверены, что хотите удалить эту страницу?",
   "Are you sure you want to remove this user from the group? The user will lose access to resources this group has access to.": "Вы уверены, что хотите удалить этого пользователя из группы? Пользователь потеряет доступ к материалам, к которым есть доступ у этой группы.",
   "Are you sure you want to remove this user from the space? The user will lose all access to this space.": "Вы уверены, что хотите удалить этого пользователя из пространства? Пользователь потеряет весь доступ к этому пространству.",
   "Are you sure you want to restore this version? Any changes not versioned will be lost.": "Вы уверены, что хотите восстановить эту версию? Все не зафиксированные изменения будут потеряны.",
+  "Are you sure you want to revoke \"{{name}}\"? Any client using this key will immediately lose access. This cannot be undone.": "Вы уверены, что хотите отозвать «{{name}}»? Любой клиент, использующий этот ключ, немедленно потеряет доступ. Это действие нельзя отменить.",
+  "Author": "Автор",
   "Can become members of groups and spaces in workspace": "Могут становиться участниками групп и пространств в рабочей области",
   "Can create and edit pages in space.": "Может создавать и редактировать страницы в пространстве.",
   "Can edit": "Может изменять",
@@ -33,11 +49,14 @@
   "Confirm": "Подтвердить",
   "Copy as Markdown": "Копировать как Markdown",
   "Copy link": "Копировать ссылку",
+  "Copy your API key now and store it somewhere safe. For security reasons it will not be shown again.": "Скопируйте API ключ сейчас и сохраните его в надёжном месте. В целях безопасности он больше не будет показан.",
   "Create": "Создать",
+  "Create API key": "Создать API ключ",
   "Create group": "Создать группу",
   "Create page": "Создать страницу",
   "Create space": "Создать пространство",
   "Create workspace": "Создать рабочую область",
+  "Critical": "Критично",
   "Current password": "Текущий пароль",
   "Dark": "Темная",
   "Date": "Дата",
@@ -46,6 +65,7 @@
   "Are you sure you want to delete this page? This will delete its children and page history. This action is irreversible.": "Вы уверены, что хотите удалить эту страницу? Это удалит её дочерние страницы, а также историю страницы. Это действие необратимо.",
   "Description": "Описание",
   "Details": "Подробности",
+  "Done": "Готово",
   "e.g ACME": "например, ACME",
   "e.g ACME Inc": "например, ACME Inc",
   "e.g Developers": "например, Developers",
@@ -55,7 +75,15 @@
   "e.g Sales": "например, Sales",
   "e.g Space for product team": "например, Пространство для команды продукта",
   "e.g Space for sales team to collaborate": "например, Пространство для совместной работы команды продаж",
+  "e.g. CI deploy token": "например, токен деплоя CI",
   "Edit": "Редактировать",
+  "Expiring soon": "Скоро истекает",
+  "Failed to create API key": "Не удалось создать API ключ",
+  "Failed to load API keys.": "Не удалось загрузить API ключи.",
+  "Failed to revoke API key": "Не удалось отозвать API ключ",
+  "Name is required": "Имя обязательно",
+  "Never used": "Не использовался",
+  "No API keys yet": "Пока нет API ключей",
   "Read": "Чтение",
   "Edit group": "Редактировать группу",
   "Email": "Электронная почта",
@@ -108,6 +136,7 @@
   "Link copied": "Ссылка скопирована",
   "Login": "Войти",
   "Logout": "Выйти",
+  "Major": "Существенно",
   "Manage Group": "Управление группой",
   "Manage members": "Управление участниками",
   "member": "участник",
@@ -134,6 +163,8 @@
   "page": "страница",
   "Page deleted successfully": "Страница успешно удалена",
   "Page history": "История страницы",
+  "Revoke API key": "Отозвать API ключ",
+  "Revoke {{name}}": "Отозвать {{name}}",
   "Select version": "Выбрать версию",
   "Highlight changes": "Выделить изменения",
   "Page import is in progress. Please do not close this tab.": "Импорт страницы в процессе. Пожалуйста, не закрывайте эту вкладку.",
@@ -189,6 +220,9 @@
   "Template": "Шаблон",
   "Templates": "Шаблоны",
   "Theme": "Тема",
+  "This key expires within 30 days": "Этот ключ истекает в течение 30 дней",
+  "This key has expired": "Этот ключ истек",
+  "This key never expires": "Этот ключ никогда не истекает",
   "To change your email, you have to enter your password and new email.": "Чтобы изменить электронную почту, вам нужно ввести пароль и новый адрес.",
   "Toggle full page width": "Переключить полную ширину страницы",
   "Unable to import pages. Please try again.": "Не удалось импортировать страницы. Пожалуйста, попробуйте ещё раз.",
@@ -196,6 +230,7 @@
   "Untitled": "Без названия",
   "Updated successfully": "Успешно обновлено",
   "User": "Пользователь",
+  "Within the last hour": "За последний час",
   "Workspace": "Рабочее пространство",
   "Workspace Name": "Название рабочего пространства",
   "Workspace settings": "Настройки рабочего пространства",
@@ -432,9 +467,12 @@
   "Write anything. Enter \"/\" for commands": "Пишите что угодно. Введите \"/\" для команд",
   "Write...": "Напишите...",
   "Column count": "Количество столбцов",
+  "Your personal API keys.": "Ваши личные API ключи.",
   "{{count}} Columns": "{count, plural, one{# столбец} few{# столбца} many{# столбцов} other{# столбца}}",
   "{{count}} command available_one": "Доступна 1 команда",
   "{{count}} command available_other": "Доступно {{count}} команд",
+  "{{count}} edits": "{count, plural, one{# правка} few{# правки} many{# правок} other{# правки}}",
+  "{{count}} major": "{count, plural, one{# существенная} few{# существенных} many{# существенных} other{# существенных}}",
   "{{count}} result available_one": "Доступен 1 результат",
   "{{count}} result available_other": "Доступно {{count}} результатов",
   "{{count}} result found_one": "Найден {{count}} результат",
@@ -1455,6 +1493,7 @@
   "agent: {{value}}": "агент: {{value}}",
   "Work": "Работа",
   "Agent": "Агент",
+  "{{start}} – {{end}} · {{duration}}": "{{start}} – {{end}} · {{duration}}",
   "≈ {{hours}}h {{minutes}}m": "≈ {{hours}} ч {{minutes}} мин",
   "≈ {{hours}}h": "≈ {{hours}} ч",
   "≈ {{minutes}}m": "≈ {{minutes}} мин",

apps/client/src/App.tsx

@@ -44,6 +44,12 @@ const AccountSettings = lazy(
 const AccountPreferences = lazy(
   () => import("@/pages/settings/account/account-preferences.tsx"),
 );
+// #506 — lazy leaf (own chunk): the API-keys management page is route-split so
+// its code (Mantine table/modals + the create/revoke flow) stays out of the
+// entry bundle (post-#342 bundle discipline).
+const AccountApiKeys = lazy(
+  () => import("@/pages/settings/account/account-api-keys.tsx"),
+);
 const WorkspaceSettings = lazy(
   () => import("@/pages/settings/workspace/workspace-settings"),
 );
@@ -105,6 +111,7 @@ export default function App() {
               path={"account/preferences"}
               element={<AccountPreferences />}
             />
+            <Route path={"account/api-keys"} element={<AccountApiKeys />} />
             <Route path={"workspace"} element={<WorkspaceSettings />} />
             <Route path={"ai"} element={<AiSettings />} />
             <Route path={"members"} element={<WorkspaceMembers />} />

apps/client/src/components/settings/settings-sidebar.tsx

@@ -10,6 +10,7 @@ import {
   IconBrush,
   IconWorld,
   IconSparkles,
+  IconKey,
 } from "@tabler/icons-react";
 import { Link, useLocation } from "react-router-dom";
 import classes from "./settings.module.css";
@@ -46,6 +47,11 @@ const groupedData: DataGroup[] = [
         icon: IconBrush,
         path: "/settings/account/preferences",
       },
+      {
+        label: "API keys",
+        icon: IconKey,
+        path: "/settings/account/api-keys",
+      },
     ],
   },
   {

apps/client/src/features/api-key/components/api-keys-manager.test.tsx

@@ -0,0 +1,296 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  render,
+  screen,
+  fireEvent,
+  waitFor,
+  within,
+} from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { ModalsProvider } from "@mantine/modals";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Provider, createStore } from "jotai";
+import { UserRole } from "@/lib/types";
+import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
+import { IApiKey } from "@/features/api-key/types/api-key.types";
+
+// Mock the service layer so no real HTTP is attempted; every test drives the
+// component through these three functions.
+vi.mock("@/features/api-key/services/api-key-service", () => ({
+  getApiKeys: vi.fn(),
+  createApiKey: vi.fn(),
+  revokeApiKey: vi.fn(),
+  revealApiKey: vi.fn(),
+}));
+
+import {
+  getApiKeys,
+  createApiKey,
+  revokeApiKey,
+  revealApiKey,
+} from "@/features/api-key/services/api-key-service";
+import ApiKeysManager from "./api-keys-manager";
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+const ISO_SOON = new Date(Date.now() + 10 * 864e5).toISOString();
+const ISO_FAR = new Date(Date.now() + 200 * 864e5).toISOString();
+const ISO_EXPIRED = new Date(Date.now() - 3 * 864e5).toISOString();
+
+// Dump the storage stub via the Web Storage API — its data lives in a closure
+// (see vitest.setup.ts), so JSON.stringify(localStorage) would be vacuous.
+function storageDump(): string {
+  let out = "";
+  for (let i = 0; i < localStorage.length; i++) {
+    const k = localStorage.key(i) as string;
+    out += `${k}=${localStorage.getItem(k)};`;
+  }
+  return out;
+}
+
+function makeKey(overrides: Partial<IApiKey> = {}): IApiKey {
+  return {
+    id: "key-1",
+    name: "CI token",
+    expiresAt: ISO_FAR,
+    lastUsedAt: null,
+    createdAt: "2026-01-01T00:00:00.000Z",
+    creator: { id: "u1", name: "Alice", email: "a@x.io", avatarUrl: null },
+    ...overrides,
+  };
+}
+
+function renderManager(role: UserRole) {
+  const store = createStore();
+  store.set(currentUserAtom, {
+    user: { id: "me", role } as never,
+    workspace: {} as never,
+  });
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const utils = render(
+    <Provider store={store}>
+      <QueryClientProvider client={queryClient}>
+        <MantineProvider>
+          <ModalsProvider>
+            <ApiKeysManager />
+          </ModalsProvider>
+        </MantineProvider>
+      </QueryClientProvider>
+    </Provider>,
+  );
+  return { store, queryClient, ...utils };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  localStorage.clear();
+});
+
+describe("ApiKeysManager — list rendering", () => {
+  it("renders an explicit expiry date and highlights a <30-day key (acceptance #3)", async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([
+      makeKey({ id: "k-soon", name: "Soon key", expiresAt: ISO_SOON }),
+      makeKey({ id: "k-far", name: "Far key", expiresAt: ISO_FAR }),
+    ]);
+
+    renderManager(UserRole.MEMBER);
+
+    await screen.findByText("Soon key");
+    // Explicit dates, not "in N days": the year is rendered verbatim.
+    const soonYear = new Date(ISO_SOON).getFullYear().toString();
+    expect(screen.getAllByText(new RegExp(soonYear)).length).toBeGreaterThan(0);
+    // Exactly one key is inside the 30-day warning window.
+    expect(screen.getAllByText("Expiring soon")).toHaveLength(1);
+  });
+
+  it('shows "Expired" (not "Expiring soon") for an already-expired key', async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([
+      makeKey({ id: "k-dead", name: "Dead key", expiresAt: ISO_EXPIRED }),
+    ]);
+    renderManager(UserRole.MEMBER);
+    await screen.findByText("Dead key");
+    // A past expiry is labelled "Expired", never the forward-looking badge.
+    expect(screen.getByText("Expired")).toBeDefined();
+    expect(screen.queryByText("Expiring soon")).toBeNull();
+  });
+
+  it('shows "Never" for an unlimited key and no highlight', async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([
+      makeKey({ id: "k-forever", name: "Forever", expiresAt: null }),
+    ]);
+    renderManager(UserRole.MEMBER);
+    await screen.findByText("Forever");
+    expect(screen.getByText("Never")).toBeDefined();
+    expect(screen.queryByText("Expiring soon")).toBeNull();
+  });
+
+  it("empty list shows the empty state", async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([]);
+    renderManager(UserRole.MEMBER);
+    expect(await screen.findByText("No API keys yet")).toBeDefined();
+  });
+});
+
+describe("ApiKeysManager — admin vs member view (acceptance #6)", () => {
+  it("a member does NOT see the author column", async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([
+      makeKey({ creator: { id: "me", name: "Me", email: "m@x.io", avatarUrl: null } }),
+    ]);
+    renderManager(UserRole.MEMBER);
+    await screen.findByText("CI token");
+    // Author header absent + creator name not rendered (no author column).
+    expect(screen.queryByText("Author")).toBeNull();
+    expect(screen.queryByText("Me")).toBeNull();
+  });
+
+  it("an admin sees the author column with the creator's name", async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([
+      makeKey({ creator: { id: "u1", name: "Alice", email: "a@x.io", avatarUrl: null } }),
+    ]);
+    renderManager(UserRole.ADMIN);
+    await screen.findByText("CI token");
+    expect(screen.getByText("Author")).toBeDefined();
+    expect(screen.getByText("Alice")).toBeDefined();
+  });
+});
+
+describe("ApiKeysManager — revoke (acceptance #4)", () => {
+  it("revoke removes the row from the list", async () => {
+    vi.mocked(getApiKeys)
+      .mockResolvedValueOnce([
+        makeKey({ id: "k1", name: "Doomed" }),
+        makeKey({ id: "k2", name: "Survivor" }),
+      ])
+      // After revoke, invalidation refetches the reduced list.
+      .mockResolvedValue([makeKey({ id: "k2", name: "Survivor" })]);
+    vi.mocked(revokeApiKey).mockResolvedValue();
+
+    renderManager(UserRole.MEMBER);
+    await screen.findByText("Doomed");
+
+    fireEvent.click(screen.getByLabelText("Revoke Doomed"));
+    // Confirm modal → click the destructive confirm button.
+    const confirm = await screen.findByRole("button", { name: "Revoke" });
+    fireEvent.click(confirm);
+
+    await waitFor(() =>
+      expect(screen.queryByText("Doomed")).toBeNull(),
+    );
+    expect(screen.getByText("Survivor")).toBeDefined();
+    expect(revokeApiKey).toHaveBeenCalledWith("k1");
+  });
+});
+
+describe("ApiKeysManager — create no longer shows the token (copy replaces show-once)", () => {
+  it("create closes the modal + toasts without ever rendering the token", async () => {
+    const SECRET = "gm_secret-created-value";
+    vi.mocked(getApiKeys).mockResolvedValue([]);
+    vi.mocked(createApiKey).mockResolvedValue({
+      token: SECRET,
+      apiKey: {
+        id: "new-1",
+        name: "My key",
+        expiresAt: ISO_FAR,
+        createdAt: new Date().toISOString(),
+      },
+    });
+
+    const { queryClient } = renderManager(UserRole.MEMBER);
+    await screen.findByText("No API keys yet");
+
+    fireEvent.click(
+      screen.getAllByRole("button", { name: "Create API key" })[0],
+    );
+    const nameInput = await screen.findByLabelText(/Name/);
+    fireEvent.change(nameInput, { target: { value: "My key" } });
+    fireEvent.click(screen.getByRole("button", { name: "Create" }));
+
+    await waitFor(() => expect(createApiKey).toHaveBeenCalled());
+    // The token is never rendered (no more show-once modal).
+    expect(screen.queryByTestId("api-key-token")).toBeNull();
+    expect(screen.queryByText(SECRET)).toBeNull();
+
+    // The created token never lands in localStorage or the react-query caches.
+    expect(storageDump()).not.toContain(SECRET);
+    const cacheDump = JSON.stringify(
+      queryClient.getQueryCache().getAll().map((q) => q.state.data),
+    );
+    expect(cacheDump).not.toContain(SECRET);
+    const mutationDump = JSON.stringify(
+      queryClient.getMutationCache().getAll().map((m) => m.state.data),
+    );
+    expect(mutationDump).not.toContain(SECRET);
+  });
+});
+
+describe("ApiKeysManager — copy under step-up (acceptance #9)", () => {
+  it("copies a re-minted token to the clipboard and leaks it nowhere else", async () => {
+    const SECRET = "gm_revealed-token-value-xyz";
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    // jsdom has no clipboard; install a stub the copy helper will use.
+    Object.defineProperty(navigator, "clipboard", {
+      value: { writeText },
+      configurable: true,
+    });
+
+    vi.mocked(getApiKeys).mockResolvedValue([makeKey({ id: "k1", name: "CI token" })]);
+    vi.mocked(revealApiKey).mockResolvedValue(SECRET);
+
+    const { queryClient } = renderManager(UserRole.MEMBER);
+    await screen.findByText("CI token");
+
+    // Click the per-row Copy action → password step-up modal.
+    fireEvent.click(screen.getByLabelText("Copy CI token"));
+    const pwInput = await screen.findByLabelText("Password");
+    fireEvent.change(pwInput, { target: { value: "hunter2" } });
+    fireEvent.click(screen.getByRole("button", { name: "Copy to clipboard" }));
+
+    // The reveal request carried the id + password; the token was written to the
+    // clipboard and NOWHERE else.
+    await waitFor(() =>
+      expect(revealApiKey).toHaveBeenCalledWith({
+        id: "k1",
+        password: "hunter2",
+      }),
+    );
+    await waitFor(() => expect(writeText).toHaveBeenCalledWith(SECRET));
+
+    // The revealed secret is never in the DOM, localStorage, or either cache.
+    expect(screen.queryByText(SECRET)).toBeNull();
+    expect(storageDump()).not.toContain(SECRET);
+    const cacheDump = JSON.stringify(
+      queryClient.getQueryCache().getAll().map((q) => q.state.data),
+    );
+    expect(cacheDump).not.toContain(SECRET);
+    const mutationDump = JSON.stringify(
+      queryClient.getMutationCache().getAll().map((m) => m.state.data),
+    );
+    expect(mutationDump).not.toContain(SECRET);
+  });
+
+  it("a wrong password keeps the modal open and does not copy", async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    Object.defineProperty(navigator, "clipboard", {
+      value: { writeText },
+      configurable: true,
+    });
+    vi.mocked(getApiKeys).mockResolvedValue([makeKey({ id: "k1", name: "CI token" })]);
+    // Server returns a 401 for a wrong step-up password.
+    vi.mocked(revealApiKey).mockRejectedValue({ response: { status: 401 } });
+
+    renderManager(UserRole.MEMBER);
+    await screen.findByText("CI token");
+
+    fireEvent.click(screen.getByLabelText("Copy CI token"));
+    const pwInput = await screen.findByLabelText("Password");
+    fireEvent.change(pwInput, { target: { value: "wrong" } });
+    fireEvent.click(screen.getByRole("button", { name: "Copy to clipboard" }));
+
+    await waitFor(() => expect(revealApiKey).toHaveBeenCalled());
+    // Nothing copied; the password field is still on screen for a retry.
+    expect(writeText).not.toHaveBeenCalled();
+    expect(await screen.findByLabelText("Password")).toBeDefined();
+  });
+});

apps/client/src/features/api-key/components/api-keys-manager.tsx

@@ -0,0 +1,308 @@
+import { useState } from "react";
+import {
+  ActionIcon,
+  Badge,
+  Button,
+  Center,
+  Group,
+  Loader,
+  Stack,
+  Table,
+  Text,
+  Tooltip,
+} from "@mantine/core";
+import { modals } from "@mantine/modals";
+import { notifications } from "@mantine/notifications";
+import { IconAlertTriangle, IconCopy, IconKey, IconTrash } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import useUserRole from "@/hooks/use-user-role.tsx";
+import { formatLocalized, useDateFnsLocale } from "@/lib/date-locale";
+import { timeAgo } from "@/lib/time";
+import { copyToClipboard } from "@/lib/copy-to-clipboard";
+import {
+  useApiKeysQuery,
+  useCreateApiKeyMutation,
+  useRevealApiKeyMutation,
+  useRevokeApiKeyMutation,
+} from "@/features/api-key/queries/api-key-query";
+import { IApiKey } from "@/features/api-key/types/api-key.types";
+import {
+  isExpired,
+  isExpiringSoon,
+  lastUsedBucket,
+} from "@/features/api-key/utils";
+import { CreateApiKeyModal } from "./create-api-key-modal";
+import { RevealKeyModal } from "./reveal-key-modal";
+
+export default function ApiKeysManager() {
+  const { t } = useTranslation();
+  const locale = useDateFnsLocale();
+  // Manage-on-API === Owner/Admin server-side, so the admin (workspace-wide)
+  // list + "author" column mirror exactly the roles the server serves the
+  // whole-workspace response to.
+  const { isAdmin } = useUserRole();
+
+  const { data: keys, isLoading, isError } = useApiKeysQuery();
+  const createMutation = useCreateApiKeyMutation();
+  const revokeMutation = useRevokeApiKeyMutation();
+  const revealMutation = useRevealApiKeyMutation();
+
+  const [createOpened, setCreateOpened] = useState(false);
+  // SECURITY: only the key METADATA is held here (for the modal title) — never a
+  // token. The token is copied straight to the clipboard in handleCopy and is
+  // never stored in state, the query cache or localStorage.
+  const [revealTarget, setRevealTarget] = useState<IApiKey | null>(null);
+
+  const handleCreate = async (values: {
+    name: string;
+    expiresAt: string | null;
+  }): Promise<boolean> => {
+    try {
+      await createMutation.mutateAsync(values);
+      // The create response carries a token, but it is now retrievable any time
+      // via the per-row Copy action (reveal), so we DISCARD it here: purge
+      // react-query's copy immediately and never move it into state. The user
+      // copies the key from the list via a password step-up.
+      createMutation.reset();
+      setCreateOpened(false);
+      notifications.show({ message: t("API key created") });
+      return true;
+    } catch {
+      notifications.show({
+        message: t("Failed to create API key"),
+        color: "red",
+      });
+      return false;
+    }
+  };
+
+  // Password step-up accepted -> re-mint + copy. The token exists only as a local
+  // `const` for the single clipboard write, then react-query's copy is reset().
+  // It never enters component state, the query cache or localStorage.
+  const handleCopy = async (password: string): Promise<boolean> => {
+    const target = revealTarget;
+    if (!target) return false;
+    try {
+      const token = await revealMutation.mutateAsync({
+        id: target.id,
+        password,
+      });
+      await copyToClipboard(token);
+      revealMutation.reset();
+      notifications.show({ message: t("API key copied to clipboard") });
+      return true;
+    } catch (err) {
+      revealMutation.reset();
+      // 401 = wrong password (keep the modal open to retry); anything else is a
+      // uniform failure (the server does not distinguish key states).
+      const status = (err as { response?: { status?: number } })?.response
+        ?.status;
+      notifications.show({
+        message:
+          status === 401
+            ? t("Incorrect password")
+            : t("Failed to copy API key"),
+        color: "red",
+      });
+      return false;
+    }
+  };
+
+  const openRevokeModal = (key: IApiKey) =>
+    modals.openConfirmModal({
+      title: t("Revoke API key"),
+      centered: true,
+      children: (
+        <Text size="sm">
+          {t(
+            'Are you sure you want to revoke "{{name}}"? Any client using this key will immediately lose access. This cannot be undone.',
+            { name: key.name },
+          )}
+        </Text>
+      ),
+      labels: { confirm: t("Revoke"), cancel: t("Cancel") },
+      confirmProps: { color: "red" },
+      onConfirm: () => revokeMutation.mutate(key.id),
+    });
+
+  const formatDate = (iso: string) =>
+    formatLocalized(new Date(iso), "MMM dd, yyyy", "PP", locale);
+
+  const renderLastUsed = (lastUsedAt: string | null) => {
+    switch (lastUsedBucket(lastUsedAt)) {
+      case "never":
+        return t("Never used");
+      case "recent":
+        return t("Within the last hour");
+      case "stale":
+        // Coarse relative time — last_used_at is throttled to ~1h server-side,
+        // so we don't promise finer precision.
+        return timeAgo(new Date(lastUsedAt as string));
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <Center py="xl">
+        <Loader size="sm" />
+      </Center>
+    );
+  }
+
+  const rows = (keys ?? []).map((key) => {
+    // Mutually exclusive: an already-expired key is labelled "Expired" (a past
+    // expiry) rather than the forward-looking "Expiring soon". isExpiringSoon
+    // also matches past expiries, so gate "soon" on !expired.
+    const expired = isExpired(key.expiresAt);
+    const soon = !expired && isExpiringSoon(key.expiresAt);
+    return (
+      <Table.Tr key={key.id}>
+        <Table.Td>
+          <Text fw={500}>{key.name}</Text>
+        </Table.Td>
+        <Table.Td>{formatDate(key.createdAt)}</Table.Td>
+        <Table.Td>
+          {key.expiresAt ? (
+            <Group gap={6} wrap="nowrap">
+              <Text size="sm">{formatDate(key.expiresAt)}</Text>
+              {expired && (
+                <Tooltip label={t("This key has expired")} withArrow>
+                  <Badge
+                    color="red"
+                    variant="light"
+                    size="sm"
+                    leftSection={<IconAlertTriangle size={12} />}
+                  >
+                    {t("Expired")}
+                  </Badge>
+                </Tooltip>
+              )}
+              {soon && (
+                <Tooltip
+                  label={t("This key expires within 30 days")}
+                  withArrow
+                >
+                  <Badge
+                    color="orange"
+                    variant="light"
+                    size="sm"
+                    leftSection={<IconAlertTriangle size={12} />}
+                  >
+                    {t("Expiring soon")}
+                  </Badge>
+                </Tooltip>
+              )}
+            </Group>
+          ) : (
+            <Text size="sm" c="dimmed">
+              {t("Never")}
+            </Text>
+          )}
+        </Table.Td>
+        <Table.Td>
+          <Text size="sm" c="dimmed">
+            {renderLastUsed(key.lastUsedAt)}
+          </Text>
+        </Table.Td>
+        {isAdmin && (
+          <Table.Td>
+            <Text size="sm">
+              {key.creator?.name ?? key.creator?.email ?? t("Unknown")}
+            </Text>
+          </Table.Td>
+        )}
+        <Table.Td style={{ textAlign: "right" }}>
+          <Group gap={4} justify="flex-end" wrap="nowrap">
+            <Tooltip label={t("Copy API key")} withArrow>
+              <ActionIcon
+                variant="subtle"
+                aria-label={t("Copy {{name}}", { name: key.name })}
+                disabled={expired}
+                onClick={() => setRevealTarget(key)}
+              >
+                <IconCopy size={16} />
+              </ActionIcon>
+            </Tooltip>
+            <Tooltip label={t("Revoke")} withArrow>
+              <ActionIcon
+                variant="subtle"
+                color="red"
+                aria-label={t("Revoke {{name}}", { name: key.name })}
+                onClick={() => openRevokeModal(key)}
+              >
+                <IconTrash size={16} />
+              </ActionIcon>
+            </Tooltip>
+          </Group>
+        </Table.Td>
+      </Table.Tr>
+    );
+  });
+
+  return (
+    <>
+      <Group justify="space-between" mb="md">
+        <Text size="sm" c="dimmed">
+          {isAdmin
+            ? t("API keys across the workspace.")
+            : t("Your personal API keys.")}
+        </Text>
+        <Button
+          leftSection={<IconKey size={16} />}
+          onClick={() => setCreateOpened(true)}
+        >
+          {t("Create API key")}
+        </Button>
+      </Group>
+
+      {isError ? (
+        <Text c="red" size="sm">
+          {t("Failed to load API keys.")}
+        </Text>
+      ) : rows.length === 0 ? (
+        <Stack align="center" gap="xs" py="xl">
+          <IconKey size={32} opacity={0.4} />
+          <Text c="dimmed">{t("No API keys yet")}</Text>
+          <Button
+            variant="light"
+            leftSection={<IconKey size={16} />}
+            onClick={() => setCreateOpened(true)}
+          >
+            {t("Create API key")}
+          </Button>
+        </Stack>
+      ) : (
+        <Table.ScrollContainer minWidth={600}>
+          <Table verticalSpacing="sm" highlightOnHover>
+            <Table.Thead>
+              <Table.Tr>
+                <Table.Th>{t("Name")}</Table.Th>
+                <Table.Th>{t("Created")}</Table.Th>
+                <Table.Th>{t("Expires")}</Table.Th>
+                <Table.Th>{t("Last used")}</Table.Th>
+                {isAdmin && <Table.Th>{t("Author")}</Table.Th>}
+                <Table.Th />
+              </Table.Tr>
+            </Table.Thead>
+            <Table.Tbody>{rows}</Table.Tbody>
+          </Table>
+        </Table.ScrollContainer>
+      )}
+
+      <CreateApiKeyModal
+        opened={createOpened}
+        onClose={() => setCreateOpened(false)}
+        onSubmit={handleCreate}
+        loading={createMutation.isPending}
+      />
+
+      <RevealKeyModal
+        keyName={revealTarget?.name ?? null}
+        opened={revealTarget !== null}
+        onClose={() => setRevealTarget(null)}
+        onConfirm={handleCopy}
+        loading={revealMutation.isPending}
+      />
+    </>
+  );
+}

apps/client/src/features/api-key/components/create-api-key-modal.tsx

@@ -0,0 +1,104 @@
+import { Button, Group, Modal, Select, Stack, TextInput } from "@mantine/core";
+import { useForm } from "@mantine/form";
+import { useTranslation } from "react-i18next";
+import {
+  ApiKeyLifetime,
+  DEFAULT_LIFETIME,
+  lifetimeToExpiresAt,
+} from "@/features/api-key/utils";
+
+interface Props {
+  opened: boolean;
+  onClose: () => void;
+  // Resolves the create request, returning true on success. The parent owns the
+  // mutation (and the token it returns); this modal only collects the name +
+  // lifetime. On failure (false) the form state is kept so the user can retry.
+  onSubmit: (values: {
+    name: string;
+    expiresAt: string | null;
+  }) => Promise<boolean>;
+  loading?: boolean;
+}
+
+interface FormValues {
+  name: string;
+  lifetime: ApiKeyLifetime;
+}
+
+export function CreateApiKeyModal({
+  opened,
+  onClose,
+  onSubmit,
+  loading,
+}: Props) {
+  const { t } = useTranslation();
+
+  const form = useForm<FormValues>({
+    initialValues: {
+      name: "",
+      lifetime: DEFAULT_LIFETIME,
+    },
+    validate: {
+      name: (value) =>
+        value.trim().length === 0 ? t("Name is required") : null,
+    },
+  });
+
+  const lifetimeOptions: { value: ApiKeyLifetime; label: string }[] = [
+    { value: "30d", label: t("30 days") },
+    { value: "90d", label: t("90 days") },
+    { value: "1y", label: t("1 year") },
+    { value: "never", label: t("No expiration") },
+  ];
+
+  const handleSubmit = form.onSubmit(async (values) => {
+    const ok = await onSubmit({
+      name: values.name.trim(),
+      expiresAt: lifetimeToExpiresAt(values.lifetime),
+    });
+    // Reset only after a successful submit so a failed create keeps the form
+    // state (the parent surfaces the error via a notification).
+    if (ok) form.reset();
+  });
+
+  const handleClose = () => {
+    form.reset();
+    onClose();
+  };
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={handleClose}
+      title={t("Create API key")}
+      centered
+    >
+      <form onSubmit={handleSubmit}>
+        <Stack gap="sm">
+          <TextInput
+            label={t("Name")}
+            placeholder={t("e.g. CI deploy token")}
+            data-autofocus
+            withAsterisk
+            {...form.getInputProps("name")}
+          />
+          <Select
+            label={t("Expiration")}
+            data={lifetimeOptions}
+            allowDeselect={false}
+            checkIconPosition="right"
+            {...form.getInputProps("lifetime")}
+          />
+          <Group justify="flex-end" mt="xs">
+            <Button variant="default" onClick={handleClose} type="button">
+              {t("Cancel")}
+            </Button>
+            <Button type="submit" loading={loading}>
+              {t("Create")}
+            </Button>
+          </Group>
+        </Stack>
+      </form>
+    </Modal>
+  );
+}

apps/client/src/features/api-key/components/reveal-key-modal.tsx

@@ -0,0 +1,85 @@
+import { useState } from "react";
+import {
+  Button,
+  Group,
+  Modal,
+  PasswordInput,
+  Stack,
+  Text,
+} from "@mantine/core";
+import { useTranslation } from "react-i18next";
+
+interface Props {
+  // The key being copied (metadata only — never its token). `null` closes.
+  keyName: string | null;
+  opened: boolean;
+  onClose: () => void;
+  // Step-up: resolves true when the password was accepted, the token was copied
+  // to the clipboard and the modal should close; false to keep it open (wrong
+  // password) so the user can retry. The password is passed straight through and
+  // never persisted here.
+  onConfirm: (password: string) => Promise<boolean>;
+  loading?: boolean;
+}
+
+// Password step-up before a copyable key is re-minted + copied. This modal only
+// ever holds the PASSWORD (transient, cleared on close) — never the revealed
+// token, which the parent writes straight to the clipboard.
+export function RevealKeyModal({
+  keyName,
+  opened,
+  onClose,
+  onConfirm,
+  loading,
+}: Props) {
+  const { t } = useTranslation();
+  const [password, setPassword] = useState("");
+
+  const close = () => {
+    setPassword("");
+    onClose();
+  };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (password.length === 0) return;
+    const ok = await onConfirm(password);
+    if (ok) close();
+    // On failure keep the modal open; clear the field so a retry starts clean.
+    else setPassword("");
+  };
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={close}
+      title={t("Confirm your password")}
+      centered
+    >
+      <form onSubmit={handleSubmit}>
+        <Stack gap="sm">
+          <Text size="sm" c="dimmed">
+            {t(
+              'Enter your password to copy the API key "{{name}}" to your clipboard.',
+              { name: keyName ?? "" },
+            )}
+          </Text>
+          <PasswordInput
+            label={t("Password")}
+            data-autofocus
+            value={password}
+            onChange={(e) => setPassword(e.currentTarget.value)}
+          />
+          <Group justify="flex-end" mt="xs">
+            <Button variant="default" onClick={close} type="button">
+              {t("Cancel")}
+            </Button>
+            <Button type="submit" loading={loading} disabled={password.length === 0}>
+              {t("Copy to clipboard")}
+            </Button>
+          </Group>
+        </Stack>
+      </form>
+    </Modal>
+  );
+}

apps/client/src/features/api-key/queries/api-key-query.ts

@@ -0,0 +1,85 @@
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+  UseQueryResult,
+} from "@tanstack/react-query";
+import { notifications } from "@mantine/notifications";
+import { useTranslation } from "react-i18next";
+import {
+  createApiKey,
+  getApiKeys,
+  revealApiKey,
+  revokeApiKey,
+} from "@/features/api-key/services/api-key-service";
+import {
+  IApiKey,
+  ICreateApiKey,
+  ICreateApiKeyResponse,
+  IRevealApiKey,
+} from "@/features/api-key/types/api-key.types";
+
+export const API_KEYS_QUERY_KEY = ["api-keys"];
+
+export function useApiKeysQuery(): UseQueryResult<IApiKey[], Error> {
+  return useQuery({
+    queryKey: API_KEYS_QUERY_KEY,
+    queryFn: () => getApiKeys(),
+  });
+}
+
+/**
+ * Create mutation.
+ *
+ * SECURITY: the response contains the token. This hook deliberately does NOT
+ * stash it anywhere — the caller reads it from `mutateAsync`'s resolved value
+ * and immediately calls `mutation.reset()` to purge react-query's own copy (the
+ * create flow discards the token; it is re-obtainable later via the reveal/copy
+ * action). `gcTime: 0` is a second belt so nothing lingers in the mutation cache
+ * after the observer unmounts. The list is invalidated here (it carries no token).
+ */
+export function useCreateApiKeyMutation() {
+  const queryClient = useQueryClient();
+  return useMutation<ICreateApiKeyResponse, Error, ICreateApiKey>({
+    mutationFn: (data) => createApiKey(data),
+    gcTime: 0,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: API_KEYS_QUERY_KEY });
+    },
+  });
+}
+
+/**
+ * Reveal (copy) mutation.
+ *
+ * SECURITY (mirrors useCreateApiKeyMutation): the resolved value is the raw
+ * token. This hook deliberately stashes it NOWHERE — the caller reads it from
+ * `mutateAsync`, writes it straight to the clipboard, then calls
+ * `mutation.reset()` to purge react-query's own copy. `gcTime: 0` is the second
+ * belt so nothing lingers in the mutation cache after the observer unmounts.
+ * There is no `onSuccess` list invalidation: reveal does not change the list.
+ */
+export function useRevealApiKeyMutation() {
+  return useMutation<string, Error, IRevealApiKey>({
+    mutationFn: (data) => revealApiKey(data),
+    gcTime: 0,
+  });
+}
+
+export function useRevokeApiKeyMutation() {
+  const { t } = useTranslation();
+  const queryClient = useQueryClient();
+  return useMutation<void, Error, string>({
+    mutationFn: (id) => revokeApiKey(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: API_KEYS_QUERY_KEY });
+      notifications.show({ message: t("API key revoked") });
+    },
+    onError: () => {
+      notifications.show({
+        message: t("Failed to revoke API key"),
+        color: "red",
+      });
+    },
+  });
+}

apps/client/src/features/api-key/services/api-key-service.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock the api-client (axios instance). vi.mock replaces the whole module, so
+// the real response interceptor — which returns `response.data`, i.e. the
+// server envelope { data, success, status } — is bypassed. Our mocked post/get
+// therefore resolve to that post-interceptor envelope shape directly, and the
+// service under test reads `.data` off it to unwrap the inner payload. This is
+// the one bug-prone line the component tests (which fully mock the service)
+// never exercise.
+const { post, get } = vi.hoisted(() => ({ post: vi.fn(), get: vi.fn() }));
+vi.mock("@/lib/api-client", () => ({
+  default: { post, get },
+}));
+
+import {
+  createApiKey,
+  getApiKeys,
+  revealApiKey,
+} from "@/features/api-key/services/api-key-service";
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("api-key-service response-contract unwrap", () => {
+  it("createApiKey unwraps the envelope to { token, apiKey }", async () => {
+    const payload = {
+      token: "gm_secret-abc",
+      apiKey: {
+        id: "key-1",
+        name: "CI token",
+        expiresAt: "2027-07-11T12:00:00.000Z",
+        createdAt: "2026-07-11T12:00:00.000Z",
+      },
+    };
+    // The server envelope as the interceptor hands it to the service.
+    post.mockResolvedValue({ data: payload, success: true, status: 200 });
+
+    const result = await createApiKey({
+      name: "CI token",
+      expiresAt: "2027-07-11T12:00:00.000Z",
+    });
+
+    // The inner payload only — not the { data, success, status } wrapper.
+    expect(result).toEqual(payload);
+    expect(result.token).toBe("gm_secret-abc");
+    expect(result.apiKey).toEqual(payload.apiKey);
+    expect(post).toHaveBeenCalledWith("/api-keys/create", {
+      name: "CI token",
+      expiresAt: "2027-07-11T12:00:00.000Z",
+    });
+  });
+
+  it("getApiKeys unwraps the envelope to the array of rows", async () => {
+    const rows = [
+      {
+        id: "key-1",
+        name: "CI token",
+        expiresAt: null,
+        lastUsedAt: null,
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+      {
+        id: "key-2",
+        name: "Deploy token",
+        expiresAt: "2027-01-01T00:00:00.000Z",
+        lastUsedAt: null,
+        createdAt: "2026-02-01T00:00:00.000Z",
+      },
+    ];
+    post.mockResolvedValue({ data: rows, success: true, status: 200 });
+
+    const result = await getApiKeys();
+
+    expect(result).toEqual(rows);
+    expect(result).toHaveLength(2);
+    expect(post).toHaveBeenCalledWith("/api-keys/list");
+  });
+
+  it("revealApiKey unwraps the envelope to the bare token string", async () => {
+    const SECRET = "gm_revealed-token";
+    post.mockResolvedValue({
+      data: { token: SECRET },
+      success: true,
+      status: 200,
+    });
+
+    const result = await revealApiKey({ id: "key-1", password: "pw" });
+
+    // The service returns ONLY the token string (not the { token } wrapper), so
+    // the caller can copy it straight to the clipboard.
+    expect(result).toBe(SECRET);
+    expect(post).toHaveBeenCalledWith("/api-keys/reveal", {
+      id: "key-1",
+      password: "pw",
+    });
+  });
+});

apps/client/src/features/api-key/services/api-key-service.ts

@@ -0,0 +1,42 @@
+import api from "@/lib/api-client";
+import {
+  IApiKey,
+  ICreateApiKey,
+  ICreateApiKeyResponse,
+  IRevealApiKey,
+} from "@/features/api-key/types/api-key.types";
+
+// Mint a new key. The response carries the token, but the create flow now
+// DISCARDS it (the user copies the key later via the per-row reveal action, so
+// there is no show-once modal) — the caller must never cache or persist it. See
+// queries/api-key-query.ts (gcTime: 0 + query invalidation) and
+// components/api-keys-manager.tsx `handleCreate` (createMutation.reset() right
+// after the mint) for the reset()-after-read discipline the reveal path mirrors.
+export async function createApiKey(
+  data: ICreateApiKey,
+): Promise<ICreateApiKeyResponse> {
+  const res = await api.post<ICreateApiKeyResponse>("/api-keys/create", data);
+  return res.data as ICreateApiKeyResponse;
+}
+
+// List the caller's keys (or, for an admin, every key in the workspace with
+// creator attribution). Never returns token material.
+export async function getApiKeys(): Promise<IApiKey[]> {
+  const res = await api.post<IApiKey[]>("/api-keys/list");
+  return res.data as IApiKey[];
+}
+
+// Revocation is server-side immediate; the caller drops the row on success.
+export async function revokeApiKey(id: string): Promise<void> {
+  await api.post("/api-keys/revoke", { id });
+}
+
+// Reveal (re-mint) an existing key's token under a password step-up. Returns the
+// bare token string — the SECURITY contract (mirrors create): the caller must
+// write it straight to the clipboard and never stash it in state, the query
+// cache or localStorage. See useRevealApiKeyMutation (gcTime: 0 + reset-after-
+// read) and api-keys-manager.tsx `handleCopy`.
+export async function revealApiKey(data: IRevealApiKey): Promise<string> {
+  const res = await api.post<{ token: string }>("/api-keys/reveal", data);
+  return (res.data as { token: string }).token;
+}

apps/client/src/features/api-key/types/api-key.types.ts

@@ -0,0 +1,59 @@
+// Compact creator attribution embedded in the admin (workspace-wide) list. A
+// normal member's list only ever contains their own keys, so the field is
+// present but redundant; the author column is only rendered for admins.
+export interface IApiKeyCreator {
+  id: string;
+  name: string;
+  email: string;
+  avatarUrl: string | null;
+}
+
+// A single api-key row as returned by `POST /api/api-keys/list`. Note: the list
+// NEVER carries token material — only metadata.
+export interface IApiKey {
+  id: string;
+  name: string;
+  // ISO string, or null for an unlimited ("never expires") key.
+  expiresAt: string | null;
+  // ISO string, or null if the key was never used. Throttled to ~1h server-side
+  // (#501), so the UI must not promise sub-hour precision.
+  lastUsedAt: string | null;
+  createdAt: string;
+  creator?: IApiKeyCreator | null;
+}
+
+// Payload for `POST /api/api-keys/create`. `expiresAt`: an ISO date string for a
+// bounded lifetime, or null for an unlimited key. (undefined would let the
+// server apply its 1-year default, but the form always sends an explicit value.)
+export interface ICreateApiKey {
+  name: string;
+  expiresAt: string | null;
+}
+
+// The metadata half of the create response. The token itself is carried
+// separately (see ICreateApiKeyResponse); it is re-obtainable later by its owner
+// via a deterministic re-mint under a step-up (POST /api-keys/reveal).
+export interface ICreatedApiKey {
+  id: string;
+  name: string;
+  expiresAt: string | null;
+  createdAt: string;
+}
+
+// Response of `POST /api/api-keys/create`. `token` is returned on create; it is
+// ALSO retrievable later via reveal (deterministic re-mint under a step-up), so
+// it is no longer "show once". It must never be cached, persisted or logged —
+// the create flow discards it (the user copies via the per-row Copy action).
+export interface ICreateApiKeyResponse {
+  token: string;
+  apiKey: ICreatedApiKey;
+}
+
+// Payload for `POST /api/api-keys/reveal`: the key id + the caller's current
+// password (step-up). The response is `{ token }` — a re-minted, byte-identical
+// copy of the key's token, which must be written straight to the clipboard and
+// never held in state, cache or storage.
+export interface IRevealApiKey {
+  id: string;
+  password: string;
+}

apps/client/src/features/api-key/utils.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from "vitest";
+import {
+  DEFAULT_LIFETIME,
+  EXPIRY_WARNING_DAYS,
+  isExpired,
+  isExpiringSoon,
+  lastUsedBucket,
+  lifetimeToExpiresAt,
+} from "./utils";
+
+const NOW = new Date("2026-07-11T12:00:00.000Z");
+const daysFromNow = (n: number) =>
+  new Date(NOW.getTime() + n * 24 * 60 * 60 * 1000).toISOString();
+
+describe("lifetimeToExpiresAt", () => {
+  it("default lifetime is 1 year (acceptance #7)", () => {
+    expect(DEFAULT_LIFETIME).toBe("1y");
+    const iso = lifetimeToExpiresAt("1y", NOW);
+    expect(iso).toBe("2027-07-11T12:00:00.000Z");
+  });
+
+  it('"never" sends null (acceptance #7)', () => {
+    expect(lifetimeToExpiresAt("never", NOW)).toBeNull();
+  });
+
+  it("30d / 90d map to the exact future instant", () => {
+    expect(lifetimeToExpiresAt("30d", NOW)).toBe(daysFromNow(30));
+    expect(lifetimeToExpiresAt("90d", NOW)).toBe(daysFromNow(90));
+  });
+});
+
+describe("isExpiringSoon (acceptance #3 highlight)", () => {
+  it("an unlimited key is never 'soon'", () => {
+    expect(isExpiringSoon(null, NOW)).toBe(false);
+  });
+
+  it("highlights a key expiring within the 30-day window", () => {
+    expect(isExpiringSoon(daysFromNow(EXPIRY_WARNING_DAYS - 1), NOW)).toBe(true);
+    expect(isExpiringSoon(daysFromNow(10), NOW)).toBe(true);
+  });
+
+  it("does not highlight a key well outside the window", () => {
+    expect(isExpiringSoon(daysFromNow(EXPIRY_WARNING_DAYS + 1), NOW)).toBe(
+      false,
+    );
+    expect(isExpiringSoon(daysFromNow(200), NOW)).toBe(false);
+  });
+
+  it("an already-expired key is highlighted", () => {
+    expect(isExpiringSoon(daysFromNow(-3), NOW)).toBe(true);
+  });
+});
+
+describe("isExpired (past vs future expiry)", () => {
+  it("an unlimited key is never expired", () => {
+    expect(isExpired(null, NOW)).toBe(false);
+  });
+
+  it("a past expiry is expired", () => {
+    expect(isExpired(daysFromNow(-3), NOW)).toBe(true);
+    expect(isExpired(daysFromNow(-1), NOW)).toBe(true);
+  });
+
+  it("a future expiry is not expired (even within the warning window)", () => {
+    expect(isExpired(daysFromNow(1), NOW)).toBe(false);
+    expect(isExpired(daysFromNow(EXPIRY_WARNING_DAYS - 1), NOW)).toBe(false);
+    expect(isExpired(daysFromNow(200), NOW)).toBe(false);
+  });
+
+  it("an expiry exactly at 'now' counts as expired (boundary is inclusive)", () => {
+    expect(isExpired(NOW.toISOString(), NOW)).toBe(true);
+  });
+
+  it("is mutually distinguishable from isExpiringSoon: expired vs soon-but-future", () => {
+    // A key 3 days in the past: expired, and (by design) also matches
+    // isExpiringSoon — the UI resolves this by checking isExpired first.
+    expect(isExpired(daysFromNow(-3), NOW)).toBe(true);
+    // A key 10 days in the future: NOT expired, but expiring soon.
+    expect(isExpired(daysFromNow(10), NOW)).toBe(false);
+    expect(isExpiringSoon(daysFromNow(10), NOW)).toBe(true);
+  });
+});
+
+describe("lastUsedBucket (within-the-last-hour semantics)", () => {
+  const minutesAgo = (n: number) =>
+    new Date(NOW.getTime() - n * 60 * 1000).toISOString();
+
+  it("null last-used is 'never'", () => {
+    expect(lastUsedBucket(null, NOW)).toBe("never");
+  });
+
+  it("under an hour is 'recent' (no sub-hour precision promised)", () => {
+    expect(lastUsedBucket(minutesAgo(5), NOW)).toBe("recent");
+    expect(lastUsedBucket(minutesAgo(59), NOW)).toBe("recent");
+  });
+
+  it("over an hour is 'stale'", () => {
+    expect(lastUsedBucket(minutesAgo(90), NOW)).toBe("stale");
+  });
+});

apps/client/src/features/api-key/utils.ts

@@ -0,0 +1,76 @@
+import { addDays, addYears, differenceInMinutes } from "date-fns";
+
+// The single early-warning window (#501/#506): keys whose expiry is closer than
+// this are visually highlighted in the list. Also used to classify a key as
+// already-expired (a negative "days until" is < 30 too).
+export const EXPIRY_WARNING_DAYS = 30;
+
+// last_used_at is throttled to ~1h server-side, so anything under an hour is
+// shown as the coarse "within the last hour" rather than a false-precise
+// "5 minutes ago".
+export const LAST_USED_THROTTLE_MINUTES = 60;
+
+export type ApiKeyLifetime = "30d" | "90d" | "1y" | "never";
+
+export const DEFAULT_LIFETIME: ApiKeyLifetime = "1y";
+
+// Maps a lifetime choice to the `expiresAt` payload sent to the server: an ISO
+// string for a bounded lifetime, or null for an explicit unlimited key.
+export function lifetimeToExpiresAt(
+  lifetime: ApiKeyLifetime,
+  now: Date = new Date(),
+): string | null {
+  switch (lifetime) {
+    case "30d":
+      return addDays(now, 30).toISOString();
+    case "90d":
+      return addDays(now, 90).toISOString();
+    case "1y":
+      return addYears(now, 1).toISOString();
+    case "never":
+      return null;
+  }
+}
+
+// True when a bounded key's expiry is already in the past (or exactly now). An
+// unlimited key (null) is never expired. This is distinct from "expiring soon":
+// the two states are mutually exclusive at the call site (see api-keys-manager),
+// so an already-expired key is labelled "Expired", not "Expiring soon".
+export function isExpired(
+  expiresAt: string | null,
+  now: Date = new Date(),
+): boolean {
+  if (!expiresAt) return false;
+  const expiry = new Date(expiresAt).getTime();
+  if (Number.isNaN(expiry)) return false;
+  return expiry <= now.getTime();
+}
+
+// True when a bounded key expires within the warning window (or is already
+// expired). An unlimited key (null) is never "expiring soon". Callers that need
+// to distinguish an already-past expiry should check isExpired() first, as this
+// predicate deliberately also covers the already-expired case.
+export function isExpiringSoon(
+  expiresAt: string | null,
+  now: Date = new Date(),
+): boolean {
+  if (!expiresAt) return false;
+  const expiry = new Date(expiresAt).getTime();
+  if (Number.isNaN(expiry)) return false;
+  const msLeft = expiry - now.getTime();
+  return msLeft < EXPIRY_WARNING_DAYS * 24 * 60 * 60 * 1000;
+}
+
+// Classifies last-used recency so the caller can pick the honest label without
+// promising sub-hour precision. Returns "never", "recent" (< 1h) or "stale".
+export function lastUsedBucket(
+  lastUsedAt: string | null,
+  now: Date = new Date(),
+): "never" | "recent" | "stale" {
+  if (!lastUsedAt) return "never";
+  const used = new Date(lastUsedAt);
+  if (Number.isNaN(used.getTime())) return "never";
+  return differenceInMinutes(now, used) < LAST_USED_THROTTLE_MINUTES
+    ? "recent"
+    : "stale";
+}

apps/client/src/features/comment/components/agent-edit-card.test.tsx

@@ -0,0 +1,284 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { createInstance } from "i18next";
+import { initReactI18next, I18nextProvider } from "react-i18next";
+import { IComment } from "@/features/comment/types/comment.types";
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+// The suggestion mutations reach react-query/network — stub them so the card
+// renders in isolation. We assert the Apply/Dismiss gating and that the click
+// hands the {commentId, pageId} pair to the existing mutation unchanged.
+const applyMutateAsync = vi.fn();
+const dismissMutateAsync = vi.fn();
+vi.mock("@/features/comment/queries/comment-query", () => ({
+  useApplySuggestionMutation: () => ({
+    mutateAsync: applyMutateAsync,
+    isPending: false,
+  }),
+  useDismissSuggestionMutation: () => ({
+    mutateAsync: dismissMutateAsync,
+    isPending: false,
+  }),
+}));
+
+// CommentContentView -> mention-view -> page-query/share-query pull in the app
+// entry (createRoot) as a side effect; stub the queries so the card renders in
+// isolation.
+vi.mock("@/features/page/queries/page-query.ts", () => ({
+  usePageQuery: () => ({ data: undefined, isLoading: false, isError: false }),
+}));
+vi.mock("@/features/share/queries/share-query.ts", () => ({
+  useSharePageQuery: () => ({ data: undefined }),
+}));
+// space-query.ts -> main.tsx (createRoot) is a module side effect reached via the
+// mention view; stub it so importing the card is side-effect free.
+vi.mock("@/features/space/queries/space-query.ts", () => ({
+  useSpaceQuery: () => ({ data: undefined }),
+  useGetSpaceBySlugQuery: () => ({ data: undefined }),
+}));
+
+import AgentEditCard, { RunHeader } from "./agent-edit-card";
+
+const body = (text: string) =>
+  JSON.stringify({
+    type: "doc",
+    content: [{ type: "paragraph", content: [{ type: "text", text }] }],
+  });
+
+const edit = (over?: Partial<IComment>): IComment =>
+  ({
+    id: "c-1",
+    content: body("[Существенно] tighten the wording"),
+    creatorId: "user-1",
+    pageId: "page-1",
+    workspaceId: "ws-1",
+    createdAt: new Date(),
+    createdSource: "agent",
+    aiChatId: "chat-1",
+    agent: { name: "Corrector", emoji: "✏️", avatarUrl: null },
+    launcher: { name: "Alice", avatarUrl: null },
+    creator: { id: "user-1", name: "Corrector", avatarUrl: null } as any,
+    selection: "old wording here",
+    suggestedText: "new wording here",
+    ...over,
+  }) as IComment;
+
+function renderCard(
+  comment: IComment,
+  canEdit = true,
+  canComment = true,
+  userSpaceRole?: string,
+) {
+  return render(
+    <MantineProvider>
+      <AgentEditCard
+        comment={comment}
+        canComment={canComment}
+        canEdit={canEdit}
+        userSpaceRole={userSpaceRole}
+      />
+    </MantineProvider>,
+  );
+}
+
+describe("AgentEditCard — suggested edit diff + Apply (#315)", () => {
+  it("renders the было→стало diff and an Apply button when canEdit, not applied/resolved", () => {
+    const { container } = renderCard(edit(), true);
+    // Both diff lines are present (old struck-through, new added).
+    expect(container.textContent).toContain("old wording here");
+    expect(container.textContent).toContain("new wording here");
+    // Diff line signs (aria-hidden) present for a replacement.
+    expect(container.textContent).toContain("−");
+    expect(container.textContent).toContain("+");
+    expect(screen.getByRole("button", { name: "Apply" })).toBeDefined();
+  });
+
+  it("hides Apply when canEdit is false (still shows the diff)", () => {
+    const { container } = renderCard(edit(), false);
+    expect(container.textContent).toContain("new wording here");
+    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
+  });
+
+  it("hides Apply once the thread is resolved", () => {
+    renderCard(edit({ resolvedAt: new Date() }), true);
+    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
+  });
+
+  it("hides Apply once suggestionAppliedAt is set", () => {
+    renderCard(edit({ suggestionAppliedAt: new Date() }), true);
+    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
+  });
+
+  it("shows the Applied badge for an applied suggestion, not a pending one (F1)", () => {
+    // Pending: no Applied badge.
+    const { unmount } = renderCard(edit(), true);
+    expect(screen.queryByText("Applied")).toBeNull();
+    unmount();
+    // Applied (kept alive by replies -> resolved, #329): the badge is restored.
+    renderCard(edit({ suggestionAppliedAt: new Date() }), true);
+    expect(screen.getByText("Applied")).toBeDefined();
+    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
+    expect(screen.queryByRole("button", { name: "Dismiss" })).toBeNull();
+  });
+
+  it("calls the apply mutation with {commentId, pageId} on click", () => {
+    applyMutateAsync.mockClear();
+    renderCard(edit(), true);
+    fireEvent.click(screen.getByRole("button", { name: "Apply" }));
+    expect(applyMutateAsync).toHaveBeenCalledWith({
+      commentId: "c-1",
+      pageId: "page-1",
+    });
+  });
+
+  it("a pure insertion (empty selection) hides the removed line", () => {
+    const { container } = renderCard(
+      edit({ selection: "", suggestedText: "added text" }),
+      true,
+    );
+    // No "−" del sign — nothing was removed.
+    expect(container.textContent).not.toContain("−");
+    expect(container.textContent).toContain("+");
+  });
+
+  it("a pure deletion (empty suggestedText) hides the added line", () => {
+    const { container } = renderCard(
+      edit({ selection: "removed text", suggestedText: "" }),
+      true,
+    );
+    expect(container.textContent).not.toContain("+");
+    expect(container.textContent).toContain("−");
+  });
+});
+
+describe("AgentEditCard — Dismiss gate (#329/#338)", () => {
+  it("shows Dismiss alongside Apply for an admin who can edit/comment", () => {
+    renderCard(edit(), true, true, "admin");
+    expect(screen.getByRole("button", { name: "Apply" })).toBeDefined();
+    expect(screen.getByRole("button", { name: "Dismiss" })).toBeDefined();
+  });
+
+  it("shows Dismiss but NOT Apply for an admin commenter who cannot edit", () => {
+    renderCard(edit(), false, true, "admin");
+    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
+    expect(screen.getByRole("button", { name: "Dismiss" })).toBeDefined();
+  });
+
+  it("hides Dismiss for a non-owner non-admin (mirrors server 403, #338 F5)", () => {
+    renderCard(edit(), false, true, "member");
+    expect(screen.queryByRole("button", { name: "Dismiss" })).toBeNull();
+  });
+
+  it("hides Dismiss when the viewer cannot comment", () => {
+    renderCard(edit(), false, false, "admin");
+    expect(screen.queryByRole("button", { name: "Dismiss" })).toBeNull();
+  });
+
+  it("calls the dismiss mutation with {commentId, pageId} on click", () => {
+    dismissMutateAsync.mockClear();
+    renderCard(edit(), true, true, "admin");
+    fireEvent.click(screen.getByRole("button", { name: "Dismiss" }));
+    expect(dismissMutateAsync).toHaveBeenCalledWith({
+      commentId: "c-1",
+      pageId: "page-1",
+    });
+  });
+});
+
+describe("AgentEditCard — provenance", () => {
+  it("renders the agent avatar stack (provenance) for the edit author (#300)", () => {
+    renderCard(edit(), true);
+    // The agent role name is shown by the provenance stack.
+    expect(screen.getAllByText("Corrector").length).toBeGreaterThan(0);
+  });
+
+  // The owner-or-admin gate uses the currentUser atom; clear localStorage so a
+  // previous test's seed never leaks into the non-owner assertions above.
+  beforeEach(() => localStorage.clear());
+  afterEach(() => localStorage.clear());
+});
+
+// The RunHeader's "N edits · M major" is built with interpolated t() keys; the
+// default (uninitialized) react-i18next t returns the key verbatim WITHOUT
+// interpolating, so a numeric assertion needs a real, initialised i18n instance.
+// This isolated instance carries just the two count keys with escapeValue off so
+// "{{count}}" is substituted and the rendered numbers are assertable.
+const headerI18n = createInstance();
+headerI18n.use(initReactI18next).init({
+  lng: "en",
+  fallbackLng: "en",
+  resources: {
+    en: {
+      translation: {
+        "{{count}} edits": "{{count}} edits",
+        "{{count}} major": "{{count}} major",
+      },
+    },
+  },
+  interpolation: { escapeValue: false },
+});
+
+const runComment = (id: string, tag: string): IComment =>
+  edit({
+    id,
+    content: body(`${tag} some rationale`),
+  });
+
+function renderRunHeader(comments: IComment[]) {
+  return render(
+    <I18nextProvider i18n={headerI18n}>
+      <MantineProvider>
+        <RunHeader comments={comments} />
+      </MantineProvider>
+    </I18nextProvider>,
+  );
+}
+
+describe("RunHeader — agent-run series header (F3)", () => {
+  // 5 edits: 2 critical + 1 major + 1 minor + 1 unknown(verdict) => 3 "major".
+  const series = () => [
+    runComment("e1", "[Критично]"),
+    runComment("e2", "[Критично]"),
+    runComment("e3", "[Существенно]"),
+    runComment("e4", "[Незначительно]"),
+    runComment("e5", "[Неверно]"),
+  ];
+
+  it("shows the total edit count", () => {
+    renderRunHeader(series());
+    expect(screen.getByText(/5 edits/)).toBeDefined();
+  });
+
+  it("counts ONLY major+critical as major (not minor/unknown)", () => {
+    renderRunHeader(series());
+    // 2 critical + 1 major = 3; minor and the [Неверно] verdict are excluded.
+    expect(screen.getByText(/3 major/)).toBeDefined();
+    // Non-vacuous: the wrong tally (counting all 5, or 4) must NOT appear.
+    expect(screen.queryByText(/5 major/)).toBeNull();
+    expect(screen.queryByText(/4 major/)).toBeNull();
+  });
+
+  it("omits the major segment entirely when there are no significant edits", () => {
+    renderRunHeader([
+      runComment("e1", "[Незначительно]"),
+      runComment("e2", "[Неверно]"),
+    ]);
+    expect(screen.getByText(/2 edits/)).toBeDefined();
+    expect(screen.queryByText(/major/)).toBeNull();
+  });
+
+  it("renders the provenance line (agent role name)", () => {
+    renderRunHeader(series());
+    expect(screen.getAllByText("Corrector").length).toBeGreaterThan(0);
+  });
+
+  it("renders NO 'Accept all' control (rejected by product)", () => {
+    renderRunHeader(series());
+    expect(screen.queryByText(/accept all/i)).toBeNull();
+    expect(
+      screen.queryByRole("button", { name: /accept all/i }),
+    ).toBeNull();
+  });
+});

apps/client/src/features/comment/components/agent-edit-card.tsx

@@ -0,0 +1,418 @@
+import React, { useMemo } from "react";
+import {
+  Badge,
+  Box,
+  Button,
+  Group,
+  Stack,
+  Text,
+  useMantineColorScheme,
+  useMantineTheme,
+} from "@mantine/core";
+import { useAtom } from "jotai";
+import { useTranslation } from "react-i18next";
+import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
+import CommentContentView from "@/features/comment/components/comment-content-view";
+import { IComment } from "@/features/comment/types/comment.types";
+import {
+  canShowApply,
+  canShowDismiss,
+  computeSuggestionDiff,
+  Segment,
+} from "@/features/comment/utils/suggestion";
+import { commentContentToText } from "@/features/comment/utils/comment-content-to-text";
+import {
+  isSignificant,
+  parseSeverity,
+  Severity,
+} from "@/features/comment/utils/severity";
+import {
+  useApplySuggestionMutation,
+  useDismissSuggestionMutation,
+} from "@/features/comment/queries/comment-query";
+import { currentUserAtom } from "@/features/user/atoms/current-user-atom.ts";
+import { useTimeAgo } from "@/hooks/use-time-ago";
+
+// Scroll the document to this comment's inline mark and flash it — the same
+// anchor navigation the old panel used (handleCommentClick). Used both by a card
+// click and by an explicit "Go to text" affordance.
+function scrollToCommentMark(commentId: string) {
+  const el = document.querySelector(
+    `.comment-mark[data-comment-id="${commentId}"]`,
+  );
+  if (el) {
+    el.scrollIntoView({ behavior: "smooth", block: "center" });
+    el.classList.add("comment-highlight");
+    setTimeout(() => el.classList.remove("comment-highlight"), 3000);
+  }
+}
+
+// Make otherwise-invisible edited whitespace legible inside a highlighted diff
+// fragment (a pure-space insertion/deletion would otherwise look like nothing
+// changed).
+function visibleWhitespace(s: string): string {
+  return s.replace(/ /g, "␣").replace(/\t/g, "⇥");
+}
+
+// One line of the intraline diff. `kind==="del"` is the old ("было") line drawn
+// red with a strike-through; `kind==="ins"` is the new ("стало") line drawn
+// green. Only the `changed` segments carry the emphasised mark background — the
+// common segments read as plain context (git/GitHub-style, #331).
+function DiffLine({
+  segments,
+  kind,
+}: {
+  segments: Segment[];
+  kind: "del" | "ins";
+}) {
+  const theme = useMantineTheme();
+  const { colorScheme } = useMantineColorScheme();
+  const dark = colorScheme === "dark";
+  const isDel = kind === "del";
+  const sign = isDel ? "−" : "+";
+  const signColor = isDel
+    ? theme.colors.red[dark ? 5 : 6]
+    : theme.colors.green[dark ? 5 : 6];
+  const baseColor = isDel
+    ? dark
+      ? theme.colors.gray[5]
+      : theme.colors.gray[6]
+    : dark
+      ? theme.colors.gray[1]
+      : theme.colors.dark[9];
+  const markBg = isDel
+    ? dark
+      ? "rgba(224,49,49,.22)"
+      : "#ffe3e3"
+    : dark
+      ? "rgba(47,158,68,.22)"
+      : "#d3f9d8";
+  const markFg = isDel
+    ? dark
+      ? theme.colors.red[3]
+      : theme.colors.red[8]
+    : dark
+      ? theme.colors.green[3]
+      : theme.colors.green[9];
+
+  return (
+    <Group gap={7} wrap="nowrap" align="flex-start">
+      <Text
+        ff="monospace"
+        fw={600}
+        fz={12}
+        c={signColor}
+        w={11}
+        ta="center"
+        aria-hidden
+        style={{ flex: "none", lineHeight: 1.5 }}
+      >
+        {sign}
+      </Text>
+      <Text fz={13.5} c={baseColor} style={{ lineHeight: 1.45 }}>
+        {segments.map((seg, i) =>
+          seg.changed ? (
+            <Box
+              key={i}
+              component="mark"
+              px={3}
+              fw={600}
+              style={{
+                background: markBg,
+                color: markFg,
+                borderRadius: 3,
+                textDecoration: isDel ? "line-through" : "none",
+              }}
+            >
+              {visibleWhitespace(seg.text)}
+            </Box>
+          ) : (
+            <Box
+              key={i}
+              component="span"
+              style={{ textDecoration: isDel ? "line-through" : "none" }}
+            >
+              {seg.text}
+            </Box>
+          ),
+        )}
+      </Text>
+    </Group>
+  );
+}
+
+// The "было → стало" block. A pure insertion (empty `before`) hides the old
+// line; a pure deletion (empty `after`) hides the new line.
+function DiffBlock({ before, after }: { before: Segment[]; after: Segment[] }) {
+  const pureInsert = before.length === 0;
+  const pureDelete = after.length === 0;
+  return (
+    <Stack gap={1}>
+      {!pureInsert && <DiffLine segments={before} kind="del" />}
+      {!pureDelete && <DiffLine segments={after} kind="ins" />}
+    </Stack>
+  );
+}
+
+const SEV_DOT: Record<Severity, { color: string; shade: number }> = {
+  critical: { color: "red", shade: 6 },
+  major: { color: "orange", shade: 6 },
+  minor: { color: "gray", shade: 5 },
+  // A neutral, deliberately faint dot — NOT the minor grey — so an untagged or
+  // verdict-only edit never reads as a graded severity.
+  unknown: { color: "gray", shade: 3 },
+};
+
+function SeverityDot({ severity }: { severity: Severity }) {
+  return (
+    <Box
+      w={8}
+      h={8}
+      aria-hidden
+      style={(t) => ({
+        flex: "none",
+        borderRadius: "50%",
+        background: t.colors[SEV_DOT[severity].color][SEV_DOT[severity].shade],
+      })}
+    />
+  );
+}
+
+interface AgentEditCardProps {
+  comment: IComment;
+  canComment: boolean;
+  canEdit?: boolean;
+  userSpaceRole?: string;
+  // Whether to render the per-card agent avatar + timestamp. A card inside a
+  // collapsed run omits it (the RunHeader carries the one provenance line);
+  // a standalone card shows it (#300 provenance must be visible on the card).
+  showProvenance?: boolean;
+}
+
+// Type A — the diff-first agent suggested-edit card. It carries NO TipTap editor
+// (a perf win vs. the old row, #340); the body renders through the static
+// CommentContentView. Apply/Dismiss reuse the existing mutations and gates
+// verbatim — the reskin changes presentation only, not the 409/404/400 toast
+// semantics or the authz gating.
+function AgentEditCard({
+  comment,
+  canComment,
+  canEdit,
+  userSpaceRole,
+  showProvenance = true,
+}: AgentEditCardProps) {
+  const { t } = useTranslation();
+  const [currentUser] = useAtom(currentUserAtom);
+  const applySuggestionMutation = useApplySuggestionMutation();
+  const dismissSuggestionMutation = useDismissSuggestionMutation();
+  const createdAtAgo = useTimeAgo(comment.createdAt);
+
+  const diff = useMemo(
+    () =>
+      computeSuggestionDiff(comment.selection ?? "", comment.suggestedText ?? ""),
+    [comment.selection, comment.suggestedText],
+  );
+
+  const severity = useMemo(
+    () => parseSeverity(commentContentToText(comment.content)),
+    [comment.content],
+  );
+
+  // Owner-or-space-admin gate (#338), mirrored from the old row so we never
+  // render a Dismiss the server would 403.
+  const isOwnerOrAdmin =
+    currentUser?.user?.id === comment.creatorId || userSpaceRole === "admin";
+
+  const isApplied = comment.suggestionAppliedAt != null;
+  const showApply = canShowApply(comment, canEdit);
+  const showDismiss = canShowDismiss(comment, canComment, isOwnerOrAdmin);
+  const pending =
+    applySuggestionMutation.isPending || dismissSuggestionMutation.isPending;
+
+  const handleApply = async () => {
+    try {
+      await applySuggestionMutation.mutateAsync({
+        commentId: comment.id,
+        pageId: comment.pageId,
+      });
+    } catch (error) {
+      // Errors (incl. 409 "text changed") surface via the mutation's onError.
+      console.error("Failed to apply suggestion:", error);
+    }
+  };
+
+  const handleDismiss = async () => {
+    try {
+      await dismissSuggestionMutation.mutateAsync({
+        commentId: comment.id,
+        pageId: comment.pageId,
+      });
+    } catch (error) {
+      // Idempotent 404 is reconciled to success in the mutation's onError.
+      console.error("Failed to dismiss suggestion:", error);
+    }
+  };
+
+  const sevLabel =
+    severity === "critical"
+      ? t("Critical")
+      : severity === "major"
+        ? t("Major")
+        : null;
+
+  return (
+    <Box
+      p="10px 12px"
+      role="button"
+      tabIndex={0}
+      aria-label={t("Jump to comment selection")}
+      onClick={() => scrollToCommentMark(comment.id)}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          scrollToCommentMark(comment.id);
+        }
+      }}
+      style={{ cursor: "pointer" }}
+    >
+      <Stack gap={8}>
+        {showProvenance && comment.agent && (
+          <Group
+            gap={8}
+            wrap="nowrap"
+            justify="space-between"
+            onClick={(e) => e.stopPropagation()}
+          >
+            <AgentAvatarStack
+              agent={comment.agent}
+              launcher={comment.launcher}
+              aiChatId={comment.aiChatId}
+            />
+            <Text size="xs" c="dimmed" style={{ flex: "none" }}>
+              {createdAtAgo}
+            </Text>
+          </Group>
+        )}
+
+        <DiffBlock before={diff.old} after={diff.new} />
+
+        {/* Agent rationale — rendered through the static ProseMirror view, not
+            restructured into a flat string. */}
+        <Box fz="xs" c="dimmed">
+          <CommentContentView content={comment.content} />
+        </Box>
+
+        <Group gap={8} wrap="nowrap" onClick={(e) => e.stopPropagation()}>
+          <SeverityDot severity={severity} />
+          {sevLabel && (
+            <Text
+              fz={10}
+              fw={600}
+              tt="uppercase"
+              c="dimmed"
+              style={{ letterSpacing: ".06em", flex: 1 }}
+            >
+              {sevLabel}
+            </Text>
+          )}
+          <Box style={{ flex: 1 }} />
+          {/* Applied state (#315): a suggestion that was applied but kept alive by
+              its replies (so #329 resolved instead of hard-deleting it) still
+              shows it was applied — the badge the pre-redesign card carried. A
+              childless applied suggestion is gone from the list entirely, so this
+              only renders in the Resolved tab. */}
+          {isApplied && (
+            <Badge
+              size="sm"
+              color="green"
+              variant="light"
+              aria-label={t("Applied")}
+            >
+              {t("Applied")}
+            </Badge>
+          )}
+          {showDismiss && (
+            <Button
+              size="compact-sm"
+              variant="default"
+              color="gray"
+              loading={dismissSuggestionMutation.isPending}
+              disabled={pending}
+              onClick={handleDismiss}
+            >
+              {t("Dismiss")}
+            </Button>
+          )}
+          {showApply && (
+            <Button
+              size="compact-sm"
+              color="green"
+              loading={applySuggestionMutation.isPending}
+              disabled={pending}
+              onClick={handleApply}
+            >
+              {t("Apply")}
+            </Button>
+          )}
+        </Group>
+      </Stack>
+    </Box>
+  );
+}
+
+// Series header for a collapsed agent run: ONE provenance line for N edits,
+// with a "N edits · M major" tally. There is intentionally NO "Accept all"
+// button / progress / Stop (rejected by product) and NO "K applied" counter
+// (uncomputable after the #329 hard-delete). Purely visual.
+export function RunHeader({ comments }: { comments: IComment[] }) {
+  const { t } = useTranslation();
+  const head = comments[0];
+  const createdAtAgo = useTimeAgo(head?.createdAt);
+
+  const majors = useMemo(
+    () =>
+      comments.filter((c) =>
+        isSignificant(parseSeverity(commentContentToText(c.content))),
+      ).length,
+    [comments],
+  );
+
+  if (!head) return null;
+
+  return (
+    <Box
+      p="11px 13px"
+      style={{ borderBottom: "1px solid var(--mantine-color-default-border)" }}
+    >
+      <Group gap={10} wrap="nowrap" justify="space-between">
+        {head.agent ? (
+          <AgentAvatarStack
+            agent={head.agent}
+            launcher={head.launcher}
+            aiChatId={head.aiChatId}
+          />
+        ) : (
+          <Text size="sm" fw={600}>
+            {head.creator?.name}
+          </Text>
+        )}
+        <Text size="xs" c="dimmed" style={{ flex: "none" }}>
+          {createdAtAgo}
+        </Text>
+      </Group>
+      <Text fz={11.5} c="dimmed" mt={4}>
+        {t("{{count}} edits", { count: comments.length })}
+        {majors > 0 && (
+          <>
+            {" · "}
+            <Text span c="orange.7" fw={600} inherit>
+              {t("{{count}} major", { count: majors })}
+            </Text>
+          </>
+        )}
+      </Text>
+    </Box>
+  );
+}
+
+export default React.memo(AgentEditCard);

apps/client/src/features/comment/components/comment-list-item.test.tsx

@@ -156,125 +156,6 @@ describe("CommentListItem — agent avatar stack", () => {
   // only guards the insertion gate (agent → stack, user → no stack).
 });
 
-describe("CommentListItem — suggested edit (#315)", () => {
-  const suggestion = (over?: Partial<IComment>): IComment =>
-    baseComment({
-      selection: "old wording here",
-      suggestedText: "new wording here",
-      ...over,
-    });
-
-  it("renders the было→стало diff and an Apply button when canEdit and not applied/resolved", () => {
-    const { container } = renderItem(suggestion(), true);
-    // Old text appears as the selection quote (a single unsplit Text node).
-    expect(screen.getAllByText("old wording here").length).toBeGreaterThan(0);
-    // The new line is now rendered as per-fragment spans (intraline diff, #331),
-    // so it is no longer a single text node — assert the concatenated content.
-    expect(container.textContent).toContain("new wording here");
-    // Apply button is present.
-    expect(screen.getByRole("button", { name: "Apply" })).toBeDefined();
-    // No Applied badge yet.
-    expect(screen.queryByText("Applied")).toBeNull();
-  });
-
-  it("hides the Apply button when canEdit is false", () => {
-    const { container } = renderItem(suggestion(), false);
-    // Diff still renders (as per-fragment spans, #331)...
-    expect(container.textContent).toContain("new wording here");
-    // ...but no Apply button.
-    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
-  });
-
-  it("shows an Applied badge (no Apply button) once suggestionAppliedAt is set", () => {
-    renderItem(suggestion({ suggestionAppliedAt: new Date() }), true);
-    expect(screen.getByText("Applied")).toBeDefined();
-    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
-  });
-
-  it("hides the Apply button once the thread is resolved", () => {
-    renderItem(suggestion({ resolvedAt: new Date() }), true);
-    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
-  });
-
-  it("calls the apply mutation when the Apply button is clicked", () => {
-    applyMutateAsync.mockClear();
-    renderItem(suggestion(), true);
-    fireEvent.click(screen.getByRole("button", { name: "Apply" }));
-    expect(applyMutateAsync).toHaveBeenCalledWith({
-      commentId: "c-1",
-      pageId: "page-1",
-    });
-  });
-
-  it("does not render the diff block for a reply (child) comment", () => {
-    renderItem(
-      suggestion({ parentCommentId: "c-0" }),
-      true,
-    );
-    expect(screen.queryByText("new wording here")).toBeNull();
-    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
-  });
-});
-
-describe("CommentListItem — dismiss suggestion (#329)", () => {
-  const suggestion = (over?: Partial<IComment>): IComment =>
-    baseComment({
-      selection: "old wording here",
-      suggestedText: "new wording here",
-      ...over,
-    });
-
-  // A space admin (userSpaceRole="admin") satisfies the owner-or-admin gate
-  // regardless of who authored the comment; the tests below use it as the lever
-  // since the currentUser atom is unseeded (null) in this harness.
-  it("renders a Dismiss button alongside Apply when canEdit and canComment (owner/admin)", () => {
-    renderItem(suggestion(), true, true, "admin");
-    expect(screen.getByRole("button", { name: "Apply" })).toBeDefined();
-    expect(screen.getByRole("button", { name: "Dismiss" })).toBeDefined();
-  });
-
-  it("shows Dismiss but NOT Apply for an admin commenter who cannot edit", () => {
-    renderItem(suggestion(), false, true, "admin");
-    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
-    expect(screen.getByRole("button", { name: "Dismiss" })).toBeDefined();
-  });
-
-  it("hides Dismiss when the viewer cannot comment", () => {
-    renderItem(suggestion(), false, false, "admin");
-    expect(screen.queryByRole("button", { name: "Dismiss" })).toBeNull();
-    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
-  });
-
-  it("hides Dismiss for a non-owner non-admin even with canComment (#338 F5: mirrors server 403)", () => {
-    // canComment=true but NOT a space admin and NOT the comment owner (the
-    // currentUser atom is null while the comment is authored by user-1), so the
-    // server would 403 a dismiss — the button must not be shown at all.
-    renderItem(suggestion(), false, true, "member");
-    expect(screen.queryByRole("button", { name: "Dismiss" })).toBeNull();
-  });
-
-  it("hides Dismiss once the thread is resolved", () => {
-    renderItem(suggestion({ resolvedAt: new Date() }), true, true, "admin");
-    expect(screen.queryByRole("button", { name: "Dismiss" })).toBeNull();
-  });
-
-  it("hides Dismiss (shows the Applied badge) once applied", () => {
-    renderItem(suggestion({ suggestionAppliedAt: new Date() }), true, true, "admin");
-    expect(screen.queryByRole("button", { name: "Dismiss" })).toBeNull();
-    expect(screen.getByText("Applied")).toBeDefined();
-  });
-
-  it("calls the dismiss mutation when the Dismiss button is clicked", () => {
-    dismissMutateAsync.mockClear();
-    renderItem(suggestion(), true, true, "admin");
-    fireEvent.click(screen.getByRole("button", { name: "Dismiss" }));
-    expect(dismissMutateAsync).toHaveBeenCalledWith({
-      commentId: "c-1",
-      pageId: "page-1",
-    });
-  });
-});
-
 describe("canShowApply predicate", () => {
   const c = (over?: Partial<IComment>): IComment =>
     ({ suggestedText: "x", ...over }) as IComment;

apps/client/src/features/comment/components/comment-list-item.tsx

@@ -1,6 +1,6 @@
-import { Group, Text, Box, Badge, Button } from "@mantine/core";
+import { Group, Text, Box } from "@mantine/core";
 import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
-import React, { useMemo, useRef, useState } from "react";
+import React, { useRef, useState } from "react";
 import classes from "./comment.module.css";
 import { useAtom, useAtomValue } from "jotai";
 import { useTimeAgo } from "@/hooks/use-time-ago";
@@ -12,18 +12,11 @@ import CommentMenu from "@/features/comment/components/comment-menu";
 import ResolveComment from "@/features/comment/components/resolve-comment";
 import { useHover } from "@mantine/hooks";
 import {
-  useApplySuggestionMutation,
   useDeleteCommentMutation,
-  useDismissSuggestionMutation,
   useResolveCommentMutation,
   useUpdateCommentMutation,
 } from "@/features/comment/queries/comment-query";
 import { IComment } from "@/features/comment/types/comment.types";
-import {
-  canShowApply,
-  canShowDismiss,
-  computeSuggestionDiff,
-} from "@/features/comment/utils/suggestion";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { useTranslation } from "react-i18next";
@@ -32,13 +25,21 @@ interface CommentListItemProps {
   comment: IComment;
   pageId: string;
   canComment: boolean;
-  // Real page-edit permission (page.permissions.canEdit) — gates the suggestion
-  // "Apply" button. Distinct from `canComment`, which may be looser (viewers
-  // allowed to comment cannot apply edits).
+  // Real page-edit permission (page.permissions.canEdit). Kept on the props for
+  // parity with the container's wiring even though the thread row itself no
+  // longer renders the suggestion Apply button (that moved to AgentEditCard).
   canEdit?: boolean;
   userSpaceRole?: string;
 }
 
+// Type B — the thread ROW. Renders a single human OR agent-without-edit comment
+// in the redesigned visual: provenance avatar, author + timeago, hover-revealed
+// resolve + edit/delete menu, the anchored selection quote, and the body through
+// the static CommentContentView (or the inline TipTap editor while editing). It
+// is used for both a top-level thread comment and, recursively, each reply row.
+// ALL wiring (update/delete/resolve mutations, owner/admin gate, anchor nav) is
+// the same logic the old row carried — only the presentation changed, and the
+// agent suggested-edit block was lifted out into AgentEditCard.
 function CommentListItem({
   comment,
   pageId,
@@ -55,29 +56,20 @@ function CommentListItem({
   const updateCommentMutation = useUpdateCommentMutation();
   const deleteCommentMutation = useDeleteCommentMutation(comment.pageId);
   const resolveCommentMutation = useResolveCommentMutation();
-  const applySuggestionMutation = useApplySuggestionMutation();
-  const dismissSuggestionMutation = useDismissSuggestionMutation();
   const [currentUser] = useAtom(currentUserAtom);
   const createdAtAgo = useTimeAgo(comment.createdAt);
 
-  // Intraline "before -> after" diff (#331) for a suggested edit: only the
-  // fragments that actually changed get emphasised inside the red/green block,
-  // instead of striking through / greening the whole line. Memoised on the
-  // (selection, suggestedText) pair so it recomputes only when they change.
-  const suggestionDiff = useMemo(
-    () =>
-      comment.suggestedText != null
-        ? computeSuggestionDiff(comment.selection ?? "", comment.suggestedText)
-        : null,
-    [comment.selection, comment.suggestedText],
-  );
+  // `canEdit`/`pageId` are threaded through for wiring parity with the container;
+  // the thread row does not itself gate on them (Apply lives on AgentEditCard).
+  void canEdit;
+  void pageId;
 
-  // Owner-or-space-admin gate (#338): mirrors the server authz for both the
-  // comment menu (edit/delete) and the suggestion Dismiss button, so we never
-  // render an action the server will 403.
+  // Owner-or-space-admin gate (#338): mirrors the server authz for the comment
+  // menu (edit/delete), so we never render an action the server will 403.
   const isOwnerOrAdmin =
     currentUser?.user?.id === comment.creatorId || userSpaceRole === "admin";
 
+  const isAgent = comment.createdSource === "agent" && !!comment.agent;
 
   async function handleUpdateComment() {
     try {
@@ -121,34 +113,9 @@ function CommentListItem({
     }
   }
 
-  async function handleApplySuggestion() {
-    try {
-      await applySuggestionMutation.mutateAsync({
-        commentId: comment.id,
-        pageId: comment.pageId,
-      });
-    } catch (error) {
-      // Errors surface via the mutation's onError notification (incl. 409).
-      console.error("Failed to apply suggestion:", error);
-    }
-  }
-
-  async function handleDismissSuggestion() {
-    try {
-      await dismissSuggestionMutation.mutateAsync({
-        commentId: comment.id,
-        pageId: comment.pageId,
-      });
-    } catch (error) {
-      // Idempotent races are reconciled to success in the mutation's onError;
-      // anything else surfaces there as a notification.
-      console.error("Failed to dismiss suggestion:", error);
-    }
-  }
-
-  function handleCommentClick(comment: IComment) {
+  function handleCommentClick(target: IComment) {
     const el = document.querySelector(
-      `.comment-mark[data-comment-id="${comment.id}"]`,
+      `.comment-mark[data-comment-id="${target.id}"]`,
     );
     if (el) {
       el.scrollIntoView({ behavior: "smooth", block: "center" });
@@ -169,10 +136,10 @@ function CommentListItem({
 
   return (
     <Box ref={ref} pb={6}>
-      <Group gap="xs">
-        {comment.createdSource === "agent" && comment.agent ? (
+      <Group gap="xs" wrap="nowrap" align="flex-start">
+        {isAgent ? (
           <AgentAvatarStack
-            agent={comment.agent}
+            agent={comment.agent!}
             launcher={comment.launcher}
             aiChatId={comment.aiChatId}
             showName={false}
@@ -185,13 +152,13 @@ function CommentListItem({
           />
         )}
 
-        <div style={{ flex: 1 }}>
+        <div style={{ flex: 1, minWidth: 0 }}>
           <Group justify="space-between" wrap="nowrap">
             <Group gap={6} wrap="nowrap" style={{ minWidth: 0 }}>
-              {comment.createdSource === "agent" && comment.agent ? (
+              {isAgent ? (
                 <>
                   <Text size="xs" fw={600} lineClamp={1} lh={1.2}>
-                    {comment.agent.name}
+                    {comment.agent!.name}
                   </Text>
                   {comment.launcher && (
                     <>
@@ -262,87 +229,6 @@ function CommentListItem({
           </Box>
         )}
 
-        {/* Suggested-edit (#315): "было → стало" diff for a top-level comment
-            carrying a suggestion. Old text struck-through/red, new text green. */}
-        {!comment.parentCommentId && comment.suggestedText && (
-          <Box className={classes.suggestionBlock}>
-            {comment.selection && (
-              // Old line: read as removed as a whole (line-through/red); only the
-              // changed fragments carry the extra intraline emphasis.
-              <Text size="xs" className={classes.suggestionOld}>
-                {suggestionDiff?.old.map((segment, index) => (
-                  <span
-                    key={index}
-                    className={segment.changed ? classes.suggestionChanged : undefined}
-                  >
-                    {segment.text}
-                  </span>
-                ))}
-              </Text>
-            )}
-            <Text size="xs" className={classes.suggestionNew}>
-              {suggestionDiff?.new.map((segment, index) => (
-                <span
-                  key={index}
-                  className={segment.changed ? classes.suggestionChanged : undefined}
-                >
-                  {segment.text}
-                </span>
-              ))}
-            </Text>
-
-            {comment.suggestionAppliedAt ? (
-              <Badge
-                size="sm"
-                color="green"
-                variant="light"
-                mt={6}
-                aria-label={t("Applied")}
-              >
-                {t("Applied")}
-              </Badge>
-            ) : (
-              (canShowApply(comment, canEdit) ||
-                canShowDismiss(comment, canComment, isOwnerOrAdmin)) && (
-                <Group gap="xs" mt={6}>
-                  {canShowApply(comment, canEdit) && (
-                    <Button
-                      size="compact-xs"
-                      variant="light"
-                      color="green"
-                      onClick={handleApplySuggestion}
-                      loading={applySuggestionMutation.isPending}
-                      disabled={
-                        applySuggestionMutation.isPending ||
-                        dismissSuggestionMutation.isPending
-                      }
-                    >
-                      {t("Apply")}
-                    </Button>
-                  )}
-                  {/* Dismiss ("Не применять", #329): removes the suggestion
-                      without changing the page text. Gated on canComment. */}
-                  {canShowDismiss(comment, canComment, isOwnerOrAdmin) && (
-                    <Button
-                      size="compact-xs"
-                      variant="subtle"
-                      color="gray"
-                      onClick={handleDismissSuggestion}
-                      loading={dismissSuggestionMutation.isPending}
-                      disabled={
-                        applySuggestionMutation.isPending ||
-                        dismissSuggestionMutation.isPending
-                      }
-                    >
-                      {t("Dismiss")}
-                    </Button>
-                  )}
-                </Group>
-              )
-            )}
-          </Box>
-        )}
-
         {!isEditing ? (
           <CommentContentView content={comment.content} />
         ) : (
@@ -350,7 +236,9 @@ function CommentListItem({
             <CommentEditor
               defaultContent={comment.content}
               editable={true}
-              onUpdate={(newContent: any) => { editContentRef.current = newContent; }}
+              onUpdate={(newContent: any) => {
+                editContentRef.current = newContent;
+              }}
               onSave={handleUpdateComment}
               autofocus={true}
             />

apps/client/src/features/comment/components/comment-list-with-tabs.tsx

@@ -5,7 +5,7 @@ import {
   Center,
   Divider,
   Group,
-  Paper,
+  Box,
   Stack,
   Tabs,
   Badge,
@@ -14,6 +14,9 @@ import {
   Tooltip,
 } from "@mantine/core";
 import CommentListItem from "@/features/comment/components/comment-list-item";
+import AgentEditCard, {
+  RunHeader,
+} from "@/features/comment/components/agent-edit-card";
 import {
   useCommentsQuery,
   useCreateCommentMutation,
@@ -22,6 +25,10 @@ import CommentEditor from "@/features/comment/components/comment-editor";
 import CommentActions from "@/features/comment/components/comment-actions";
 import { useFocusWithin } from "@mantine/hooks";
 import { IComment } from "@/features/comment/types/comment.types.ts";
+import {
+  groupAgentRuns,
+  CommentRenderUnit,
+} from "@/features/comment/utils/group-agent-runs";
 import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
 import { useTranslation } from "react-i18next";
@@ -69,6 +76,32 @@ export function sortResolvedByResolvedAt(resolved: IComment[]): IComment[] {
   );
 }
 
+// The redesigned card shell: a rounded, bordered surface on the panel body. Both
+// a thread card and an agent-run group live inside one of these.
+function PanelCard({
+  children,
+  ...rest
+}: {
+  children: React.ReactNode;
+  [key: string]: unknown;
+}) {
+  return (
+    <Box
+      m="8px 10px"
+      p={0}
+      style={{
+        background: "var(--mantine-color-body)",
+        border: "1px solid var(--mantine-color-default-border)",
+        borderRadius: 10,
+        overflow: "hidden",
+      }}
+      {...rest}
+    >
+      {children}
+    </Box>
+  );
+}
+
 function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
   const { t } = useTranslation();
   const { pageSlug } = useParams();
@@ -90,6 +123,8 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
     canEdit ||
     (space?.settings?.comments?.allowViewerComments === true);
 
+  const userSpaceRole = space?.membership?.role;
+
   // Separate active and resolved comments
   const { activeComments, resolvedComments } = useMemo(() => {
     if (!comments?.items) {
@@ -113,6 +148,17 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
     };
   }, [comments]);
 
+  // Collapse each tab's top-level list into render units (a lone comment or a
+  // collapsed agent run). Purely visual — the underlying data is untouched.
+  const activeUnits = useMemo(
+    () => groupAgentRuns(activeComments),
+    [activeComments],
+  );
+  const resolvedUnits = useMemo(
+    () => groupAgentRuns(resolvedComments),
+    [resolvedComments],
+  );
+
   // Index replies by their parent once, instead of an O(n^2) filter per thread.
   // The map ref changes on any comments update, so MemoizedChildComments re-runs
   // (cheap) and re-looks-up, while memoized CommentListItems skip unchanged items.
@@ -168,56 +214,104 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
     [createCommentAsync, page?.id],
   );
 
-  const renderComments = useCallback(
-    (comment: IComment) => (
-      <Paper
-        shadow="sm"
-        radius="md"
-        p="xs"
-        mb="xs"
-        withBorder
-        key={comment.id}
-        data-comment-id={comment.id}
-      >
-        <div>
-          <CommentListItem
+  // The full subtree for ONE top-level comment: its head card (thread row or
+  // agent edit card), its nested replies, and a lazily-mounted reply editor.
+  // Shared by a standalone card and a card inside an agent-run group so the
+  // reply threading / lazy editor (#340) is wired identically in both.
+  const renderCommentSubtree = useCallback(
+    (comment: IComment, isEdit: boolean, showProvenance: boolean) => (
+      <>
+        {isEdit ? (
+          <AgentEditCard
             comment={comment}
-            pageId={page?.id}
             canComment={canComment}
             canEdit={canEdit}
-            userSpaceRole={space?.membership?.role}
+            userSpaceRole={userSpaceRole}
+            showProvenance={showProvenance}
           />
+        ) : (
+          <Box p="xs">
+            <CommentListItem
+              comment={comment}
+              pageId={page?.id}
+              canComment={canComment}
+              canEdit={canEdit}
+              userSpaceRole={userSpaceRole}
+            />
+          </Box>
+        )}
+
+        <Box px="xs">
           <MemoizedChildComments
             childrenByParent={childrenByParent}
             parentId={comment.id}
             pageId={page?.id}
             canComment={canComment}
             canEdit={canEdit}
-            userSpaceRole={space?.membership?.role}
+            userSpaceRole={userSpaceRole}
           />
-        </div>
+        </Box>
 
         {!comment.resolvedAt && canComment && (
-          <>
+          <Box px="xs" pb="xs">
             <Divider my={2} />
             <CommentEditorWithActions
               commentId={comment.id}
               onSave={handleAddReply}
             />
-          </>
+          </Box>
         )}
-      </Paper>
+      </>
     ),
     [
       childrenByParent,
       handleAddReply,
       page?.id,
-      space?.membership?.role,
+      userSpaceRole,
       canComment,
       canEdit,
     ],
   );
 
+  // Render one collapsed unit: a standalone card (thread or lone edit) or an
+  // agent-run group (one RunHeader over N stacked edit cards).
+  const renderUnit = useCallback(
+    (unit: CommentRenderUnit) => {
+      if (unit.kind === "single") {
+        const c = unit.comment;
+        const isEdit =
+          c.createdSource === "agent" &&
+          c.suggestedText != null &&
+          !c.parentCommentId;
+        return (
+          <PanelCard key={c.id} data-comment-id={c.id}>
+            {renderCommentSubtree(c, isEdit, true)}
+          </PanelCard>
+        );
+      }
+
+      // A collapsed agent run: one header, then each edit card (provenance
+      // suppressed on the cards — the header carries the single provenance line).
+      return (
+        <PanelCard key={unit.key}>
+          <RunHeader comments={unit.comments} />
+          {unit.comments.map((c) => (
+            <Box
+              key={c.id}
+              data-comment-id={c.id}
+              style={{
+                borderTop: "1px solid var(--mantine-color-default-border)",
+              }}
+            >
+              {renderCommentSubtree(c, true, false)}
+            </Box>
+          ))}
+        </PanelCard>
+      );
+    },
+    [renderCommentSubtree],
+  );
+
   if (isCommentsLoading) {
     return <></>;
   }
@@ -226,8 +320,6 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
     return <div>{t("Error loading comments.")}</div>;
   }
 
-  const totalComments = activeComments.length + resolvedComments.length;
-
   const pageCommentInput = canComment ? (
     <PageCommentInput
       onSave={handleAddPageComment}
@@ -328,7 +420,7 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
                   </Stack>
                 </Center>
               ) : (
-                activeComments.map(renderComments)
+                activeUnits.map(renderUnit)
               )}
             </Tabs.Panel>
 
@@ -347,7 +439,7 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
                   </Stack>
                 </Center>
               ) : (
-                resolvedComments.map(renderComments)
+                resolvedUnits.map(renderUnit)
               )}
             </Tabs.Panel>
           </div>

apps/client/src/features/comment/components/comment.module.css

@@ -21,53 +21,6 @@
     box-sizing: border-box;
 }
 
-/* Suggested-edit (#315) "было → стало" diff block. */
-.suggestionBlock {
-    margin-top: 8px;
-    margin-left: 6px;
-    padding: 6px;
-    border-radius: var(--mantine-radius-sm);
-    border: 1px solid var(--mantine-color-default-border);
-    overflow-wrap: break-word;
-    word-break: break-word;
-    max-width: 100%;
-    box-sizing: border-box;
-    display: flex;
-    flex-direction: column;
-    align-items: flex-start;
-}
-
-.suggestionOld {
-    text-decoration: line-through;
-    color: var(--mantine-color-red-7);
-    background: var(--mantine-color-red-light);
-    border-radius: 2px;
-    padding: 1px 3px;
-}
-
-.suggestionNew {
-    color: var(--mantine-color-green-9);
-    background: var(--mantine-color-green-light);
-    border-radius: 2px;
-    padding: 1px 3px;
-    margin-top: 4px;
-}
-
-/* Intraline diff (#331): the fragment that actually changed within the
-   red "before" / green "after" block. It inherits the surrounding red/green
-   framing and adds a stronger tint plus bold weight so the eye lands on the
-   changed letters/words (git/GitHub-style) rather than the whole line. The
-   container's line-through (old) / green (new) still marks the full line. */
-.suggestionChanged {
-    /* Stronger tint of the surrounding red/green so the changed fragment pops
-       within the block. `currentColor` follows the parent's red (old) or green
-       (new) text colour. No `text-decoration` here on purpose: the old block's
-       inherited line-through must survive on the changed letters too. */
-    background: color-mix(in srgb, currentColor 22%, transparent);
-    border-radius: 2px;
-    font-weight: 700;
-}
-
 .commentEditor {
 
     &[data-editable][data-surface="muted"] .ProseMirror:not(.focused) {

apps/client/src/features/comment/utils/group-agent-runs.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import { groupAgentRuns, runKey, GROUP_MIN } from "./group-agent-runs";
+import { IComment } from "@/features/comment/types/comment.types";
+
+const editComment = (id: string, over?: Partial<IComment>): IComment =>
+  ({
+    id,
+    createdSource: "agent",
+    aiChatId: "chat-1",
+    agent: { name: "Corrector" },
+    suggestedText: "new text",
+    parentCommentId: null,
+    ...over,
+  }) as unknown as IComment;
+
+const human = (id: string): IComment =>
+  ({ id, createdSource: "user", parentCommentId: null }) as unknown as IComment;
+
+describe("runKey", () => {
+  it("keys a groupable agent edit on aiChatId + agent.name", () => {
+    expect(runKey(editComment("a"))).toBe("chat-1:Corrector");
+  });
+
+  it("is null for an external MCP agent (aiChatId null)", () => {
+    expect(runKey(editComment("a", { aiChatId: null }))).toBeNull();
+  });
+
+  it("is null for a non-edit agent comment (no suggestedText)", () => {
+    expect(runKey(editComment("a", { suggestedText: null }))).toBeNull();
+  });
+
+  it("is null for a reply (has parentCommentId)", () => {
+    expect(runKey(editComment("a", { parentCommentId: "p" }))).toBeNull();
+  });
+
+  it("is null for a human comment", () => {
+    expect(runKey(human("a"))).toBeNull();
+  });
+});
+
+describe("groupAgentRuns", () => {
+  it("collapses >= GROUP_MIN same chat+role edits into one run at the first position", () => {
+    const units = groupAgentRuns([
+      editComment("e1"),
+      editComment("e2"),
+      editComment("e3"),
+    ]);
+    expect(units).toHaveLength(1);
+    expect(units[0].kind).toBe("run");
+    if (units[0].kind === "run") {
+      expect(units[0].key).toBe("chat-1:Corrector");
+      expect(units[0].comments.map((c) => c.id)).toEqual(["e1", "e2", "e3"]);
+    }
+    expect(GROUP_MIN).toBe(2);
+  });
+
+  it("renders a lone edit as a single (below the threshold)", () => {
+    const units = groupAgentRuns([editComment("e1")]);
+    expect(units).toHaveLength(1);
+    expect(units[0].kind).toBe("single");
+  });
+
+  it("never groups external MCP edits (aiChatId null) — each is a single", () => {
+    const units = groupAgentRuns([
+      editComment("m1", { aiChatId: null }),
+      editComment("m2", { aiChatId: null }),
+    ]);
+    expect(units).toHaveLength(2);
+    expect(units.every((u) => u.kind === "single")).toBe(true);
+  });
+
+  it("does not collapse two different roles sharing one chat", () => {
+    const units = groupAgentRuns([
+      editComment("a", { agent: { name: "Corrector" } as any }),
+      editComment("b", { agent: { name: "FactChecker" } as any }),
+    ]);
+    // Each key has count 1 -> both remain singles.
+    expect(units).toHaveLength(2);
+    expect(units.every((u) => u.kind === "single")).toBe(true);
+  });
+
+  it("preserves order and keeps human threads as singles interleaved with a run", () => {
+    const units = groupAgentRuns([
+      human("h1"),
+      editComment("e1"),
+      editComment("e2"),
+      human("h2"),
+    ]);
+    // h1 single, then the run (emitted at e1's position, e2 absorbed), then h2.
+    expect(units.map((u) => u.kind)).toEqual(["single", "run", "single"]);
+    if (units[1].kind === "run") {
+      expect(units[1].comments.map((c) => c.id)).toEqual(["e1", "e2"]);
+    }
+  });
+});

apps/client/src/features/comment/utils/group-agent-runs.ts

@@ -0,0 +1,76 @@
+import { IComment } from "@/features/comment/types/comment.types";
+
+// A visual-only series threshold: this many agent suggested-edits sharing one
+// run key collapse under a single RunHeader. A group of one renders as a plain
+// standalone card (no header). Policy constant — no env override.
+export const GROUP_MIN = 2;
+
+// One rendered unit of the top-level comment list: either a collapsed agent-run
+// group (>= GROUP_MIN suggested-edits from the same chat+role) or a single
+// comment (a human thread, an agent thread without an edit, or a lone edit).
+export interface AgentRunGroup {
+  kind: "run";
+  key: string;
+  comments: IComment[];
+}
+export interface SingleUnit {
+  kind: "single";
+  comment: IComment;
+}
+export type CommentRenderUnit = AgentRunGroup | SingleUnit;
+
+// The grouping key of a top-level agent suggested-edit, or null when the comment
+// is not a groupable edit. The key pins BOTH the AI chat and the acting role
+// (`aiChatId + ":" + agent.name`) so two roles running in the same chat do not
+// collapse under one header. A comment with `aiChatId == null` (an external MCP
+// agent) has no chat to group by — it is deliberately never groupable and always
+// renders as a single card (a time-bucketed synthetic run would split/merge runs
+// arbitrarily and choke on ISO `createdAt`). PURE.
+export function runKey(c: IComment): string | null {
+  if (
+    c.createdSource === "agent" &&
+    c.suggestedText != null &&
+    !c.parentCommentId &&
+    c.aiChatId != null &&
+    c.agent?.name
+  ) {
+    return `${c.aiChatId}:${c.agent.name}`;
+  }
+  return null;
+}
+
+// Collapse an ORDERED list of top-level comments into render units, preserving
+// list order: a run is emitted in place of its FIRST member (later members are
+// absorbed), everything else stays a single unit. Grouping is computed over the
+// snapshot handed in; a streamed page / WS update may later promote a single
+// edit into a run as more members arrive — that is acceptable (purely visual).
+// PURE — no React/DOM, no mutation of the input.
+export function groupAgentRuns(comments: IComment[]): CommentRenderUnit[] {
+  // First pass: tally groupable edits per key so we know which keys clear
+  // GROUP_MIN before we start emitting.
+  const counts = new Map<string, number>();
+  for (const c of comments) {
+    const key = runKey(c);
+    if (key) counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+
+  const emitted = new Set<string>();
+  const units: CommentRenderUnit[] = [];
+  for (const c of comments) {
+    const key = runKey(c);
+    if (key && (counts.get(key) ?? 0) >= GROUP_MIN) {
+      // Emit the whole run once, at the position of its first member; skip the
+      // absorbed later members.
+      if (emitted.has(key)) continue;
+      emitted.add(key);
+      units.push({
+        kind: "run",
+        key,
+        comments: comments.filter((x) => runKey(x) === key),
+      });
+    } else {
+      units.push({ kind: "single", comment: c });
+    }
+  }
+  return units;
+}

apps/client/src/features/comment/utils/severity.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { parseSeverity, isSignificant } from "./severity";
+
+describe("parseSeverity — exact importance dictionary", () => {
+  it("maps the Russian importance tags", () => {
+    expect(parseSeverity("[Критично] fix now")).toBe("critical");
+    expect(parseSeverity("[Существенно] tighten")).toBe("major");
+    expect(parseSeverity("[Незначительно] nit")).toBe("minor");
+  });
+
+  it("maps the English equivalents and is case-insensitive", () => {
+    expect(parseSeverity("[Critical] x")).toBe("critical");
+    expect(parseSeverity("[MAJOR] x")).toBe("major");
+    expect(parseSeverity("[minor] x")).toBe("minor");
+    expect(parseSeverity("[критично] x")).toBe("critical");
+  });
+
+  it("treats fact-checker verdicts as unknown, NOT a severity", () => {
+    expect(parseSeverity("[Неверно] this is wrong")).toBe("unknown");
+    expect(parseSeverity("[Не проверено] can't verify")).toBe("unknown");
+    expect(parseSeverity("[Непроверяемо] x")).toBe("unknown");
+    expect(parseSeverity("[Это мнение] x")).toBe("unknown");
+  });
+
+  it("treats a typo'd / unrecognised tag as unknown (never falls back to minor)", () => {
+    expect(parseSeverity("[Существенное] typo ending")).toBe("unknown");
+    expect(parseSeverity("[whatever] x")).toBe("unknown");
+  });
+
+  it("returns unknown for no tag or empty input", () => {
+    expect(parseSeverity("plain body, no tag")).toBe("unknown");
+    expect(parseSeverity("")).toBe("unknown");
+  });
+
+  it("finds the recognised importance tag even after a leading verdict tag", () => {
+    expect(parseSeverity("[Неверно] [Существенно] body")).toBe("major");
+  });
+});
+
+describe("isSignificant", () => {
+  it("counts only major and critical", () => {
+    expect(isSignificant("critical")).toBe(true);
+    expect(isSignificant("major")).toBe(true);
+    expect(isSignificant("minor")).toBe(false);
+    expect(isSignificant("unknown")).toBe(false);
+  });
+});

apps/client/src/features/comment/utils/severity.ts

@@ -0,0 +1,44 @@
+// Severity of an agent suggested-edit, parsed CLIENT-SIDE from the importance
+// tag the editorial role prompts emit at the head of the comment body
+// (`[Критично]` / `[Существенно]` / `[Незначительно]`, or their English
+// equivalents). It is a DISPLAY-ONLY signal: it drives the coloured dot on the
+// edit card and the "M major" counter in a run header. It never gates an action.
+//
+// `unknown` is a first-class value, NOT a synonym for `minor`: any bracketed
+// text that is not in the exact dictionary — a Fact-checker verdict
+// (`[Неверно]`, `[Не проверено]`, `[Непроверяемо]`, `[Это мнение]`), a typo
+// (`[Существенное]`), or the absence of a tag — resolves to `unknown` and draws
+// a neutral dot. Passing an unrecognised tag off as `minor` would mis-label it.
+export type Severity = "critical" | "major" | "minor" | "unknown";
+
+// EXACT (case-insensitive) dictionary. Only these tokens map to a real severity;
+// everything else falls through to `unknown` on purpose.
+const SEVERITY_TAGS: Record<string, Severity> = {
+  критично: "critical",
+  существенно: "major",
+  незначительно: "minor",
+  critical: "critical",
+  major: "major",
+  minor: "minor",
+};
+
+// Parse the first RECOGNISED importance tag out of the flattened comment text
+// (use `commentContentToText` to obtain it). Scans every `[...]` token so a tag
+// that trails a verdict still counts; the first exact-dictionary hit wins. When
+// no token matches the dictionary the result is `unknown`. PURE — no React/DOM.
+export function parseSeverity(text: string): Severity {
+  if (!text) return "unknown";
+  const matches = text.matchAll(/\[([^\]]+)\]/g);
+  for (const m of matches) {
+    const tag = m[1].trim().toLowerCase();
+    const sev = SEVERITY_TAGS[tag];
+    if (sev) return sev;
+  }
+  return "unknown";
+}
+
+// Whether a severity counts toward the "M major" tally in a run header: only the
+// genuinely significant ones (major + critical). `minor` and `unknown` do not.
+export function isSignificant(severity: Severity): boolean {
+  return severity === "major" || severity === "critical";
+}

apps/client/src/features/editor/components/footnote/footnote.module.css

@@ -92,13 +92,23 @@
    wrapper, never in the document model) and is rendered inline at the start of
    the first content line via ::before. This keeps text and wrapped lines flush
    to the left margin — no hanging indent — while the editable contentDOM stays
-   the FIRST DOM child (#146). */
+   the FIRST DOM child (#146).
+
+   The rules below target `p:first-child`, NOT `> :first-child`: tiptap-react
+   wraps the NodeViewContent children in an extra block-level div
+   (`[data-node-view-content-react]`, style="white-space: inherit"), so
+   `.definitionContent`'s first child is that wrapper, not the paragraph. An
+   inline ::before on the block wrapper (whose child is a block <p>) drops onto
+   its own line above the text — the "+1 line" regression. `p:first-child`
+   reaches the real first paragraph so the number stays inline, and it works
+   whether or not the wrapper is present (definition content is `paragraph+`,
+   so there are no nested paragraphs to mis-match). */
 .definitionContent {
   flex: 1 1 auto;
   min-width: 0;
 }
 
-.definitionContent > :first-child::before {
+.definitionContent p:first-child::before {
   content: var(--footnote-number, "?") ". ";
   color: var(--mantine-color-dimmed);
   font-variant-numeric: tabular-nums;
@@ -108,12 +118,13 @@
 /* The inner editable paragraph inherits `.ProseMirror p { margin: 0.5em 0 }`.
    Drop the outer margins so the definition sits tight to the heading above and
    the ::before number aligns with the top of the row — same approach used for
-   callouts in core.css. */
-.definitionContent > :first-child {
+   callouts in core.css. Target the paragraphs directly (through the
+   tiptap-react content wrapper), same reasoning as the ::before rule above. */
+.definitionContent p:first-child {
   margin-top: 0;
 }
 
-.definitionContent > :last-child {
+.definitionContent p:last-child {
   margin-bottom: 0;
 }
 

apps/client/src/features/page-history/work-time/work-time-adapter.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildRows,
+  formatBlockTooltip,
+  summaryLabels,
+  toBlocks,
+  toTimelineDay,
+  EMPTY_RUN_COLLAPSE,
+} from "./work-time-adapter";
+import { IPageWorkTime, IPerDay } from "./work-time.types";
+
+const MIN = 60 * 1000;
+const HOUR = 60 * MIN;
+const DAY_MS = 24 * HOUR;
+
+// Fake translator: renders the key with {{tokens}} substituted, so the tests
+// assert the mapping/branching without depending on the i18n catalogue.
+const t = (key: string, opts?: Record<string, unknown>) =>
+  key.replace(/\{\{(\w+)\}\}/g, (_, k) => String(opts?.[k] ?? ""));
+
+// A day midnight anchored at a fixed UTC instant (tz handled server-side; we
+// only lay out fractions of the day the server already bucketed).
+const DAY0 = Date.UTC(2026, 5, 29, 0, 0, 0); // Mon 29 Jun 2026 00:00 UTC
+
+function day(over: Partial<IPerDay> & { day: number }): IPerDay {
+  return {
+    dayISO: new Date(over.day).toISOString().slice(0, 10),
+    activeMs: 0,
+    agentMs: 0,
+    windows: [],
+    ...over,
+  };
+}
+
+const config: IPageWorkTime["config"] = {
+  tGap: 15 * MIN,
+  agentTGap: 15 * MIN,
+  pIn: 0,
+  pOut: 0,
+  pSingle: 30 * 1000,
+  excludeGit: false,
+  dedupRoundMs: 1000,
+};
+
+function payload(over: Partial<IPageWorkTime>): IPageWorkTime {
+  return {
+    workMs: 0,
+    agentOnlyMs: 0,
+    perDay: [],
+    config,
+    tz: "UTC",
+    ...over,
+  };
+}
+
+describe("toBlocks", () => {
+  it("maps work+agent windows to time-of-day segments (hour fractions)", () => {
+    const d = day({
+      day: DAY0,
+      activeMs: 90 * MIN,
+      windows: [
+        { start: DAY0 + 9 * HOUR, end: DAY0 + 10 * HOUR + 30 * MIN, class: "work" },
+        { start: DAY0 + 22 * HOUR, end: DAY0 + 23 * HOUR, class: "agent_only" },
+      ],
+    });
+    const blocks = toBlocks(d);
+    expect(blocks).toHaveLength(2);
+    expect(blocks[0]).toMatchObject({ start: 9, end: 10.5, kind: "work" });
+    expect(blocks[1]).toMatchObject({ start: 22, end: 23, kind: "agent" });
+    // real epoch preserved for the DST-safe tooltip
+    expect(blocks[0].startEpoch).toBe(DAY0 + 9 * HOUR);
+  });
+
+  it("clamps out-of-day fractions to [0,24]", () => {
+    const d = day({
+      day: DAY0,
+      windows: [{ start: DAY0 - HOUR, end: DAY0 + 25 * HOUR, class: "work" }],
+    });
+    const [b] = toBlocks(d);
+    expect(b.start).toBe(0);
+    expect(b.end).toBe(24);
+  });
+});
+
+describe("toTimelineDay", () => {
+  it("draws the now-line only on today's row", () => {
+    const today = day({ day: DAY0, activeMs: HOUR });
+    const noon = DAY0 + 12 * HOUR;
+    const asToday = toTimelineDay(today, t, noon);
+    expect(asToday.isToday).toBe(true);
+    expect(asToday.nowFraction).toBeCloseTo(0.5, 5);
+
+    const past = day({ day: DAY0 - DAY_MS, activeMs: HOUR });
+    const asPast = toTimelineDay(past, t, noon);
+    expect(asPast.isToday).toBe(false);
+    expect(asPast.nowFraction).toBeUndefined();
+  });
+
+  it("labels an empty day and totals it as —", () => {
+    const empty = day({ day: DAY0 });
+    const d = toTimelineDay(empty, t, DAY0 + 12 * HOUR);
+    expect(d.isEmpty).toBe(true);
+    expect(d.totalLabel).toBe("—");
+  });
+});
+
+describe("buildRows (empty-run collapsing)", () => {
+  it("collapses a run of >= EMPTY_RUN_COLLAPSE empty days in place", () => {
+    const perDay: IPerDay[] = [
+      day({ day: DAY0, activeMs: HOUR }),
+      ...Array.from({ length: EMPTY_RUN_COLLAPSE }, (_, i) =>
+        day({ day: DAY0 + (i + 1) * DAY_MS }),
+      ),
+      day({ day: DAY0 + (EMPTY_RUN_COLLAPSE + 1) * DAY_MS, activeMs: HOUR }),
+    ];
+    const rows = buildRows(perDay, t, 0);
+    expect(rows.map((r) => r.type)).toEqual(["day", "gap", "day"]);
+    const gap = rows[1];
+    expect(gap.type === "gap" && gap.count).toBe(EMPTY_RUN_COLLAPSE);
+  });
+
+  it("keeps a short empty run as individual dimmed day rows", () => {
+    const perDay: IPerDay[] = [
+      day({ day: DAY0, activeMs: HOUR }),
+      day({ day: DAY0 + DAY_MS }),
+      day({ day: DAY0 + 2 * DAY_MS, activeMs: HOUR }),
+    ];
+    const rows = buildRows(perDay, t, 0);
+    expect(rows.map((r) => r.type)).toEqual(["day", "day", "day"]);
+  });
+});
+
+describe("summaryLabels", () => {
+  it("derives totalLabel/agentLabel from ms via the shared formatter", () => {
+    const { total, agent } = summaryLabels(
+      payload({ workMs: 4 * HOUR + 27 * MIN, agentOnlyMs: 80 * MIN }),
+      t,
+    );
+    expect(total).toBe("≈ 4h 25m");
+    expect(agent).toBe("≈ 1h 20m");
+  });
+
+  it("agent-only page: agent estimate fills the main slot, no secondary line", () => {
+    const { total, agent } = summaryLabels(
+      payload({ workMs: 0, agentOnlyMs: 80 * MIN }),
+      t,
+    );
+    expect(total).toBe("agent: ≈ 1h 20m");
+    expect(agent).toBeUndefined();
+  });
+
+  it("human-only page: no agent line", () => {
+    const { agent } = summaryLabels(payload({ workMs: HOUR, agentOnlyMs: 0 }), t);
+    expect(agent).toBeUndefined();
+  });
+});
+
+describe("formatBlockTooltip", () => {
+  it("formats start–end from the real epoch in the data tz + duration", () => {
+    const d = day({
+      day: DAY0,
+      windows: [{ start: DAY0 + 9 * HOUR, end: DAY0 + 10 * HOUR + 30 * MIN, class: "work" }],
+    });
+    const [b] = toBlocks(d);
+    const label = formatBlockTooltip(b, "UTC", "en-US", t);
+    expect(label).toBe("09:00 – 10:30 · 1h 30m");
+  });
+});

apps/client/src/features/page-history/work-time/work-time-adapter.ts

@@ -0,0 +1,168 @@
+// #566 — adapter: real IPageWorkTime → the render-ready shape the redesigned
+// time-of-day timeline consumes. The visual prototype (NewDesign/TimeWorkedModal)
+// was written against invented props (`DaySummary[]`, pre-made `totalLabel`); the
+// real payload is IPageWorkTime. Everything below is pure so the mapping (windows
+// → time-of-day blocks, ms → labels, the "now" boundary, empty-run collapsing) is
+// unit-testable without React. No re-bucketing: the server already grouped the
+// windows by the request timezone — we only lay out the windows it returned.
+
+import { IPageWorkTime, IPerDay, IDayWindow } from "./work-time.types";
+import { formatDayTotal, formatHeadline } from "./format-work-time";
+
+type Translate = (key: string, opts?: Record<string, unknown>) => string;
+
+export const DAY_MS = 24 * 60 * 60 * 1000;
+// Collapse a run of this many (or more) consecutive edit-free days into a single
+// "× N days" separator (§6.2 long-range) — preserved from the original punch-card.
+export const EMPTY_RUN_COLLAPSE = 8;
+
+export interface TimelineBlock {
+  /** Hour fraction 0..24 within the day — drives left/width positioning. */
+  start: number;
+  end: number;
+  kind: "work" | "agent";
+  /** Real epoch ms, kept for a DST-safe tooltip (formatted in the data tz). */
+  startEpoch: number;
+  endEpoch: number;
+}
+
+export interface TimelineDay {
+  key: string;
+  label: string;
+  totalLabel: string;
+  blocks: TimelineBlock[];
+  isEmpty: boolean;
+  /** Today lives only in the last active bucket; drives the "now" boundary. */
+  isToday: boolean;
+  /** 0..1 position of "now" within today's track (undefined when not today). */
+  nowFraction?: number;
+}
+
+export type TimelineRow =
+  | { type: "day"; day: TimelineDay }
+  | { type: "gap"; count: number };
+
+/** Weekday-day-month heading in the browser locale (matches the server tz
+ *  bucketing, since usePageWorkTime requests buckets in the viewer tz). */
+export function dayHeading(day: number): string {
+  return new Date(day).toLocaleDateString(undefined, {
+    weekday: "short",
+    day: "numeric",
+    month: "short",
+  });
+}
+
+/** Map one day's absolute windows into time-of-day blocks. `class` work|agent_only
+ *  → kind work|agent; positions are the in-day hour fraction (epoch kept for the
+ *  tooltip). Fractions are clamped to [0,24] to match the original punch-card. */
+export function toBlocks(day: IPerDay): TimelineBlock[] {
+  return day.windows.map((w: IDayWindow) => {
+    const start = clampHour((w.start - day.day) / (DAY_MS / 24));
+    const end = clampHour((w.end - day.day) / (DAY_MS / 24));
+    return {
+      start,
+      end,
+      kind: w.class === "work" ? "work" : "agent",
+      startEpoch: w.start,
+      endEpoch: w.end,
+    };
+  });
+}
+
+function clampHour(h: number): number {
+  return Math.max(0, Math.min(24, h));
+}
+
+/** Build a single render-ready day. `now` is injected for testability; the
+ *  "now" boundary is drawn only when `now` falls inside this bucket's calendar
+ *  day (so it appears on today's row and only when today has edits). */
+export function toTimelineDay(
+  day: IPerDay,
+  t: Translate,
+  now: number,
+): TimelineDay {
+  const isToday = now >= day.day && now < day.day + DAY_MS;
+  return {
+    key: day.dayISO,
+    label: dayHeading(day.day),
+    totalLabel: formatDayTotal(day.activeMs, t),
+    blocks: toBlocks(day),
+    isEmpty: day.activeMs === 0 && day.agentMs === 0,
+    isToday,
+    nowFraction: isToday ? (now - day.day) / DAY_MS : undefined,
+  };
+}
+
+/** Collapse long edit-free runs (≥ EMPTY_RUN_COLLAPSE) into an in-place "gap"
+ *  row; short runs stay as (dimmed, "—") day rows. Preserved from the original
+ *  punch-card so a page edited over months does not render hundreds of rows. */
+export function buildRows(
+  perDay: IPerDay[],
+  t: Translate,
+  now: number,
+): TimelineRow[] {
+  const rows: TimelineRow[] = [];
+  let emptyRun: IPerDay[] = [];
+  const flush = () => {
+    if (emptyRun.length >= EMPTY_RUN_COLLAPSE) {
+      rows.push({ type: "gap", count: emptyRun.length });
+    } else {
+      for (const d of emptyRun) {
+        rows.push({ type: "day", day: toTimelineDay(d, t, now) });
+      }
+    }
+    emptyRun = [];
+  };
+  for (const d of perDay) {
+    if (d.activeMs === 0 && d.agentMs === 0) {
+      emptyRun.push(d);
+    } else {
+      flush();
+      rows.push({ type: "day", day: toTimelineDay(d, t, now) });
+    }
+  }
+  flush();
+  return rows;
+}
+
+/** The big summary slot. Fail-safe for an agent-only page (#395/#551): since
+ *  formatHeadline(0) === "", never leave the 22px slot empty — put the agent
+ *  estimate in the main slot, and only show the secondary `agent:` line when
+ *  BOTH a human and an agent estimate exist. */
+export function summaryLabels(
+  data: IPageWorkTime,
+  t: Translate,
+): { total: string; agent?: string } {
+  const total =
+    data.workMs > 0
+      ? formatHeadline(data.workMs, t)
+      : t("agent: {{value}}", { value: formatHeadline(data.agentOnlyMs, t) });
+  const agent =
+    data.workMs > 0 && data.agentOnlyMs > 0
+      ? formatHeadline(data.agentOnlyMs, t)
+      : undefined;
+  return { total, agent };
+}
+
+/** Block hover label "start – end · duration". Times come from the REAL epoch
+ *  rendered in the data tz (NOT the 24h fraction) so a DST-transition day does
+ *  not skew the shown clock time. Duration reuses formatDayTotal (always > 0
+ *  here, so never "—"). */
+export function formatBlockTooltip(
+  block: TimelineBlock,
+  tz: string,
+  locale: string,
+  t: Translate,
+): string {
+  const fmt = new Intl.DateTimeFormat(locale || undefined, {
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+    timeZone: tz,
+  });
+  return t("{{start}} – {{end}} · {{duration}}", {
+    start: fmt.format(block.startEpoch),
+    end: fmt.format(block.endEpoch),
+    duration: formatDayTotal(block.endEpoch - block.startEpoch, t),
+  });
+}

apps/client/src/features/page-history/work-time/work-time-punch-card.tsx

@@ -1,97 +1,86 @@
-import { Group, Stack, Text } from "@mantine/core";
+// #566 — redesigned "Time worked" body: daily time-of-day timelines. Each day is
+// a 24h track showing WHEN the work happened — a sticky 00/06/12/18/24 hour axis,
+// shaded night hours, per-block hover tooltip ("start – end · duration"), and a
+// "now" boundary on today's row. Presentation ported from NewDesign/TimeWorkedModal;
+// all data comes through the pure adapter over the real IPageWorkTime (zero backend
+// change). Positioning math, empty-run collapsing and the formatters are reused.
+import { Box, Group, ScrollArea, Stack, Text, Tooltip } from "@mantine/core";
 import { useTranslation } from "react-i18next";
 import { useMemo } from "react";
-import { IPageWorkTime, IPerDay, IDayWindow } from "./work-time.types";
+import { IPageWorkTime } from "./work-time.types";
+import { formatGapMinutes } from "./format-work-time";
 import {
-  formatDayTotal,
-  formatGapMinutes,
-  formatHeadline,
-} from "./format-work-time";
+  buildRows,
+  formatBlockTooltip,
+  summaryLabels,
+  TimelineBlock,
+  TimelineDay,
+} from "./work-time-adapter";
 import classes from "./work-time.module.css";
 
-const DAY_MS = 24 * 60 * 60 * 1000;
-// Collapse a run of this many (or more) consecutive edit-free days into a single
-// "× N days" separator (§6.2 long-range) — the row is still always one day.
-const EMPTY_RUN_COLLAPSE = 8;
+// Minimum visible width so a very short session neither vanishes nor fakes dense
+// work (§6.2); kept from the original punch-card.
+const MIN_BLOCK_WIDTH_PCT = 0.6;
 
-type Row =
-  | { type: "day"; day: IPerDay }
-  | { type: "gap"; count: number };
-
-function collapseEmptyRuns(perDay: IPerDay[]): Row[] {
-  const rows: Row[] = [];
-  let emptyRun: IPerDay[] = [];
-  const flush = () => {
-    if (emptyRun.length >= EMPTY_RUN_COLLAPSE) {
-      rows.push({ type: "gap", count: emptyRun.length });
-    } else {
-      for (const d of emptyRun) rows.push({ type: "day", day: d });
-    }
-    emptyRun = [];
-  };
-  for (const d of perDay) {
-    if (d.activeMs === 0 && d.agentMs === 0) {
-      emptyRun.push(d);
-    } else {
-      flush();
-      rows.push({ type: "day", day: d });
-    }
-  }
-  flush();
-  return rows;
-}
-
-function dayHeading(day: number): string {
-  return new Date(day).toLocaleDateString(undefined, {
-    weekday: "short",
-    day: "numeric",
-    month: "short",
-  });
+function ActivityBlock({
+  block,
+  tz,
+  locale,
+}: {
+  block: TimelineBlock;
+  tz: string;
+  locale: string;
+}) {
+  const { t } = useTranslation();
+  const left = (block.start / 24) * 100;
+  const width = Math.max(((block.end - block.start) / 24) * 100, MIN_BLOCK_WIDTH_PCT);
+  const cls = [
+    classes.window,
+    block.kind === "work" ? classes.windowWork : classes.windowAgent,
+  ].join(" ");
+  return (
+    <Tooltip
+      label={formatBlockTooltip(block, tz, locale, t)}
+      withArrow
+      openDelay={120}
+      fz={11}
+    >
+      <div className={cls} style={{ left: `${left}%`, width: `${width}%` }} />
+    </Tooltip>
+  );
 }
 
 function DayTrack({
   day,
-  pSingle,
+  tz,
+  locale,
 }: {
-  day: IPerDay;
-  pSingle: number;
+  day: TimelineDay;
+  tz: string;
+  locale: string;
 }) {
-  const { t } = useTranslation();
-  const ticks = [6, 12, 18];
   return (
     <div className={classes.row}>
-      <span className={classes.dayLabel}>{dayHeading(day.day)}</span>
-      <div className={classes.track}>
-        {ticks.map((h) => (
-          <div
-            key={h}
-            className={classes.hourTick}
-            style={{ left: `${(h / 24) * 100}%` }}
-          />
+      <span className={classes.dayLabel}>{day.label}</span>
+      <div className={`${classes.track} ${day.isEmpty ? classes.trackEmpty : ""}`}>
+        {[25, 50, 75].map((p) => (
+          <div key={p} className={classes.hourTick} style={{ left: `${p}%` }} />
         ))}
-        {day.windows.map((w: IDayWindow, i) => {
-          const leftPct = ((w.start - day.day) / DAY_MS) * 100;
-          const widthPct = ((w.end - w.start) / DAY_MS) * 100;
-          const isSingle = w.end - w.start <= pSingle;
-          const cls = [
-            classes.window,
-            w.class === "work" ? classes.windowWork : classes.windowAgent,
-            isSingle ? classes.windowSingle : "",
-          ].join(" ");
-          return (
-            <div
-              key={i}
-              className={cls}
-              style={{
-                left: `${Math.max(0, Math.min(100, leftPct))}%`,
-                width: `${Math.max(0, Math.min(100, widthPct))}%`,
-              }}
-            />
-          );
-        })}
+        {day.blocks.map((b, i) => (
+          <ActivityBlock key={i} block={b} tz={tz} locale={locale} />
+        ))}
+        {day.isToday && day.nowFraction != null && (
+          <div
+            className={classes.nowLine}
+            style={{ left: `${day.nowFraction * 100}%` }}
+          />
+        )}
       </div>
-      <span className={classes.daySum}>
-        {formatDayTotal(day.activeMs, t)}
+      <span
+        className={classes.daySum}
+        data-empty={day.totalLabel === "—" ? true : undefined}
+      >
+        {day.totalLabel}
       </span>
     </div>
   );
@@ -102,8 +91,16 @@ interface Props {
 }
 
 export default function WorkTimePunchCard({ data }: Props) {
-  const { t } = useTranslation();
-  const rows = useMemo(() => collapseEmptyRuns(data.perDay), [data.perDay]);
+  const { t, i18n } = useTranslation();
+  const locale = i18n.language;
+  const now = Date.now();
+  const rows = useMemo(
+    () => buildRows(data.perDay, t, now),
+    // `now` intentionally re-read on each open; excluded so the memo tracks data.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [data.perDay, t],
+  );
+  const { total, agent } = summaryLabels(data, t);
   const gapMin = formatGapMinutes(data.config.tGap);
 
   if (data.workMs <= 0 && data.agentOnlyMs <= 0) {
@@ -116,17 +113,19 @@ export default function WorkTimePunchCard({ data }: Props) {
 
   return (
     <Stack gap="xs">
-      <Group gap="lg">
-        <Text size="sm" fw={500}>
-          {formatHeadline(data.workMs, t)}
+      {/* summary */}
+      <Group align="baseline" gap="md">
+        <Text fz={22} fw={700}>
+          {total}
         </Text>
-        {data.agentOnlyMs > 0 && (
+        {agent && (
           <Text size="xs" c="dimmed">
-            {t("agent: {{value}}", { value: formatHeadline(data.agentOnlyMs, t) })}
+            {t("agent: {{value}}", { value: agent })}
           </Text>
         )}
       </Group>
 
+      {/* legend */}
       <Group gap="md">
         <Text size="xs" c="dimmed">
           <span
@@ -144,21 +143,47 @@ export default function WorkTimePunchCard({ data }: Props) {
         </Text>
       </Group>
 
-      <div>
+      {/* sticky hour axis */}
+      <div className={`${classes.row} ${classes.axisRow}`}>
+        <span />
+        <div className={classes.axis}>
+          {[
+            ["0%", "00", "start"],
+            ["25%", "06", "center"],
+            ["50%", "12", "center"],
+            ["75%", "18", "center"],
+            ["100%", "24", "end"],
+          ].map(([l, label, align]) => (
+            <span
+              key={label}
+              className={classes.axisTick}
+              data-align={align}
+              style={{ left: l }}
+            >
+              {label}
+            </span>
+          ))}
+        </div>
+        <span />
+      </div>
+
+      {/* day rows */}
+      <ScrollArea.Autosize mah="60vh" type="hover">
         {rows.map((row, i) =>
           row.type === "day" ? (
             <DayTrack
-              key={row.day.dayISO}
+              key={row.day.key}
               day={row.day}
-              pSingle={data.config.pSingle}
+              tz={data.tz}
+              locale={locale}
             />
           ) : (
-            <div key={`gap-${i}`} className={classes.gapRow}>
+            <Box key={`gap-${i}`} className={classes.gapRow}>
               {t("× {{count}} days without edits", { count: row.count })}
-            </div>
+            </Box>
           ),
         )}
-      </div>
+      </ScrollArea.Autosize>
 
       <Text size="xs" c="dimmed" mt="xs">
         {t("Estimate · timezone {{tz}} · inactivity gap {{gap}} min", {

apps/client/src/features/page-history/work-time/work-time-stat.tsx

@@ -60,7 +60,7 @@ export default function WorkTimeStat({ pageId }: Props) {
         opened={opened}
         onClose={close}
         title={t("Time worked on this article")}
-        size="lg"
+        size="46rem"
       >
         <WorkTimePunchCard data={data} />
       </Modal>

apps/client/src/features/page-history/work-time/work-time.module.css

@@ -1,5 +1,7 @@
-/* #395 — 24h × days punch-card. Custom CSS segments on a fixed 24-hour track
-   (position = offset-in-day / 24h, width = duration / 24h), no chart library. */
+/* #566 — time-of-day timeline. Custom CSS segments on a fixed 24-hour track
+   (position = offset-in-day / 24h, width = duration / 24h), no chart library.
+   Night hours (0–6, 21–24) are shaded so the eye reads morning-vs-evening; a
+   sticky hour axis labels 00/06/12/18/24. Theme-aware via Mantine tokens. */
 
 .row {
   display: grid;
@@ -16,17 +18,29 @@
 }
 
 .track {
+  --wt-night: rgba(90, 100, 130, 0.16);
+  --wt-day: rgba(90, 100, 130, 0.03);
   position: relative;
-  height: 16px;
-  border-radius: 4px;
-  background-color: light-dark(
-    var(--mantine-color-gray-1),
-    var(--mantine-color-dark-6)
-  );
+  height: 20px;
+  border-radius: 5px;
   overflow: hidden;
+  /* base fill + night shading: 0–6h and 21–24h (87.5%) darker than daytime */
+  background:
+    linear-gradient(
+      90deg,
+      var(--wt-night) 0 25%,
+      var(--wt-day) 25% 87.5%,
+      var(--wt-night) 87.5% 100%
+    ),
+    light-dark(var(--mantine-color-gray-1), var(--mantine-color-dark-6));
 }
 
-/* Faint hour grid so the eye can read "morning vs evening". */
+/* Short (< EMPTY_RUN_COLLAPSE) edit-free days: dimmed, empty track. */
+.trackEmpty {
+  opacity: 0.5;
+}
+
+/* Quarter-day grid divisions (06/12/18) inside the track. */
 .hourTick {
   position: absolute;
   top: 0;
@@ -40,10 +54,11 @@
 
 .window {
   position: absolute;
-  top: 2px;
-  bottom: 2px;
+  top: 3px;
+  height: 14px;
   border-radius: 3px;
   min-width: 3px;
+  cursor: default;
 }
 
 .windowWork {
@@ -54,18 +69,57 @@
   background-color: var(--mantine-color-grape-5);
 }
 
-/* A lone single-sample (P_single) window: minimal + dimmed, so it neither
-   vanishes nor fakes dense work (§6.2). */
-.windowSingle {
-  opacity: 0.5;
+/* The "now" boundary on today's row. */
+.nowLine {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background-color: var(--mantine-color-red-6);
 }
 
 .daySum {
   font-size: var(--mantine-font-size-xs);
+  font-weight: 500;
   text-align: right;
   white-space: nowrap;
 }
 
+.daySum[data-empty] {
+  color: var(--mantine-color-dimmed);
+  font-weight: 400;
+}
+
+/* Sticky hour axis header aligned to the track column. */
+.axisRow {
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  background-color: var(--mantine-color-body);
+  padding-bottom: 2px;
+}
+
+.axis {
+  position: relative;
+  height: 14px;
+}
+
+.axisTick {
+  position: absolute;
+  top: 0;
+  font-size: 10px;
+  font-weight: 500;
+  color: var(--mantine-color-dimmed);
+}
+
+.axisTick[data-align="center"] {
+  transform: translateX(-50%);
+}
+
+.axisTick[data-align="end"] {
+  transform: translateX(-100%);
+}
+
 .gapRow {
   padding: 6px 0 6px 108px;
   font-size: var(--mantine-font-size-xs);

apps/client/src/features/page/queries/page-query.ts

@@ -665,6 +665,13 @@ export function updateCacheOnMovePage(
   pageData: Partial<IPage>,
 ) {
   invalidatePageTree();
+  // Invalidate the moved page's breadcrumbs (#523). The tree-side child-loss
+  // guard removes the moved node from the local tree when its new parent is an
+  // unloaded branch, so `findBreadcrumbPath` misses it and the breadcrumb bar
+  // falls back to the server `["breadcrumbs", pageId]` query — which this move
+  // must invalidate, otherwise the crumbs keep showing the OLD parent until a
+  // refocus/navigation.
+  queryClient.invalidateQueries({ queryKey: ["breadcrumbs", pageId] });
   // Remove page from old parent's cache
   const oldQueryKey =
     oldParentId === null

apps/client/src/features/page/queries/update-cache-on-move.breadcrumbs.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import type { IPage } from "@/features/page/types/page.types";
+
+// A fresh QueryClient stands in for the app singleton (importing the real
+// @/main.tsx would run ReactDOM.createRoot, which has no DOM root in jsdom).
+vi.mock("@/main.tsx", async () => {
+  const { QueryClient } = await import("@tanstack/react-query");
+  return { queryClient: new QueryClient() };
+});
+
+import { queryClient } from "@/main.tsx";
+import { updateCacheOnMovePage } from "./page-query";
+
+// #523: the tree-side child-loss guard removes the moved node from the local
+// tree when its new parent is an unloaded branch, so `findBreadcrumbPath` misses
+// it and the breadcrumb bar falls back to the server `["breadcrumbs", pageId]`
+// query. That query MUST be invalidated by a move, or the crumbs keep showing
+// the OLD parent until a refocus/navigation.
+describe("updateCacheOnMovePage — breadcrumbs invalidation (#523)", () => {
+  beforeEach(() => {
+    queryClient.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("invalidates the moved page's ['breadcrumbs', pageId] query", () => {
+    const spy = vi.spyOn(queryClient, "invalidateQueries");
+
+    updateCacheOnMovePage("s1", "moved-page", "old-parent", "new-parent", {
+      id: "moved-page",
+    } as Partial<IPage>);
+
+    const invalidatedBreadcrumbs = spy.mock.calls.some(
+      ([arg]) =>
+        Array.isArray((arg as { queryKey?: unknown[] })?.queryKey) &&
+        (arg as { queryKey: unknown[] }).queryKey[0] === "breadcrumbs" &&
+        (arg as { queryKey: unknown[] }).queryKey[1] === "moved-page",
+    );
+    expect(invalidatedBreadcrumbs).toBe(true);
+  });
+});

apps/client/src/features/page/tree/components/doc-tree-row.tsx

@@ -55,7 +55,14 @@ type Props<T extends object> = {
 };
 
 const DRAG_TYPE = 'doc-tree-item';
-const AUTO_EXPAND_MS = 500;
+// Hover-hold before a collapsed row auto-expands during a drag. 2s (not ~0.5s)
+// so merely dragging the cursor THROUGH the tree never expands rows — only a
+// deliberate hold does (#523).
+const AUTO_EXPAND_MS = 2000;
+// How long the "a page just moved in here" cue stays on a collapsed target after
+// a make-child drop. Long enough to notice at a glance during frequent
+// collapsed-drops, short enough not to linger. Code-only UX constant (#523).
+const DROP_LANDED_HIGHLIGHT_MS = 1800;
 
 function DocTreeRowInner<T extends object>(props: Props<T>) {
   const {
@@ -93,7 +100,11 @@ function DocTreeRowInner<T extends object>(props: Props<T>) {
   const rowRef = useRef<HTMLElement>(null);
   const [isDragging, setIsDragging] = useState(false);
   const [instruction, setInstruction] = useState<Instruction | null>(null);
+  // Transient "just received a child" cue: a make-child drop no longer expands
+  // the (collapsed) target, so flash the row instead so the move isn't invisible.
+  const [landedChild, setLandedChild] = useState(false);
   const autoExpandTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const landedChildTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const cancelAutoExpand = useCallback(() => {
     if (autoExpandTimerRef.current) {
@@ -249,11 +260,24 @@ function DocTreeRowInner<T extends object>(props: Props<T>) {
               ? getDragLabel(sourceNode)
               : 'item';
             liveRegion.announce(`Moved ${sourceLabel} under ${parentName}.`);
-            // After a make-child drop, expand this row so the user sees the
-            // just-dropped child — especially important when the row had no
-            // children before (chevron just appeared) so the drop would
-            // otherwise be invisible.
-            if (op.kind === 'make-child') onToggle(node.id, true);
+            // Do NOT auto-expand the target on drop: a drop must leave the node
+            // collapsed. Intentional expansion is handled solely by the
+            // hover-hold timer (AUTO_EXPAND_MS). Feedback that the drop landed is
+            // given by the post-move flash + landed-cue highlight + live-region
+            // announce above. When the make-child target is collapsed, flash a
+            // distinct "child moved in here" cue on the row (it stays collapsed).
+            if (op.kind === 'make-child' && !isOpen) {
+              if (landedChildTimerRef.current) {
+                clearTimeout(landedChildTimerRef.current);
+              }
+              setLandedChild(true);
+              landedChildTimerRef.current = setTimeout(() => {
+                setLandedChild(false);
+                landedChildTimerRef.current = null;
+              }, DROP_LANDED_HIGHLIGHT_MS);
+            }
+            // Restore the openness of the MOVED page itself (source) — untouched
+            // by the above; the target is never expanded here.
             if (source.data.isOpenOnDragStart) onToggle(sourceId, true);
           },
         }),
@@ -281,6 +305,17 @@ function DocTreeRowInner<T extends object>(props: Props<T>) {
 
   useEffect(() => () => cancelAutoExpand(), [cancelAutoExpand]);
 
+  // Clear the landed-child cue timer on unmount (mirrors autoExpandTimerRef).
+  useEffect(
+    () => () => {
+      if (landedChildTimerRef.current) {
+        clearTimeout(landedChildTimerRef.current);
+        landedChildTimerRef.current = null;
+      }
+    },
+    [],
+  );
+
   const effectiveInst =
     instruction?.type === 'instruction-blocked'
       ? instruction.desired
@@ -317,6 +352,7 @@ function DocTreeRowInner<T extends object>(props: Props<T>) {
         className={styles.node}
         data-dragging={isDragging || undefined}
         data-selected={isSelected || undefined}
+        data-landed-child={landedChild || undefined}
         data-receiving-drop={
           receivingDrop === 'make-child'
             ? blocked

apps/client/src/features/page/tree/hooks/use-tree-mutation.move-guard.test.tsx

@@ -0,0 +1,149 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { Provider, createStore } from "jotai";
+import type { ReactNode } from "react";
+
+import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
+import { treeModel } from "@/features/page/tree/model/tree-model";
+import type { SpaceTreeNode } from "@/features/page/tree/types";
+
+// --- Boundary mocks: only the network/query + router/i18n surfaces the hook
+// touches. The tree math (treeModel, dropOpToMovePayload) runs for real so the
+// child-loss guard is exercised end-to-end.
+const moveMutate = vi.fn().mockResolvedValue({});
+const updateCacheOnMovePageMock = vi.fn();
+vi.mock("@/features/page/queries/page-query.ts", () => ({
+  useCreatePageMutation: () => ({ mutateAsync: vi.fn() }),
+  useUpdatePageMutation: () => ({ mutateAsync: vi.fn() }),
+  useRemovePageMutation: () => ({ mutateAsync: vi.fn() }),
+  useMovePageMutation: () => ({ mutateAsync: moveMutate }),
+  updateCacheOnMovePage: (...args: unknown[]) =>
+    updateCacheOnMovePageMock(...args),
+}));
+vi.mock("react-router-dom", () => ({
+  useNavigate: () => vi.fn(),
+  useParams: () => ({ spaceSlug: "space", pageSlug: undefined }),
+}));
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (s: string) => s }),
+}));
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn() },
+}));
+
+// Import AFTER mocks so the hook binds to them.
+import { useTreeMutation } from "./use-tree-mutation";
+
+function node(
+  id: string,
+  over: Partial<SpaceTreeNode> = {},
+): SpaceTreeNode {
+  return {
+    id,
+    slugId: `slug-${id}`,
+    name: id.toUpperCase(),
+    position: "a0",
+    spaceId: "space-1",
+    parentPageId: null as unknown as string,
+    hasChildren: false,
+    children: [],
+    ...over,
+  };
+}
+
+function setup(before: SpaceTreeNode[]) {
+  const store = createStore();
+  store.set(treeDataAtom, before);
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <Provider store={store}>{children}</Provider>
+  );
+  const { result } = renderHook(() => useTreeMutation("space-1"), { wrapper });
+  return { store, result };
+}
+
+describe("useTreeMutation.handleMove — child-loss guard (#523)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    moveMutate.mockResolvedValue({});
+  });
+
+  it("make-child into an UNLOADED folder does NOT materialize [source] — keeps it lazy-loadable", async () => {
+    // F has children on the server but none are loaded here (canonical unloaded
+    // form: hasChildren + children:[]). X sits at root.
+    const before = [
+      node("F", { position: "a0", hasChildren: true, children: [] }),
+      node("X", { position: "a5" }),
+    ];
+    const { store, result } = setup(before);
+
+    await act(async () => {
+      await result.current.handleMove("X", {
+        kind: "make-child",
+        targetId: "F",
+      });
+    });
+
+    const tree = store.get(treeDataAtom);
+    const f = treeModel.find(tree, "F");
+    // The guard leaves F unloaded (children stay []), so a later expand fetches
+    // the FULL server set (incl. X) instead of showing a misleading partial [X].
+    // MUTATION: dropping the guard (using the `move` result) would put children
+    // === [X] here and redden this.
+    expect(f?.children).toEqual([]);
+    expect(f?.hasChildren).toBe(true);
+    // X is removed from its old (root) slot; it reappears on expand/load of F.
+    expect(treeModel.find(tree, "X")).toBeNull();
+    // The server move is still persisted.
+    expect(moveMutate).toHaveBeenCalledTimes(1);
+  });
+
+  it("make-child into a LOADED folder appends source and KEEPS the existing children", async () => {
+    // F is loaded with one child c1; moving X in must preserve c1 (no loss) and
+    // append X — this path does NOT hit the guard.
+    const before = [
+      node("F", {
+        position: "a0",
+        hasChildren: true,
+        children: [node("c1", { position: "a1", parentPageId: "F" })],
+      }),
+      node("X", { position: "a5" }),
+    ];
+    const { store, result } = setup(before);
+
+    await act(async () => {
+      await result.current.handleMove("X", {
+        kind: "make-child",
+        targetId: "F",
+      });
+    });
+
+    const tree = store.get(treeDataAtom);
+    const f = treeModel.find(tree, "F");
+    expect(f?.children?.map((n) => n.id)).toEqual(["c1", "X"]);
+    expect(f?.hasChildren).toBe(true);
+    // X now lives under F.
+    expect(treeModel.find(tree, "X")?.parentPageId).toBe("F");
+  });
+
+  it("make-child into a genuinely-empty leaf materializes the child (nothing to lose)", async () => {
+    // Leaf L has no server children (hasChildren:false). Dropping X in should
+    // show X immediately — the guard must NOT fire here.
+    const before = [
+      node("L", { position: "a0", hasChildren: false, children: [] }),
+      node("X", { position: "a5" }),
+    ];
+    const { store, result } = setup(before);
+
+    await act(async () => {
+      await result.current.handleMove("X", {
+        kind: "make-child",
+        targetId: "L",
+      });
+    });
+
+    const tree = store.get(treeDataAtom);
+    const l = treeModel.find(tree, "L");
+    expect(l?.children?.map((n) => n.id)).toEqual(["X"]);
+    expect(l?.hasChildren).toBe(true);
+  });
+});

apps/client/src/features/page/tree/hooks/use-tree-mutation.ts

@@ -61,11 +61,48 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
       if (!source) return;
       const oldParentId = source.parentPageId ?? null;
 
-      // optimistic apply with the new position from the payload
-      let optimistic = treeModel.update(after, sourceId, {
-        position: payload.position,
-        parentPageId: payload.parentPageId,
-      } as Partial<SpaceTreeNode>);
+      // Child-loss guard (#523, twin of #525's realtime `insertByPosition` fix).
+      // We no longer auto-expand the make-child target on drop, so the old
+      // `onToggle(target, true)` — which was ALSO the only trigger of the
+      // corrective lazy-load — is gone. `treeModel.move` materialized
+      // `target.children = [source]` (only the moved node); if the target is an
+      // UNLOADED branch (server has children but none are loaded here), keeping
+      // that partial `[source]` list would defeat the lazy-load gate and hide the
+      // target's OTHER server children (the #159 #1 data-loss class). So for an
+      // unloaded make-child target, build the optimistic tree WITHOUT
+      // materializing source under it: just remove source from its old parent and
+      // flag the target `hasChildren`. The gate stays armed and a later manual
+      // expand fetches the FULL set (incl. the moved page, which the awaited
+      // server move persists). Predicate is the gate's (`isUnloadedBranch`), NOT
+      // `insertByPosition`'s old `=== undefined` (canonical unloaded is `[]`).
+      const target =
+        op.kind === "make-child"
+          ? (treeModel.find(before, op.targetId) as SpaceTreeNode | null)
+          : null;
+      const unloadedMakeChild =
+        op.kind === "make-child" && treeModel.isUnloadedBranch(target);
+
+      let optimistic: SpaceTreeNode[];
+      if (unloadedMakeChild) {
+        // Do NOT materialize [source] into the unloaded target.
+        optimistic = treeModel.remove(before, sourceId);
+        optimistic = treeModel.update(optimistic, op.targetId, {
+          hasChildren: true,
+        } as Partial<SpaceTreeNode>);
+      } else {
+        // optimistic apply with the new position from the payload
+        optimistic = treeModel.update(after, sourceId, {
+          position: payload.position,
+          parentPageId: payload.parentPageId,
+        } as Partial<SpaceTreeNode>);
+        // For make-child onto a previously-childless (loaded) target: flip
+        // hasChildren on so the new parent shows its chevron.
+        if (op.kind === "make-child") {
+          optimistic = treeModel.update(optimistic, op.targetId, {
+            hasChildren: true,
+          } as Partial<SpaceTreeNode>);
+        }
+      }
 
       // If the old parent has no children left, mark hasChildren: false so the
       // chevron disappears. Without this, the empty parent keeps rendering an
@@ -79,14 +116,6 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
         }
       }
 
-      // For make-child onto a previously-childless target: flip hasChildren on
-      // so the new parent shows its chevron.
-      if (op.kind === "make-child") {
-        optimistic = treeModel.update(optimistic, op.targetId, {
-          hasChildren: true,
-        } as Partial<SpaceTreeNode>);
-      }
-
       setData(optimistic);
 
       try {

apps/client/src/features/page/tree/styles/tree.module.css

@@ -150,6 +150,45 @@
     );
 }
 
+/* "A page just moved in here" cue (#523). A make-child drop no longer expands
+   the collapsed target, so the moved page is momentarily invisible; pulse the
+   target row in a distinct teal (NOT the blue make-child highlight, NOT the
+   neutral post-move flash) so the landing is noticeable while the node stays
+   collapsed. Two short pulses fit inside DROP_LANDED_HIGHLIGHT_MS (1.8s), after
+   which the row clears the attribute and the animation stops. */
+@keyframes landedChildPulse {
+    0% {
+        background-color: light-dark(
+            var(--mantine-color-teal-2),
+            rgba(45, 212, 191, 0.30)
+        );
+        outline-color: light-dark(
+            var(--mantine-color-teal-6),
+            var(--mantine-color-teal-5)
+        );
+    }
+    100% {
+        background-color: transparent;
+        outline-color: transparent;
+    }
+}
+
+.node[data-landed-child="true"] {
+    outline: 2px solid transparent;
+    outline-offset: -1px;
+    animation: landedChildPulse 0.9s ease-out 2;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .node[data-landed-child="true"] {
+        animation: none;
+        background-color: light-dark(
+            var(--mantine-color-teal-1),
+            rgba(45, 212, 191, 0.18)
+        );
+    }
+}
+
 .dropLine {
     position: absolute;
     left: var(--drop-line-indent, 0);

apps/client/src/lib/copy-to-clipboard.ts

@@ -14,3 +14,19 @@ export function execCommandCopy(text: string): void {
   document.execCommand("copy");
   document.body.removeChild(textarea);
 }
+
+// Stateless one-shot copy: write `text` to the clipboard without ever storing it
+// in React state (unlike useClipboard, which keeps a `copied` flag AND holds the
+// last value). Used by the api-key reveal/copy flow, where the secret must touch
+// nothing but the clipboard — no component state, no cache, no localStorage.
+export async function copyToClipboard(text: string): Promise<void> {
+  if (typeof navigator !== "undefined" && "clipboard" in navigator) {
+    try {
+      await navigator.clipboard.writeText(text);
+      return;
+    } catch {
+      // Fall through to the execCommand fallback (e.g. insecure context).
+    }
+  }
+  execCommandCopy(text);
+}

apps/client/src/lib/telemetry/route-template.ts

@@ -36,6 +36,7 @@ const STATIC_ROUTES = new Set<string>([
   '/setup/register',
   '/settings/account/profile',
   '/settings/account/preferences',
+  '/settings/account/api-keys',
   '/settings/workspace',
   '/settings/ai',
   '/settings/members',

apps/client/src/pages/settings/account/account-api-keys.tsx

@@ -0,0 +1,22 @@
+import SettingsTitle from "@/components/settings/settings-title.tsx";
+import ApiKeysManager from "@/features/api-key/components/api-keys-manager";
+import { getAppName } from "@/lib/config.ts";
+import { Helmet } from "react-helmet-async";
+import { useTranslation } from "react-i18next";
+
+export default function AccountApiKeys() {
+  const { t } = useTranslation();
+
+  return (
+    <>
+      <Helmet>
+        <title>
+          {t("API keys")} - {getAppName()}
+        </title>
+      </Helmet>
+      <SettingsTitle title={t("API keys")} />
+
+      <ApiKeysManager />
+    </>
+  );
+}

apps/client/vitest.setup.ts

@@ -63,3 +63,15 @@ vi.stubGlobal("matchMedia", (query: string) => ({
   removeEventListener: vi.fn(),
   dispatchEvent: vi.fn(),
 }));
+
+// Mantine's ScrollArea (used by Table.ScrollContainer, ScrollArea, etc.) reads
+// `ResizeObserver` in a layout effect on mount, which jsdom does not implement.
+// A no-op stub lets any test rendering those components mount cleanly.
+vi.stubGlobal(
+  "ResizeObserver",
+  class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  },
+);

apps/server/src/common/events/audit-events.ts

@@ -22,6 +22,9 @@ export const AuditEvent = {
   API_KEY_CREATED: 'api_key.created',
   API_KEY_UPDATED: 'api_key.updated',
   API_KEY_DELETED: 'api_key.deleted',
+  // A copyable key was re-minted and returned to its owner under a password
+  // step-up (see ApiKeyController.reveal). Durable via DatabaseAuditService.
+  API_KEY_REVEALED: 'api_key.revealed',
 
   // SCIM Tokens
   SCIM_TOKEN_CREATED: 'scim_token.created',

apps/server/src/core/ai-chat/embedding/embedding-indexer.service.spec.ts

@@ -32,6 +32,14 @@ describe('EmbeddingIndexerService.reindexWorkspace fail-fast', () => {
     const pageEmbeddingRepo = {};
     const aiService = {
       getEmbeddingModel: jest.fn().mockResolvedValue('some-model'),
+      // #530: reindexWorkspace's pre-check now resolves the provider (workspace
+      // or global). Resolve it so the batch control flow under test proceeds.
+      resolveEmbeddingProvider: jest.fn().mockResolvedValue({
+        model: 'some-model',
+        queryPrefix: '',
+        docPrefix: '',
+        fingerprint: 'fp-test',
+      }),
     };
     // Progress is a best-effort cosmetic store; mock its async methods so the
     // batch control flow can be tested without Redis.
@@ -108,6 +116,14 @@ describe('EmbeddingIndexerService.reindexWorkspace progress', () => {
     const pageEmbeddingRepo = {};
     const aiService = {
       getEmbeddingModel: jest.fn().mockResolvedValue('some-model'),
+      // #530: reindexWorkspace's pre-check now resolves the provider (workspace
+      // or global). Resolve it so the batch control flow under test proceeds.
+      resolveEmbeddingProvider: jest.fn().mockResolvedValue({
+        model: 'some-model',
+        queryPrefix: '',
+        docPrefix: '',
+        fingerprint: 'fp-test',
+      }),
     };
     const reindexProgress = {
       start: jest.fn().mockResolvedValue(undefined),
@@ -174,7 +190,7 @@ describe('EmbeddingIndexerService.reindexWorkspace progress', () => {
     const { service, aiService, reindexProgress } = makeService();
     // Embeddings not configured: reindexWorkspace returns early WITHOUT starting
     // a fresh record, but the finally must still clear the enqueue-time seed.
-    aiService.getEmbeddingModel = jest
+    aiService.resolveEmbeddingProvider = jest
       .fn()
       .mockRejectedValue(new AiEmbeddingNotConfiguredException());
 
@@ -187,3 +203,87 @@ describe('EmbeddingIndexerService.reindexWorkspace progress', () => {
     expect(reindexProgress.clear).toHaveBeenCalledWith(WORKSPACE_ID);
   });
 });
+
+/**
+ * #530 PR-1: reindexPage must (a) prepend the provider's DOC prefix to each chunk
+ * BEFORE embedding (so stored vectors live in the same prefixed space as a
+ * prefixed query), and (b) stamp the ACTIVE fingerprint on every inserted row (so
+ * search only fuses same-generation vectors). Uses lightweight mocks; the tx is
+ * stubbed to run its callback inline.
+ */
+describe('EmbeddingIndexerService.reindexPage doc-prefix + fingerprint (#530)', () => {
+  const WORKSPACE_ID = 'ws-1';
+  const SPACE_ID = 'space-1';
+  const PAGE_ID = 'page-1';
+
+  function makeService(docPrefix: string) {
+    const pageRepo = {
+      findById: jest.fn().mockResolvedValue({
+        id: PAGE_ID,
+        workspaceId: WORKSPACE_ID,
+        spaceId: SPACE_ID,
+        title: 'Заголовок',
+        // No ProseMirror content -> the plain-text fallback path (single chunk).
+        content: null,
+        textContent: 'простой текст страницы',
+        deletedAt: null,
+      }),
+    };
+    const insertChunks = jest.fn().mockResolvedValue(undefined);
+    const pageEmbeddingRepo = {
+      deleteByPage: jest.fn().mockResolvedValue(undefined),
+      insertChunks,
+    };
+    const embedWithModel = jest.fn().mockResolvedValue([[0.1, 0.2, 0.3]]);
+    const aiService = {
+      resolveEmbeddingProvider: jest.fn().mockResolvedValue({
+        model: { modelId: 'e5-small' },
+        queryPrefix: 'query: ',
+        docPrefix,
+        fingerprint: 'fp-gen-1',
+      }),
+      embedWithModel,
+    };
+    const reindexProgress = {};
+    // Stub the tx so executeTx runs its callback inline against a fake trx.
+    const db = {
+      transaction: () => ({ execute: (cb: any) => cb({}) }),
+    };
+    const service = new EmbeddingIndexerService(
+      pageRepo as unknown as PageRepo,
+      pageEmbeddingRepo as unknown as PageEmbeddingRepo,
+      aiService as unknown as AiService,
+      reindexProgress as unknown as EmbeddingReindexProgressService,
+      db as unknown as KyselyDB,
+    );
+    return { service, embedWithModel, insertChunks };
+  }
+
+  it('prepends the doc prefix to each chunk and stamps the fingerprint on rows', async () => {
+    const { service, embedWithModel, insertChunks } = makeService('passage: ');
+    await service.reindexPage(PAGE_ID);
+
+    // Embedded values are DOC-prefixed; the model is the resolved provider model.
+    expect(embedWithModel).toHaveBeenCalledTimes(1);
+    const [modelArg, wsArg, valuesArg] = embedWithModel.mock.calls[0];
+    expect(modelArg).toEqual({ modelId: 'e5-small' });
+    expect(wsArg).toBe(WORKSPACE_ID);
+    expect(valuesArg).toEqual(['passage: простой текст страницы']);
+
+    // Inserted rows carry the active fingerprint and the ORIGINAL (un-prefixed)
+    // content (the prefix is an embedding-space artifact, not stored text).
+    expect(insertChunks).toHaveBeenCalledTimes(1);
+    const rows = insertChunks.mock.calls[0][0];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].fingerprint).toBe('fp-gen-1');
+    expect(rows[0].content).toBe('простой текст страницы');
+    expect(rows[0].modelName).toBe('e5-small');
+  });
+
+  it('does not prefix when the provider has an empty doc prefix', async () => {
+    const { service, embedWithModel } = makeService('');
+    await service.reindexPage(PAGE_ID);
+    const [, , valuesArg] = embedWithModel.mock.calls[0];
+    expect(valuesArg).toEqual(['простой текст страницы']);
+  });
+});

apps/server/src/core/ai-chat/embedding/embedding-indexer.service.ts

@@ -108,15 +108,24 @@ export class EmbeddingIndexerService {
       return;
     }
 
-    // Resolve embeddings config WITHOUT crashing the queue when unconfigured.
+    // Resolve the embeddings provider WITHOUT crashing the queue when
+    // unconfigured. #530: resolveEmbeddingProvider prefers the workspace provider
+    // and falls back to the GLOBAL env provider (TEI sidecar), and yields the
+    // doc-prefix + the active fingerprint stored per row so search filters by the
+    // active generation.
     let modelName = 'unknown';
+    let provider: Awaited<
+      ReturnType<AiService['resolveEmbeddingProvider']>
+    >;
     try {
-      const model = await this.aiService.getEmbeddingModel(workspaceId);
+      provider = await this.aiService.resolveEmbeddingProvider(workspaceId);
       // Record the model id per row so a future migration can detect + re-index
       // rows produced by a different model (see the migration header). The SDK
       // type is `string | EmbeddingModel{V2,V3}`; model objects carry `modelId`.
       modelName =
-        typeof model === 'string' ? model : (model.modelId ?? 'unknown');
+        typeof provider.model === 'string'
+          ? provider.model
+          : (provider.model.modelId ?? 'unknown');
     } catch (err) {
       if (err instanceof AiEmbeddingNotConfiguredException) {
         // No embeddings provider for this workspace: NO-OP (§6.7). The page can
@@ -145,8 +154,18 @@ export class EmbeddingIndexerService {
       return;
     }
 
-    // Embed all chunks in one batch.
-    const vectors = await this.aiService.embedTexts(workspaceId, chunks);
+    // #530: prepend the provider's DOC prefix to each chunk (e5-style
+    // "passage: "; empty for a non-e5 provider) so stored vectors live in the
+    // same prefixed space as a prefixed query, then embed with the RESOLVED
+    // provider model (which may be the global TEI sidecar, not a workspace one).
+    const prefixedChunks = provider.docPrefix
+      ? chunks.map((c) => provider.docPrefix + c)
+      : chunks;
+    const vectors = await this.aiService.embedWithModel(
+      provider.model,
+      workspaceId,
+      prefixedChunks,
+    );
 
     // The column is dimension-agnostic, so ANY model dimension is stored as-is.
     // Defensive sanity check only: all chunks of ONE page come from the SAME
@@ -170,6 +189,7 @@ export class EmbeddingIndexerService {
       vectors,
       { pageId, workspaceId, spaceId },
       modelName,
+      provider.fingerprint,
     );
 
     // HARD replace in one transaction: delete then insert so search never
@@ -216,7 +236,9 @@ export class EmbeddingIndexerService {
     // (seeded at enqueue time); the finally cleans that too.
     try {
       try {
-        await this.aiService.getEmbeddingModel(workspaceId);
+        // #530: resolve via the same path reindexPage uses (workspace provider,
+        // else the global TEI sidecar) so a global-only deployment is NOT skipped.
+        await this.aiService.resolveEmbeddingProvider(workspaceId);
       } catch (err) {
         if (err instanceof AiEmbeddingNotConfiguredException) {
           this.logger.log(
@@ -348,6 +370,7 @@ export class EmbeddingIndexerService {
     vectors: number[][],
     ids: { pageId: string; workspaceId: string; spaceId: string },
     modelName: string,
+    fingerprint: string | null,
   ): PageEmbeddingChunkRow[] {
     const rows: PageEmbeddingChunkRow[] = [];
     let cursor = 0;
@@ -370,6 +393,8 @@ export class EmbeddingIndexerService {
         // Provenance for a future re-index sweep on model change.
         modelName,
         modelDimensions: embedding.length,
+        // #530: the active generation fingerprint this row belongs to.
+        fingerprint,
         embedding,
       });
     }

apps/server/src/core/api-key/api-key.controller.spec.ts

@@ -1,4 +1,8 @@
-import { ForbiddenException, NotFoundException } from '@nestjs/common';
+import {
+  ForbiddenException,
+  NotFoundException,
+  UnauthorizedException,
+} from '@nestjs/common';
 import { ApiKeyController } from './api-key.controller';
 import {
   WorkspaceCaslAction,
@@ -12,7 +16,8 @@ import {
  *    — GitHub-PAT semantics closing post-revocation laundering.
  *  - admin (CASL Manage on API) sees/revokes all workspace keys; a member only
  *    their own.
- *  - kill-switch OFF -> the surface 404s (looks like the feature does not exist).
+ *  - reveal: password step-up (401 on wrong password), owner-only even for admin
+ *    (404), api_key principal 403 — the copyable-key surface (#557).
  */
 
 function makeController(over: any = {}) {
@@ -22,6 +27,7 @@ function makeController(over: any = {}) {
       key: { id: 'k1', name: 'n', expiresAt: null, createdAt: new Date() },
     }),
     revoke: jest.fn().mockResolvedValue(undefined),
+    reveal: jest.fn().mockResolvedValue('remint.tok'),
     ...(over.apiKeyService ?? {}),
   };
   const apiKeyRepo = {
@@ -36,16 +42,16 @@ function makeController(over: any = {}) {
     }),
     ...(over.workspaceAbility ?? {}),
   };
-  const environmentService = {
-    isApiKeysEnabled: jest.fn().mockReturnValue(over.enabled ?? true),
-    ...(over.environmentService ?? {}),
+  const authService = {
+    verifyUserCredentials: jest.fn().mockResolvedValue({ id: 'u-1' }),
+    ...(over.authService ?? {}),
   };
   const auditService = { log: jest.fn() };
   const controller = new ApiKeyController(
     apiKeyService as any,
     apiKeyRepo as any,
     workspaceAbility as any,
-    environmentService as any,
+    authService as any,
     auditService as any,
   );
   return {
@@ -53,12 +59,12 @@ function makeController(over: any = {}) {
     apiKeyService,
     apiKeyRepo,
     workspaceAbility,
-    environmentService,
+    authService,
     auditService,
   };
 }
 
-const user = { id: 'u-1', workspaceId: 'ws-1' } as any;
+const user = { id: 'u-1', email: 'u@x.io', workspaceId: 'ws-1' } as any;
 const workspace = { id: 'ws-1' } as any;
 const reqAccess = () => ({ raw: {}, ip: '1.2.3.4', socket: {} }) as any;
 const reqApiKey = () =>
@@ -86,20 +92,86 @@ describe('ApiKeyController — a token cannot manage tokens', () => {
       controller.revoke({ id: 'k1' } as any, user, workspace, reqApiKey()),
     ).rejects.toBeInstanceOf(ForbiddenException);
   });
+
+  it('403 on reveal for an api_key principal (a key cannot reveal its siblings)', async () => {
+    const { controller, authService, apiKeyService } = makeController();
+    await expect(
+      controller.reveal(
+        { id: 'k1', password: 'pw' } as any,
+        user,
+        workspace,
+        reqApiKey(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    // Rejected BEFORE the step-up and the key lookup even run.
+    expect(authService.verifyUserCredentials).not.toHaveBeenCalled();
+    expect(apiKeyService.reveal).not.toHaveBeenCalled();
+  });
 });
 
-describe('ApiKeyController — kill-switch OFF → 404', () => {
-  it('create/list/revoke all 404 when disabled', async () => {
-    const { controller } = makeController({ enabled: false });
+describe('ApiKeyController — reveal (copyable key under step-up)', () => {
+  it('re-mints and returns the token + logs API_KEY_REVEALED on success', async () => {
+    const { controller, apiKeyService, authService, auditService } =
+      makeController();
+    const res = await controller.reveal(
+      { id: 'k1', password: 'correct-horse' } as any,
+      user,
+      workspace,
+      reqAccess(),
+    );
+
+    expect(res).toEqual({ token: 'remint.tok' });
+    // Step-up ran with the caller's email + supplied password.
+    expect(authService.verifyUserCredentials).toHaveBeenCalledWith(
+      { email: 'u@x.io', password: 'correct-horse' },
+      'ws-1',
+    );
+    expect(apiKeyService.reveal).toHaveBeenCalledWith({
+      apiKeyId: 'k1',
+      user,
+      workspaceId: 'ws-1',
+    });
+    expect(auditService.log).toHaveBeenCalledWith(
+      expect.objectContaining({ event: 'api_key.revealed' }),
+    );
+  });
+
+  it('401 on a wrong password — step-up runs BEFORE the key lookup (no oracle)', async () => {
+    const { controller, apiKeyService } = makeController({
+      authService: {
+        verifyUserCredentials: jest
+          .fn()
+          .mockRejectedValue(new UnauthorizedException()),
+      },
+    });
     await expect(
-      controller.create({ name: 'x' } as any, user, reqAccess()),
-    ).rejects.toBeInstanceOf(NotFoundException);
+      controller.reveal(
+        { id: 'k1', password: 'wrong' } as any,
+        user,
+        workspace,
+        reqAccess(),
+      ),
+    ).rejects.toBeInstanceOf(UnauthorizedException);
+    // The key is never looked up / re-minted when step-up fails.
+    expect(apiKeyService.reveal).not.toHaveBeenCalled();
+  });
+
+  it("propagates the service's uniform 404 (absent/revoked/expired/non-owner)", async () => {
+    const { controller, auditService } = makeController({
+      apiKeyService: {
+        reveal: jest.fn().mockRejectedValue(new NotFoundException()),
+      },
+    });
     await expect(
-      controller.list(user, workspace, reqAccess()),
-    ).rejects.toBeInstanceOf(NotFoundException);
-    await expect(
-      controller.revoke({ id: 'k1' } as any, user, workspace, reqAccess()),
+      controller.reveal(
+        { id: 'k1', password: 'correct' } as any,
+        user,
+        workspace,
+        reqAccess(),
+      ),
     ).rejects.toBeInstanceOf(NotFoundException);
+    // No audit event on a failed reveal.
+    expect(auditService.log).not.toHaveBeenCalled();
   });
 });
 

apps/server/src/core/api-key/api-key.controller.ts

@@ -2,6 +2,7 @@ import {
   Body,
   Controller,
   ForbiddenException,
+  forwardRef,
   HttpCode,
   HttpStatus,
   Inject,
@@ -17,6 +18,7 @@ import { ApiKeyService } from './api-key.service';
 import { ApiKeyRepo } from '@docmost/db/repos/api-key/api-key.repo';
 import { CreateApiKeyDto } from './dto/create-api-key.dto';
 import { RevokeApiKeyDto } from './dto/revoke-api-key.dto';
+import { RevealApiKeyDto } from './dto/reveal-api-key.dto';
 import { AuthUser } from '../../common/decorators/auth-user.decorator';
 import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
 import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
@@ -31,7 +33,7 @@ import {
   AUDIT_SERVICE,
   IAuditService,
 } from '../../integrations/audit/audit.service';
-import { EnvironmentService } from '../../integrations/environment/environment.service';
+import { AuthService } from '../auth/services/auth.service';
 import { UserThrottlerGuard } from '../../integrations/throttle/user-throttler.guard';
 import { AUTH_THROTTLER } from '../../integrations/throttle/throttler-names';
 
@@ -44,18 +46,13 @@ export class ApiKeyController {
     private readonly apiKeyService: ApiKeyService,
     private readonly apiKeyRepo: ApiKeyRepo,
     private readonly workspaceAbility: WorkspaceAbilityFactory,
-    private readonly environmentService: EnvironmentService,
+    // forwardRef breaks the AuthModule <-> ApiKeyModule cycle (AuthModule imports
+    // ApiKeyModule for JwtStrategy). Only used for the reveal step-up.
+    @Inject(forwardRef(() => AuthService))
+    private readonly authService: AuthService,
     @Inject(AUDIT_SERVICE) private readonly auditService: IAuditService,
   ) {}
 
-  // Kill-switch OFF: the issuance surface disappears entirely (404), not a 403 —
-  // it must look like the feature does not exist.
-  private assertEnabled(): void {
-    if (!this.environmentService.isApiKeysEnabled()) {
-      throw new NotFoundException();
-    }
-  }
-
   // A token cannot manage tokens (GitHub-PAT semantics): an api-key principal is
   // refused on the management surface, so a leaked key cannot mint a replacement
   // or revoke the keys that would lock it out (closes post-revocation laundering).
@@ -78,7 +75,6 @@ export class ApiKeyController {
     @AuthUser() user: User,
     @Req() req: FastifyRequest,
   ) {
-    this.assertEnabled();
     this.rejectApiKeyPrincipal(req);
 
     // undefined -> service default (1 year); null -> unlimited; string -> Date.
@@ -100,8 +96,10 @@ export class ApiKeyController {
       resourceType: AuditResource.API_KEY,
       resourceId: key.id,
     });
-    // The durable trail lives in container logs (AUDIT_SERVICE is a Noop in this
-    // build). No token material — the JWT is only ever returned in the response.
+    // Durable audit is via DatabaseAuditService (#496); this structured log is a
+    // second, container-log trail. No token material — the JWT is only ever
+    // returned in a response body (here on create, or via /api-keys/reveal),
+    // never logged and never stored.
     this.logger.log(
       `API key created: id=${key.id} name=${JSON.stringify(
         key.name,
@@ -110,9 +108,9 @@ export class ApiKeyController {
       } ip=${this.clientIp(req)}`,
     );
 
-    // Return the token ONCE (never retrievable again) and the computed expiry so
-    // the caller/UI can surface "expires <date>" (the year-default time-bomb
-    // early-warning).
+    // Return the token (also re-obtainable later by the owner via
+    // /api-keys/reveal under a step-up) and the computed expiry so the caller/UI
+    // can surface "expires <date>" (the year-default time-bomb early-warning).
     return {
       token,
       apiKey: {
@@ -131,7 +129,6 @@ export class ApiKeyController {
     @AuthWorkspace() workspace: Workspace,
     @Req() req: FastifyRequest,
   ) {
-    this.assertEnabled();
     this.rejectApiKeyPrincipal(req);
 
     const ability = this.workspaceAbility.createForUser(user, workspace);
@@ -163,7 +160,6 @@ export class ApiKeyController {
     @AuthWorkspace() workspace: Workspace,
     @Req() req: FastifyRequest,
   ) {
-    this.assertEnabled();
     this.rejectApiKeyPrincipal(req);
 
     const key = await this.apiKeyRepo.findById(dto.id, workspace.id);
@@ -198,4 +194,64 @@ export class ApiKeyController {
 
     return { success: true };
   }
+
+  /**
+   * Reveal (re-mint) a copyable token for an existing key, under a password
+   * step-up. The token is hashed nowhere and stored nowhere — "reveal" re-mints
+   * the SAME deterministic value (see TokenService.generateApiToken /
+   * ApiKeyService.reveal) and returns it in the body only.
+   *
+   * Defence layers (triple, against exfiltration through a hijacked session):
+   *  - rejectApiKeyPrincipal: an api_key Bearer caller is 403 — a leaked key must
+   *    NOT be able to reveal its siblings (key laundering); a token doesn't manage
+   *    tokens.
+   *  - step-up: the password is re-verified (verifyUserCredentials) BEFORE any key
+   *    lookup, so a wrong/absent password is a uniform 401 that leaks nothing about
+   *    the key. SSO/MFA-only users (no local password) are out of scope (homelab).
+   *  - AUTH throttler: same limiter as create.
+   *
+   * Owner-only, EVEN for an admin, and every key-state negative (absent / revoked /
+   * expired / another user's / creator disabled) is a UNIFORM 404 (see
+   * ApiKeyService.reveal) — no existence/state oracle.
+   */
+  @HttpCode(HttpStatus.OK)
+  @UseGuards(JwtAuthGuard, UserThrottlerGuard)
+  @Throttle({ [AUTH_THROTTLER]: { limit: 10, ttl: 60_000 } })
+  @Post('reveal')
+  async reveal(
+    @Body() dto: RevealApiKeyDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+    @Req() req: FastifyRequest,
+  ) {
+    this.rejectApiKeyPrincipal(req);
+
+    // Step-up FIRST — before any key lookup — so the 401 for a bad password never
+    // depends on (and never leaks) the key's existence/state. Reuses the exact
+    // timing-safe, SSO-aware credential check used by login (throws a uniform
+    // 401 on wrong/absent/SSO-only password).
+    await this.authService.verifyUserCredentials(
+      { email: user.email, password: dto.password },
+      workspace.id,
+    );
+
+    const token = await this.apiKeyService.reveal({
+      apiKeyId: dto.id,
+      user,
+      workspaceId: workspace.id,
+    });
+
+    // Durable audit (DatabaseAuditService, #496) + a structured container-log
+    // trail. NEVER the token material.
+    this.auditService.log({
+      event: AuditEvent.API_KEY_REVEALED,
+      resourceType: AuditResource.API_KEY,
+      resourceId: dto.id,
+    });
+    this.logger.log(
+      `API key revealed: id=${dto.id} actor=${user.id} ip=${this.clientIp(req)}`,
+    );
+
+    return { token };
+  }
 }

apps/server/src/core/api-key/api-key.module.ts

@@ -1,7 +1,8 @@
-import { Module } from '@nestjs/common';
+import { forwardRef, Module } from '@nestjs/common';
 import { ApiKeyService } from './api-key.service';
 import { ApiKeyController } from './api-key.controller';
 import { TokenModule } from '../auth/token.module';
+import { AuthModule } from '../auth/auth.module';
 
 // Core (non-EE) API-key feature: issuance REST endpoints + the shared validator
 // consumed by jwt.strategy (REST) and McpService (the /mcp Bearer router).
@@ -11,7 +12,10 @@ import { TokenModule } from '../auth/token.module';
 // jwt.strategy) and McpModule (for the /mcp router) can inject it directly,
 // replacing the absent EE `ee/api-key` dynamic require.
 @Module({
-  imports: [TokenModule],
+  // forwardRef(AuthModule): the reveal endpoint's password step-up uses
+  // AuthService.verifyUserCredentials. AuthModule already imports ApiKeyModule
+  // (for JwtStrategy), so the two form a cycle that forwardRef resolves.
+  imports: [TokenModule, forwardRef(() => AuthModule)],
   controllers: [ApiKeyController],
   providers: [ApiKeyService],
   exports: [ApiKeyService],

apps/server/src/core/api-key/api-key.service.spec.ts

@@ -1,4 +1,8 @@
-import { UnauthorizedException } from '@nestjs/common';
+import {
+  ForbiddenException,
+  NotFoundException,
+  UnauthorizedException,
+} from '@nestjs/common';
 import { ApiKeyService } from './api-key.service';
 import { JwtType } from '../auth/dto/jwt-payload';
 
@@ -16,8 +20,6 @@ import { JwtType } from '../auth/dto/jwt-payload';
  *  - No validate cache (each call re-reads the row → immediate revocation).
  */
 
-const APP_SECRET = 'secret';
-
 function makeDeps(over: Partial<Record<string, any>> = {}) {
   const apiKeyRepo = {
     findById: jest.fn(),
@@ -38,20 +40,13 @@ function makeDeps(over: Partial<Record<string, any>> = {}) {
     generateApiToken: jest.fn().mockResolvedValue('minted.jwt.token'),
     ...(over.tokenService ?? {}),
   };
-  const environmentService = {
-    isApiKeysEnabled: jest.fn().mockReturnValue(true),
-    getApiKeysEnabledRaw: jest.fn().mockReturnValue(undefined),
-    getAppSecret: jest.fn().mockReturnValue(APP_SECRET),
-    ...(over.environmentService ?? {}),
-  };
   const service = new (ApiKeyService as unknown as new (...a: any[]) => ApiKeyService)(
     apiKeyRepo,
     userRepo,
     workspaceRepo,
     tokenService,
-    environmentService,
   );
-  return { service, apiKeyRepo, userRepo, workspaceRepo, tokenService, environmentService };
+  return { service, apiKeyRepo, userRepo, workspaceRepo, tokenService };
 }
 
 const payload = (over: Record<string, any> = {}) => ({
@@ -148,10 +143,6 @@ describe('ApiKeyService.validate', () => {
         d.workspaceRepo.findById.mockResolvedValue(undefined);
       },
     ],
-    [
-      'kill-switch OFF',
-      (d) => d.environmentService.isApiKeysEnabled.mockReturnValue(false),
-    ],
     [
       'malformed payload (missing apiKeyId)',
       () => undefined,
@@ -175,14 +166,16 @@ describe('ApiKeyService.validate', () => {
     },
   );
 
-  it('kill-switch OFF denies BEFORE any DB read', async () => {
-    const { service, apiKeyRepo, environmentService } = makeDeps();
-    environmentService.isApiKeysEnabled.mockReturnValue(false);
+  // --- Kill-switch removed: keys work with no env variable ------------------
+  it('validates with no API_KEYS_ENABLED env (kill-switch fully removed)', async () => {
+    // The service no longer takes EnvironmentService — there is no env gate left.
+    const { service, apiKeyRepo, userRepo } = makeDeps();
+    apiKeyRepo.findById.mockResolvedValue(activeRow());
+    userRepo.findById.mockResolvedValue(activeUser());
 
-    await expect(service.validate(payload() as any)).rejects.toBeInstanceOf(
-      UnauthorizedException,
-    );
-    expect(apiKeyRepo.findById).not.toHaveBeenCalled();
+    await expect(service.validate(payload() as any)).resolves.toMatchObject({
+      user: { id: 'u-1' },
+    });
   });
 
   // --- Infra error propagates (5xx), NOT masked as 401 ---------------------
@@ -297,3 +290,90 @@ describe('ApiKeyService.create (mint-then-insert, no exp)', () => {
     expect(apiKeyRepo.insert).not.toHaveBeenCalled();
   });
 });
+
+/**
+ * ApiKeyService.reveal — the KEY-STATE gate for the copyable-key flow. Owner-only
+ * (even for an admin), and EVERY negative is a uniform NotFoundException so there
+ * is no existence/state oracle. Re-mint is deterministic (delegated to
+ * TokenService); here we only assert the gate + normalization.
+ */
+describe('ApiKeyService.reveal', () => {
+  const caller = (over: Record<string, any> = {}) =>
+    ({ id: 'u-1', email: 'u@x.io', workspaceId: 'ws-1', ...over }) as any;
+
+  it('re-mints and returns the token for a live key owned by the caller', async () => {
+    const { service, apiKeyRepo, tokenService } = makeDeps();
+    apiKeyRepo.findById.mockResolvedValue(activeRow());
+    tokenService.generateApiToken.mockResolvedValue('remint.tok');
+
+    const token = await service.reveal({
+      apiKeyId: 'key-1',
+      user: caller(),
+      workspaceId: 'ws-1',
+    });
+
+    expect(token).toBe('remint.tok');
+    // Re-mints against the SAME id + the caller (== creator) so the value matches.
+    expect(tokenService.generateApiToken).toHaveBeenCalledWith({
+      apiKeyId: 'key-1',
+      user: expect.objectContaining({ id: 'u-1' }),
+      workspaceId: 'ws-1',
+    });
+  });
+
+  it('404 for a missing/revoked key (findById returns undefined)', async () => {
+    const { service, apiKeyRepo, tokenService } = makeDeps();
+    apiKeyRepo.findById.mockResolvedValue(undefined);
+
+    await expect(
+      service.reveal({ apiKeyId: 'key-1', user: caller(), workspaceId: 'ws-1' }),
+    ).rejects.toBeInstanceOf(NotFoundException);
+    // No re-mint on any negative.
+    expect(tokenService.generateApiToken).not.toHaveBeenCalled();
+  });
+
+  it("404 for another user's key — owner-only, even for an admin", async () => {
+    const { service, apiKeyRepo, tokenService } = makeDeps();
+    // The caller is a workspace admin (irrelevant here — reveal ignores CASL).
+    apiKeyRepo.findById.mockResolvedValue(activeRow({ creatorId: 'someone-else' }));
+
+    await expect(
+      service.reveal({ apiKeyId: 'key-1', user: caller(), workspaceId: 'ws-1' }),
+    ).rejects.toBeInstanceOf(NotFoundException);
+    expect(tokenService.generateApiToken).not.toHaveBeenCalled();
+  });
+
+  it('404 for an expired key (expiry read from the row) — no dead token issued', async () => {
+    const { service, apiKeyRepo, tokenService } = makeDeps();
+    apiKeyRepo.findById.mockResolvedValue(
+      activeRow({ expiresAt: new Date(Date.now() - 1000) }),
+    );
+
+    await expect(
+      service.reveal({ apiKeyId: 'key-1', user: caller(), workspaceId: 'ws-1' }),
+    ).rejects.toBeInstanceOf(NotFoundException);
+    expect(tokenService.generateApiToken).not.toHaveBeenCalled();
+  });
+
+  it('normalizes a disabled-creator ForbiddenException (403) to a uniform 404', async () => {
+    const { service, apiKeyRepo, tokenService } = makeDeps();
+    apiKeyRepo.findById.mockResolvedValue(activeRow());
+    // generateApiToken throws ForbiddenException when isUserDisabled(user).
+    tokenService.generateApiToken.mockRejectedValue(new ForbiddenException());
+
+    await expect(
+      service.reveal({ apiKeyId: 'key-1', user: caller(), workspaceId: 'ws-1' }),
+    ).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it('propagates an UNEXPECTED re-mint error (not masked as 404)', async () => {
+    const { service, apiKeyRepo, tokenService } = makeDeps();
+    apiKeyRepo.findById.mockResolvedValue(activeRow());
+    const boom = new Error('signer exploded');
+    tokenService.generateApiToken.mockRejectedValue(boom);
+
+    await expect(
+      service.reveal({ apiKeyId: 'key-1', user: caller(), workspaceId: 'ws-1' }),
+    ).rejects.toBe(boom);
+  });
+});

apps/server/src/core/api-key/api-key.service.ts

@@ -1,7 +1,8 @@
 import {
+  ForbiddenException,
   Injectable,
   Logger,
-  OnModuleInit,
+  NotFoundException,
   UnauthorizedException,
 } from '@nestjs/common';
 import { v7 as uuid7 } from 'uuid';
@@ -9,7 +10,6 @@ import { ApiKeyRepo } from '@docmost/db/repos/api-key/api-key.repo';
 import { UserRepo } from '@docmost/db/repos/user/user.repo';
 import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
 import { TokenService } from '../auth/services/token.service';
-import { EnvironmentService } from '../../integrations/environment/environment.service';
 import { JwtApiKeyPayload } from '../auth/dto/jwt-payload';
 import { ApiKey, User, Workspace } from '@docmost/db/types/entity.types';
 import { isUserDisabled } from '../../common/helpers';
@@ -31,7 +31,7 @@ const LAST_USED_THROTTLE_MS = 60 * 60 * 1000;
  * key's lifetime and revocation — never the JWT, which carries no `exp` claim.
  */
 @Injectable()
-export class ApiKeyService implements OnModuleInit {
+export class ApiKeyService {
   private readonly logger = new Logger(ApiKeyService.name);
 
   constructor(
@@ -39,20 +39,8 @@ export class ApiKeyService implements OnModuleInit {
     private readonly userRepo: UserRepo,
     private readonly workspaceRepo: WorkspaceRepo,
     private readonly tokenService: TokenService,
-    private readonly environmentService: EnvironmentService,
   ) {}
 
-  onModuleInit() {
-    // Boot log so the kill-switch state after each deploy is verifiable in logs.
-    const enabled = this.environmentService.isApiKeysEnabled();
-    const raw = this.environmentService.getApiKeysEnabledRaw();
-    this.logger.log(
-      `API keys: ${enabled ? 'ENABLED' : 'DISABLED'} (API_KEYS_ENABLED=${
-        raw ?? 'unset'
-      })`,
-    );
-  }
-
   /**
    * Mint a new key for `user`. mint-then-insert ordering (R1):
    *   1. generate the id first — it must be in the JWT payload before the row.
@@ -60,8 +48,11 @@ export class ApiKeyService implements OnModuleInit {
    *      written (inert), so a half-created key cannot exist.
    *   3. insert the row last. A lost response leaves an orphaned row that is
    *      visible in `list` and self-heals (the user revokes it).
-   * The token is returned ONCE and never stored — the JWT is self-contained, so
-   * no token material lives in the table.
+   * No token material is ever stored — the JWT is self-contained (its `api_keys`
+   * row holds only metadata + lifetime, never the token). The token is returned
+   * here on create AND is re-obtainable any time by its owner via a deterministic
+   * re-mint under a password step-up (POST /api-keys/reveal); it is deterministic
+   * precisely because it carries no `iat`/`exp` (see TokenService).
    *
    * `expiresAt`: `undefined` -> default 1 year; `null` -> unlimited (explicit);
    * a Date -> that instant (a past date is rejected at the DTO layer).
@@ -101,8 +92,8 @@ export class ApiKeyService implements OnModuleInit {
    * path returns) so the AuthUser/AuthWorkspace decorators and MCP identity work
    * unchanged.
    *
-   * Failure semantics (R4, anti-enumeration): a DEFINITE negative fact — feature
-   * disabled, missing/revoked/expired row, workspace mismatch, disabled user —
+   * Failure semantics (R4, anti-enumeration): a DEFINITE negative fact —
+   * missing/revoked/expired row, workspace mismatch, disabled user —
    * throws a bare `UnauthorizedException` (a single generic 401 for every case;
    * an agent cannot distinguish expired from revoked, and its reaction is
    * identical). An UNEXPECTED (infra) error is NOT caught here: it propagates so
@@ -114,12 +105,6 @@ export class ApiKeyService implements OnModuleInit {
   async validate(
     payload: JwtApiKeyPayload,
   ): Promise<{ user: User; workspace: Workspace }> {
-    // Kill-switch OFF: deny unconditionally (same generic 401). Note the
-    // endpoints additionally 404 at the controller; here we deny the token.
-    if (!this.environmentService.isApiKeysEnabled()) {
-      throw new UnauthorizedException();
-    }
-
     if (!payload?.apiKeyId || !payload?.sub || !payload?.workspaceId) {
       throw new UnauthorizedException();
     }
@@ -174,6 +159,67 @@ export class ApiKeyService implements OnModuleInit {
     await this.apiKeyRepo.softDelete(id, workspaceId);
   }
 
+  /**
+   * Re-mint (reveal) the token for an EXISTING key so its owner can copy it again.
+   * The token material is never stored, so "reveal" = re-generate the same value:
+   * generateApiToken is deterministic (no `iat`/`exp`, fixed payload), so the
+   * re-minted token is byte-identical to the original for the same key.
+   *
+   * Authorization/step-up (principal rejection + password) is the caller's job
+   * (the controller). This method owns the KEY-STATE gate and the re-mint. Every
+   * negative is a UNIFORM `NotFoundException` — there is NO existence/state oracle:
+   * a caller cannot tell "absent" from "revoked" from "expired" from "another
+   * user's key" from "creator disabled". Only a live key owned by `user` re-mints.
+   *
+   * `user` is the authenticated caller AND (after the owner check) the key's
+   * creator, so the re-minted token's `sub` matches the original mint — passing
+   * `user` directly avoids re-fetching the creator row.
+   */
+  async reveal(opts: {
+    apiKeyId: string;
+    user: User;
+    workspaceId: string;
+  }): Promise<string> {
+    const { apiKeyId, user, workspaceId } = opts;
+
+    const row = await this.apiKeyRepo.findById(apiKeyId, workspaceId);
+    // Absent = revoked (soft-deleted), orphaned, or never existed -> uniform 404.
+    if (!row) {
+      throw new NotFoundException();
+    }
+
+    // Owner-only, EVEN for an admin: a working revealed token is an impersonation
+    // of the creator, so unlike list/revoke, admin must NOT reveal others' keys.
+    // Someone else's key looks exactly like a missing one -> uniform 404.
+    if (row.creatorId !== user.id) {
+      throw new NotFoundException();
+    }
+
+    // Expiry is read from the ROW (findById filters only deletedAt, so an expired
+    // row is still returned). A dead key must not hand out a working token, and a
+    // uniform 404 keeps the anti-enumeration property.
+    if (row.expiresAt && row.expiresAt.getTime() <= Date.now()) {
+      throw new NotFoundException();
+    }
+
+    try {
+      // Deterministic re-mint (byte-identical to the original for this key).
+      return await this.tokenService.generateApiToken({
+        apiKeyId: row.id,
+        user,
+        workspaceId,
+      });
+    } catch (err) {
+      // A disabled creator makes generateApiToken throw ForbiddenException (403).
+      // Normalize to the SAME 404 so reveal never leaks "user is blocked" vs "key
+      // does not exist". Unexpected errors propagate (5xx), never masked.
+      if (err instanceof ForbiddenException) {
+        throw new NotFoundException();
+      }
+      throw err;
+    }
+  }
+
   // Throttled best-effort last_used_at bump: skip if it was touched within the
   // window; otherwise fire-and-forget so a stamp write never fails or slows the
   // request (mirrors SessionActivityService.trackActivity).

apps/server/src/core/api-key/dto/reveal-api-key.dto.ts

@@ -0,0 +1,14 @@
+import { IsNotEmpty, IsString, IsUUID } from 'class-validator';
+
+// Step-up payload for `POST /api-keys/reveal`: the key to re-mint + the caller's
+// current password. The password is re-verified server-side (AuthService.
+// verifyUserCredentials) before the key is ever looked up, so a copyable,
+// non-expiring token cannot be exfiltrated through a merely-hijacked session.
+export class RevealApiKeyDto {
+  @IsUUID()
+  id: string;
+
+  @IsString()
+  @IsNotEmpty()
+  password: string;
+}

apps/server/src/core/auth/auth.module.ts

@@ -1,4 +1,4 @@
-import { Module } from '@nestjs/common';
+import { forwardRef, Module } from '@nestjs/common';
 import { AuthController } from './auth.controller';
 import { AuthService } from './services/auth.service';
 import { JwtStrategy } from './strategies/jwt.strategy';
@@ -10,8 +10,9 @@ import { ApiKeyModule } from '../api-key/api-key.module';
 @Module({
   // ApiKeyModule supplies ApiKeyService, injected into JwtStrategy so an
   // api_key Bearer/cookie token is validated directly (replacing the absent EE
-  // `ee/api-key` dynamic require).
-  imports: [TokenModule, WorkspaceModule, ApiKeyModule],
+  // `ee/api-key` dynamic require). forwardRef: ApiKeyModule imports AuthModule
+  // back (for the reveal step-up), so the two form a cycle.
+  imports: [TokenModule, WorkspaceModule, forwardRef(() => ApiKeyModule)],
   controllers: [AuthController],
   providers: [AuthService, SignupService, JwtStrategy],
   exports: [SignupService, AuthService],

apps/server/src/core/auth/services/token.service.behavior.spec.ts

@@ -306,6 +306,41 @@ describe('TokenService.generateApiToken (no exp claim ever)', () => {
     });
   });
 
+  // #557: the copyable-key contract. noTimestamp suppresses `iat`, so the token
+  // is a pure deterministic function of (payload, secret) — re-minting the SAME
+  // key yields a BYTE-IDENTICAL value, which is what makes "reveal" a safe
+  // re-mint rather than a stored secret.
+  it('mints an api-key JWT with NEITHER exp NOR iat (deterministic)', async () => {
+    const { service } = makeRealSignerService();
+
+    const token = await service.generateApiToken({
+      apiKeyId: 'key-1',
+      user: user as never,
+      workspaceId: 'ws-1',
+    });
+
+    const decoded = jwt.decode(token) as Record<string, unknown>;
+    expect(decoded.exp).toBeUndefined();
+    expect(decoded.iat).toBeUndefined();
+  });
+
+  it('two mints of the SAME key are byte-identical (re-mint = reveal)', async () => {
+    const { service } = makeRealSignerService();
+    const opts = {
+      apiKeyId: 'key-1',
+      user: user as never,
+      workspaceId: 'ws-1',
+    };
+
+    const first = await service.generateApiToken(opts);
+    // A different time (and a fresh signer instance) must not change the bytes.
+    await new Promise((r) => setTimeout(r, 1100));
+    const { service: service2 } = makeRealSignerService();
+    const second = await service2.generateApiToken(opts);
+
+    expect(second).toBe(first);
+  });
+
   it('demonstrates the live bug it guards: the SHARED signer WOULD add exp', () => {
     const { JwtService } = require('@nestjs/jwt');
     const sharedJwt = new JwtService({

apps/server/src/core/auth/services/token.service.ts

@@ -155,19 +155,31 @@ export class TokenService {
     // signer would silently get exp=now+90d and die in 90 days regardless of its
     // row. We mint through a dedicated no-expiry signer, re-stamping only
     // `issuer: 'Docmost'` for claim parity with the shared signer.
+    //
+    // The dedicated signer ALSO sets `noTimestamp: true`, so the token carries
+    // neither `exp` nor `iat`. The payload is a fixed literal { sub, apiKeyId,
+    // workspaceId, type } in a stable order, so the HS256 signature is a pure
+    // deterministic function of (sub, apiKeyId, workspaceId, APP_SECRET): minting
+    // the SAME key twice yields a BYTE-IDENTICAL token. This is what makes the key
+    // "copyable" — the reveal endpoint (#557) re-mints the same value under a
+    // step-up without ever persisting the token material.
     return this.apiKeyJwtService().sign(payload);
   }
 
   // Lazily-built JWT signer for API-key tokens: same APP_SECRET, same 'Docmost'
   // issuer, but WITHOUT the global `expiresIn` — so minted API-key tokens have no
-  // `exp` claim. Built once and cached. Verification still goes through the
-  // shared verifier (same secret); `verifyAsync` does not require an `exp`.
+  // `exp` claim. `noTimestamp: true` additionally suppresses the default `iat`
+  // claim jsonwebtoken would otherwise add, making the minted token a fully
+  // deterministic function of its payload + secret (byte-identical re-mints, the
+  // basis of the copyable/reveal flow). Built once and cached. Verification still
+  // goes through the shared verifier (same secret); `verifyAsync` does not
+  // require an `exp` or `iat`.
   private _apiKeyJwtService?: JwtService;
   private apiKeyJwtService(): JwtService {
     if (!this._apiKeyJwtService) {
       this._apiKeyJwtService = new JwtService({
         secret: this.environmentService.getAppSecret(),
-        signOptions: { issuer: 'Docmost' },
+        signOptions: { issuer: 'Docmost', noTimestamp: true },
       });
     }
     return this._apiKeyJwtService;

apps/server/src/core/search/dto/search-response.dto.ts

@@ -32,10 +32,27 @@ export class SearchResultDto {
   matchedTerms: string[];
 }
 
-// The paginated envelope (A5). `total` is the EXACT permission-filtered count of
-// pages matching the positive lexical query (fail-closed). `hasMore` is true when
-// more results exist WITHIN the fusion window; `truncatedAtCap` signals the match
-// set exceeded CANDIDATE_CAP and the tail is unreachable by pagination.
+// #530 Phase B — the semantic (vector) layer's per-request status.
+//  - `state`: 'full' when a provider resolved and the vector arm ran this
+//    request; 'off' otherwise (kill-switch, no provider, or a degrade).
+//  - `available`: whether the vector arm actually contributed this request.
+//  - `reason`: why the arm did NOT run — 'no-provider' (no embedding provider
+//    resolved) or 'degraded' (sidecar down / query embed timed out).
+//  - `indexed`/`total`: reserved for PR-2 coverage reporting (unused in PR-1).
+export class SearchSemanticDto {
+  state: 'full' | 'off';
+  available: boolean;
+  reason?: 'no-provider' | 'degraded';
+  indexed?: number;
+  total?: number;
+}
+
+// The paginated envelope (A5). `total` is the permission-filtered count of the
+// candidate UNION (lexical ∪ vector top-N, fail-closed) — a deliberate, #530
+// documented change from Phase A's exact-lexical count (on a semantic degrade it
+// falls back to exactly that lexical count). `hasMore` is true when more results
+// exist WITHIN the fusion window; `truncatedAtCap` signals the match set exceeded
+// CANDIDATE_CAP and the tail is unreachable by pagination.
 export class SearchResponseDto {
   items: SearchResultDto[];
   total: number;
@@ -53,4 +70,7 @@ export class SearchResponseDto {
     mode: 'or' | 'and';
     match: string;
   };
+  // Absent on the early-exit paths (empty/garbage query); present once search
+  // actually runs. Optional so those short-circuit responses stay valid.
+  semantic?: SearchSemanticDto;
 }

apps/server/src/core/search/search.module.ts

@@ -1,8 +1,15 @@
 import { Module } from '@nestjs/common';
 import { SearchController } from './search.controller';
 import { SearchService } from './search.service';
+import { AiModule } from '../../integrations/ai/ai.module';
 
+/**
+ * #530: AiModule supplies AiService (embedQuery / resolveEmbeddingProvider).
+ * PageEmbeddingRepo is provided by the @Global DatabaseModule, so it is injected
+ * into SearchService without an explicit import here.
+ */
 @Module({
+  imports: [AiModule],
   controllers: [SearchController],
   providers: [SearchService],
   exports: [SearchService],

apps/server/src/core/search/search.service.query-mode.spec.ts

@@ -48,6 +48,10 @@ describe('SearchService.searchPage — scope-security early returns', () => {
       shareRepo as any,
       spaceMemberRepo as any,
       pagePermissionRepo as any,
+      // #530 semantic path off for these query-mode unit tests: a stubbed
+      // embedQuery that throws makes the service degrade to the lexical path.
+      { embedQuery: jest.fn().mockRejectedValue(new Error('no embed')) } as any,
+      { vectorCandidateArm: jest.fn() } as any,
     );
     return { service, pageRepo, shareRepo, spaceMemberRepo, pagePermissionRepo };
   }

apps/server/src/core/search/search.service.spec.ts

@@ -11,6 +11,8 @@ describe('SearchService', () => {
       {} as any, // shareRepo
       {} as any, // spaceMemberRepo
       {} as any, // pagePermissionRepo
+      {} as any, // aiService
+      {} as any, // pageEmbeddingRepo
     );
     expect(service).toBeDefined();
   });
@@ -61,6 +63,8 @@ describe('SearchService.searchSuggestions — onlyTemplates filter', () => {
       shareRepo as any,
       spaceMemberRepo as any,
       pagePermissionRepo as any,
+      {} as any, // aiService (searchSuggestions never embeds)
+      {} as any, // pageEmbeddingRepo
     );
 
     return { service, db, pageBuilder };

apps/server/src/core/search/search.service.ts

@@ -1,8 +1,9 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, Logger } from '@nestjs/common';
 import { SearchDTO, SearchSuggestionDTO } from './dto/search.dto';
 import {
   SearchResponseDto,
   SearchResultDto,
+  SearchSemanticDto,
 } from './dto/search-response.dto';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
@@ -11,6 +12,10 @@ import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
 import { ShareRepo } from '@docmost/db/repos/share/share.repo';
 import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
+import { PageEmbeddingRepo } from '@docmost/db/repos/ai-chat/page-embedding.repo';
+import { AiService } from '../../integrations/ai/ai.service';
+import { AiEmbeddingNotConfiguredException } from '../../integrations/ai/ai-embedding-not-configured.exception';
+import { isStatementTimeout } from '@docmost/db/utils';
 import {
   ParsedQuery,
   ParsedTerm,
@@ -59,14 +64,42 @@ function defaultBooleanMode(): SearchBooleanMode {
   return process.env.SEARCH_MODE === 'and' ? 'and' : 'or';
 }
 
+// #530 semantic env knobs. SEARCH_SEMANTIC=off is the kill-switch (hybrid is
+// otherwise transparent — no per-request mode flag). SEARCH_VECTOR_WEIGHT tunes
+// the vector RRF leg's contribution (default 1.0, i.e. equal to each lexical
+// leg). SEARCH_VECTOR_CANDIDATES caps the vector top-N pulled into the union.
+function semanticKillSwitchOff(): boolean {
+  return process.env.SEARCH_SEMANTIC === 'off';
+}
+function getVectorWeight(): number {
+  const raw = Number(process.env.SEARCH_VECTOR_WEIGHT);
+  return Number.isFinite(raw) && raw >= 0 ? raw : 1.0;
+}
+function getVectorCandidates(): number {
+  const raw = Number(process.env.SEARCH_VECTOR_CANDIDATES);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 50;
+}
+// Safety net for the brute-force vector scan (no ANN index — see
+// vectorCandidateArm): a per-statement timeout bounding ONLY the fused vector
+// query, so a pathological seq scan is cancelled (SQLSTATE 57014) and search
+// degrades to lexical instead of hanging the request. Default 2000ms.
+function getVectorStatementTimeoutMs(): number {
+  const raw = Number(process.env.SEARCH_VECTOR_STATEMENT_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 2000;
+}
+
 @Injectable()
 export class SearchService {
+  private readonly logger = new Logger(SearchService.name);
+
   constructor(
     @InjectKysely() private readonly db: KyselyDB,
     private pageRepo: PageRepo,
     private shareRepo: ShareRepo,
     private spaceMemberRepo: SpaceMemberRepo,
     private pagePermissionRepo: PagePermissionRepo,
+    private aiService: AiService,
+    private pageEmbeddingRepo: PageEmbeddingRepo,
   ) {}
 
   // === #529 SQL fragment builders (parameterized AST, never string-concat) =====
@@ -292,33 +325,102 @@ export class SearchService {
     const scopeSql = sql`(${sql.join(scopePreds, sql` AND `)})`;
     const candidateSql = sql`(${scopeSql} AND ${this.candidatePredicate(parsed, titleOnly)})`;
 
+    // --- Semantic (vector) arm: embed the query, degrade gracefully. (#530) ----
+    // The try/catch wraps ONLY embedQuery + vector-arm construction. On ANY throw
+    // (TEI down / 800ms timeout / no provider) we omit the vector arm entirely and
+    // run the byte-identical Phase-A lexical path — never a 500 from the sidecar.
+    // The permission filter below stays OUTSIDE this try (a permission error must
+    // 500, never fail-open). Hybrid is transparent; SEARCH_SEMANTIC=off disables it.
+    let vectorArm: RawBuilder<unknown> | null = null;
+    let semanticAvailable = false;
+    let semanticReason: 'no-provider' | 'degraded' | undefined;
+    if (!semanticKillSwitchOff()) {
+      try {
+        const { vector, fingerprint } = await this.aiService.embedQuery(
+          opts.workspaceId,
+          rawQuery,
+        );
+        vectorArm = this.pageEmbeddingRepo.vectorCandidateArm({
+          queryEmbedding: vector,
+          dimensions: vector.length,
+          fingerprint,
+          scope: scopeSql,
+          limit: getVectorCandidates(),
+          // Filter page_embeddings by (immutable) workspace_id directly, so the
+          // composite index bites on its leading column and candidates are
+          // workspace-scoped at the embedding level (#530 review WARNING 2). Space
+          // scoping stays on the pages join only — page_embeddings.space_id can be
+          // STALE after a cross-space move, so filtering it here would drop a moved
+          // page's vector hit (re-review regression fix).
+          workspaceId: scope.workspaceId,
+        });
+        semanticAvailable = true;
+      } catch (err) {
+        if (err instanceof AiEmbeddingNotConfiguredException) {
+          // No embedding provider is the DEFAULT state of any deployment without
+          // the TEI sidecar — normal, not a problem. Log at DEBUG so it never
+          // floods WARN once per search request.
+          semanticReason = 'no-provider';
+          this.logger.debug(
+            `search.semantic.no-provider workspace=${opts.workspaceId}`,
+          );
+        } else {
+          // A provider IS configured but the embed call failed/timed out — a real
+          // sidecar problem worth a WARN. Structured, greppable event (fixed code)
+          // — no query text/secrets.
+          semanticReason = 'degraded';
+          this.logger.warn(
+            `search.semantic.degraded reason=degraded workspace=${opts.workspaceId}`,
+          );
+        }
+      }
+    }
     // --- Ranked candidate ids (ALL matches, RRF order). -----------------------
-    // Two independent branches ranked SEPARATELY (FTS by ts_rank_cd, substring by
-    // tier) then fused with RRF: score = Σ 1/(k + rank_branch). Deterministic
-    // ORDER BY rrf DESC, id so pagination never dupes/skips (A4, acceptance #8).
-    const rankedRows = await sql<{ id: string }>`
-      WITH candidates AS (
-        SELECT pages.id AS id,
-               ${this.ftsScoreExpr(parsed)} AS fts_score,
-               ${this.subTierExpr(parsed, titleOnly)} AS sub_tier
-        FROM pages
-        WHERE ${candidateSql}
-      ),
-      ranked AS (
-        SELECT id, fts_score, sub_tier,
-               row_number() OVER (ORDER BY fts_score DESC NULLS LAST, id) AS rn_fts,
-               row_number() OVER (ORDER BY sub_tier DESC NULLS LAST, id) AS rn_sub
-        FROM candidates
-      )
-      SELECT id
-      FROM ranked
-      ORDER BY
-        (CASE WHEN fts_score IS NOT NULL THEN 1.0/(${RRF_K} + rn_fts) ELSE 0 END)
-        + (CASE WHEN sub_tier IS NOT NULL THEN 1.0/(${RRF_K} + rn_sub) ELSE 0 END) DESC,
-        id ASC
-    `.execute(this.db);
+    // Lexical branches ranked SEPARATELY (FTS by ts_rank_cd, substring by tier);
+    // when a query vector is available a third VECTOR branch is fused over the
+    // UNION of lexical + vector candidates. RRF: score = Σ w/(k + rank_branch).
+    // Deterministic ORDER BY rrf DESC, id so pagination never dupes/skips (A4,
+    // acceptance #8). `total` is thus the union size (lexical ∪ vector top-N),
+    // post-permission-filter — a documented change from Phase A's exact lexical
+    // count (#530). On degrade the query is byte-identical to Phase A.
+    //
+    // The fused query is bounded by a per-statement timeout (see runRankedQuery):
+    // if the brute-force vector scan is cancelled (SQLSTATE 57014) we degrade to
+    // the byte-identical lexical path — search returns lexical results, never
+    // hangs, never 500s. Only the timeout is caught here; any OTHER SQL error
+    // propagates. The permission filter below stays outside, unchanged.
+    let orderedIds: string[];
+    try {
+      orderedIds = await this.runRankedQuery(
+        candidateSql,
+        parsed,
+        titleOnly,
+        vectorArm,
+      );
+    } catch (err) {
+      if (vectorArm && isStatementTimeout(err)) {
+        semanticAvailable = false;
+        semanticReason = 'degraded';
+        this.logger.warn(
+          `search.semantic.degraded reason=degraded workspace=${opts.workspaceId} (vector statement timeout)`,
+        );
+        // Re-run the exact Phase-A lexical path (no vector arm, no timeout).
+        orderedIds = await this.runRankedQuery(
+          candidateSql,
+          parsed,
+          titleOnly,
+          null,
+        );
+      } else {
+        throw err;
+      }
+    }
 
-    let orderedIds = rankedRows.rows.map((r) => r.id);
+    const semantic: SearchSemanticDto = {
+      state: semanticAvailable ? 'full' : 'off',
+      available: semanticAvailable,
+      ...(semanticReason ? { reason: semanticReason } : {}),
+    };
 
     // --- Permission filter (fail-closed, exact total). ------------------------
     // filterAccessiblePageIds runs the #348 hasRestricted pre-check internally:
@@ -355,14 +457,131 @@ export class SearchService {
     const hasMore = offset + pageIds.length < window.length;
 
     if (pageIds.length === 0) {
-      return { items: [], total, hasMore, truncatedAtCap, offset, query: queryMeta };
+      return {
+        items: [],
+        total,
+        hasMore,
+        truncatedAtCap,
+        offset,
+        query: queryMeta,
+        semantic,
+      };
     }
 
     // --- Detail fetch for the page slice only (ts_headline/snippet are costly, so
     //     compute them ONLY for the returned rows), preserving RRF order. -------
     const items = await this.fetchDetails(pageIds, parsed, titleOnly);
 
-    return { items, total, hasMore, truncatedAtCap, offset, query: queryMeta };
+    return {
+      items,
+      total,
+      hasMore,
+      truncatedAtCap,
+      offset,
+      query: queryMeta,
+      semantic,
+    };
+  }
+
+  /**
+   * Run the ranked-candidate-ids query and return the ids in RRF order (#530).
+   *
+   * When `vectorArm` is null (degrade / semantic off / no query vector) this runs
+   * the BYTE-IDENTICAL Phase-A 2-branch lexical query — the semantic layer must
+   * be a pure superset that never changes lexical behaviour on degrade.
+   *
+   * When a vector arm is supplied it is UNION ALL'd with the lexical arm into one
+   * `candidates` set; `agg` collapses each page to its best per-branch signal
+   * (MAX fts_score / MAX sub_tier / MIN vec_distance); `ranked` assigns a
+   * per-branch row_number; the final ORDER BY fuses the three legs with RRF,
+   * adding the vector leg ONLY for rows that have a vec_distance (a lexical-only
+   * hit contributes 0 to the vector leg, and vice-versa). W_VEC weights the
+   * vector leg.
+   */
+  private async runRankedQuery(
+    candidateSql: RawBuilder<unknown>,
+    parsed: ParsedQuery,
+    titleOnly: boolean,
+    vectorArm: RawBuilder<unknown> | null,
+  ): Promise<string[]> {
+    if (!vectorArm) {
+      // Phase-A lexical path — DO NOT change (byte-identical on degrade, #529).
+      const rankedRows = await sql<{ id: string }>`
+        WITH candidates AS (
+          SELECT pages.id AS id,
+                 ${this.ftsScoreExpr(parsed)} AS fts_score,
+                 ${this.subTierExpr(parsed, titleOnly)} AS sub_tier
+          FROM pages
+          WHERE ${candidateSql}
+        ),
+        ranked AS (
+          SELECT id, fts_score, sub_tier,
+                 row_number() OVER (ORDER BY fts_score DESC NULLS LAST, id) AS rn_fts,
+                 row_number() OVER (ORDER BY sub_tier DESC NULLS LAST, id) AS rn_sub
+          FROM candidates
+        )
+        SELECT id
+        FROM ranked
+        ORDER BY
+          (CASE WHEN fts_score IS NOT NULL THEN 1.0/(${RRF_K} + rn_fts) ELSE 0 END)
+          + (CASE WHEN sub_tier IS NOT NULL THEN 1.0/(${RRF_K} + rn_sub) ELSE 0 END) DESC,
+          id ASC
+      `.execute(this.db);
+      return rankedRows.rows.map((r) => r.id);
+    }
+
+    // #530 fused 3-branch RRF over lexical ∪ vector candidates. The lexical arm
+    // adds NULL::float vec_distance to stay UNION-compatible with the vector arm.
+    const wVec = getVectorWeight();
+
+    // Bound the brute-force vector scan with a per-statement timeout, scoped to
+    // THIS query only. `set_config(..., is_local := true)` = SET LOCAL semantics:
+    // it applies within this transaction and auto-resets at COMMIT/ROLLBACK, so
+    // it can NEVER leak onto the next query that reuses this pooled connection.
+    // On a cancellation the driver raises SQLSTATE 57014, which searchPage catches
+    // to degrade to lexical-only. Running inside a transaction also guarantees the
+    // SET and the ranked query share one connection.
+    const timeoutMs = getVectorStatementTimeoutMs();
+    return this.db.transaction().execute(async (trx) => {
+      await sql`SELECT set_config('statement_timeout', ${String(timeoutMs)}, true)`.execute(
+        trx,
+      );
+      const rankedRows = await sql<{ id: string }>`
+        WITH candidates AS (
+          (SELECT pages.id AS id,
+                  ${this.ftsScoreExpr(parsed)} AS fts_score,
+                  ${this.subTierExpr(parsed, titleOnly)} AS sub_tier,
+                  NULL::float AS vec_distance
+           FROM pages
+           WHERE ${candidateSql})
+          UNION ALL
+          (${vectorArm})
+        ),
+        agg AS (
+          SELECT id,
+                 MAX(fts_score) AS fts_score,
+                 MAX(sub_tier) AS sub_tier,
+                 MIN(vec_distance) AS vec_distance
+          FROM candidates
+          GROUP BY id
+        ),
+        ranked AS (
+          SELECT id, fts_score, sub_tier, vec_distance,
+                 row_number() OVER (ORDER BY fts_score DESC NULLS LAST, id) AS rn_fts,
+                 row_number() OVER (ORDER BY sub_tier DESC NULLS LAST, id) AS rn_sub,
+                 row_number() OVER (ORDER BY vec_distance ASC NULLS LAST, id) AS rn_vec
+          FROM agg
+        )
+        SELECT id
+        FROM ranked
+        ORDER BY
+          (CASE WHEN fts_score IS NOT NULL THEN 1.0/(${RRF_K} + rn_fts) ELSE 0 END)
+          + (CASE WHEN sub_tier IS NOT NULL THEN 1.0/(${RRF_K} + rn_sub) ELSE 0 END)
+          + (CASE WHEN vec_distance IS NOT NULL THEN ${wVec}::float/(${RRF_K} + rn_vec) ELSE 0 END) DESC,
+          id ASC
+      `.execute(trx);
+      return rankedRows.rows.map((r) => r.id);
+    });
   }
 
   // Resolve the search scope: explicit space, the authed user's member spaces, or

apps/server/src/database/migrations/20260712T120000-page-embeddings-fingerprint.ts

@@ -0,0 +1,49 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * #530 Search Phase B (PR-1): add the embedding FINGERPRINT column.
+ *
+ * The fingerprint is a deterministic id of the embedding configuration that
+ * produced a row — model id + revision + query/doc prefix scheme + dimensions
+ * (see AiService.computeEmbeddingFingerprint). Search filters vector candidates
+ * by the workspace's ACTIVE fingerprint so a revision bump or a prefix-scheme
+ * change never fuses incompatible vectors into results.
+ *
+ * PR-1 scope: this migration only ADDS the column (nullable — existing rows stay
+ * NULL = legacy) and the composite index the vector-candidate scan uses. The full
+ * generational swap / GC lifecycle (target-fingerprint reindex, atomic flip,
+ * old-generation GC) is deliberately deferred to PR-2.
+ *
+ * Independent migration (per the #363 crash-loop net): it creates ONLY its own
+ * objects and never touches another migration's tables/indexes, so a partial
+ * failure cannot leave a shared object half-built.
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  // Nullable text column. Existing rows keep NULL (legacy generation) and are
+  // simply not matched by the active-fingerprint filter until re-indexed.
+  await sql`
+    ALTER TABLE page_embeddings
+      ADD COLUMN IF NOT EXISTS fingerprint text
+  `.execute(db);
+
+  // Composite btree supporting the scoped, dimension- + fingerprint-filtered
+  // vector-candidate scan (workspace_id + space_id + fingerprint + model_dimensions).
+  await db.schema
+    .createIndex('idx_page_embeddings_ws_space_fp_dim')
+    .ifNotExists()
+    .on('page_embeddings')
+    .columns(['workspace_id', 'space_id', 'fingerprint', 'model_dimensions'])
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .dropIndex('idx_page_embeddings_ws_space_fp_dim')
+    .ifExists()
+    .execute();
+
+  await sql`
+    ALTER TABLE page_embeddings
+      DROP COLUMN IF EXISTS fingerprint
+  `.execute(db);
+}

apps/server/src/database/repos/ai-chat/page-embedding.repo.ts

@@ -1,6 +1,6 @@
 import { Injectable } from '@nestjs/common';
 import { InjectKysely } from 'nestjs-kysely';
-import { sql } from 'kysely';
+import { RawBuilder, sql } from 'kysely';
 import * as pgvector from 'pgvector';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
 import { dbOrTx } from '../../utils';
@@ -35,6 +35,9 @@ export interface PageEmbeddingChunkRow {
   content: string;
   modelName: string;
   modelDimensions: number;
+  // #530 PR-1: the active embedding fingerprint (see computeEmbeddingFingerprint).
+  // null only when no provider resolves (the indexer no-ops in that case).
+  fingerprint: string | null;
   embedding: number[];
 }
 
@@ -120,6 +123,7 @@ export class PageEmbeddingRepo {
           content: row.content,
           modelName: row.modelName,
           modelDimensions: row.modelDimensions,
+          fingerprint: row.fingerprint,
           // pgvector.toSql -> '[1,2,3]'; cast the bound literal to vector.
           embedding: sql`${pgvector.toSql(row.embedding)}::vector`,
         })),
@@ -127,6 +131,82 @@ export class PageEmbeddingRepo {
       .execute();
   }
 
+  /**
+   * #530: build the VECTOR candidate arm for SearchService's fused RRF union — a
+   * page-level nearest-neighbour sub-select. Returns a `sql` fragment (not an
+   * executed query) so the caller can UNION ALL it with the lexical arm inside a
+   * single ranked-ids query.
+   *
+   * SCALING BOUNDARY: the column is dimension-agnostic, so it carries NO ANN
+   * index — this is a brute-force O(N) KNN seq scan with `<=>`. Accepted for the
+   * small-tenant / homelab fork target (ANN + a pinned-dimension column are
+   * deferred). It is NOT unbounded, though: the caller (SearchService) runs this
+   * fused query under a per-statement timeout (SEARCH_VECTOR_STATEMENT_TIMEOUT_MS)
+   * and DEGRADES to lexical-only on a 57014 cancellation, so a pathological scan
+   * can never hang the interactive search request.
+   *
+   * The arm collapses a page's chunks to its best (MIN) cosine distance:
+   *   SELECT pages.id, NULL fts_score, NULL sub_tier,
+   *          MIN(pe.embedding <=> $qvec) AS vec_distance
+   *   FROM page_embeddings pe JOIN pages ON pages.id = pe.page_id
+   *   WHERE <scope> AND pe.model_dimensions = $dim AND pe.fingerprint = $fp
+   *   GROUP BY pages.id ORDER BY vec_distance LIMIT $limit
+   *
+   * `scope` is SearchService's shared scope predicate (workspace + space/id set +
+   * creator + descendants + deleted_at), referencing the `pages` table — it must
+   * be spliced verbatim so the vector candidate set mirrors the lexical scope
+   * EXACTLY, minus the lexical text predicate (vector candidates need not match
+   * text). The vector is bound via pgvector's `toSql(...)::vector`, and both the
+   * dimension and the ACTIVE fingerprint are filtered so `<=>` only ever compares
+   * compatible, same-generation vectors (pgvector errors on a dimension
+   * mismatch; a fingerprint mismatch would fuse incomparable vectors).
+   *
+   * `workspaceId` is ALSO filtered directly on `page_embeddings` — not only via
+   * the pages join. It is IMMUTABLE (there are no cross-workspace page moves), so
+   * an embedding row's workspace_id always matches its page's, and this drops NO
+   * legitimate hit; it lets the composite index idx_page_embeddings_ws_space_fp_dim
+   * (workspace_id, space_id, fingerprint, model_dimensions) bite from its LEADING
+   * column, and workspace-scopes candidates at the embedding level (defense in
+   * depth).
+   *
+   * SPACE is deliberately NOT filtered on page_embeddings: `page_embeddings.space_id`
+   * is stamped at index time and is NOT updated when a page is MOVED between spaces
+   * (movePageToSpace does not reindex, and PAGE_MOVED_TO_SPACE has no reindex
+   * consumer), so a moved page's rows carry the OLD space until the next reindex. A
+   * `page_embeddings.space_id = ANY(scope)` predicate would then wrongly drop a
+   * legitimate vector hit for a page moved INTO the searched space. Space scoping
+   * is therefore enforced ONLY by the join to `pages` (pages.space_id ∈ scope,
+   * always current) — the same way the lexical arm scopes, so no space leak.
+   *
+   * The NULL fts_score / sub_tier columns keep the arm UNION-compatible with the
+   * lexical arm's column list.
+   */
+  vectorCandidateArm(params: {
+    queryEmbedding: number[];
+    dimensions: number;
+    fingerprint: string;
+    scope: RawBuilder<unknown>;
+    limit: number;
+    workspaceId: string;
+  }): RawBuilder<unknown> {
+    const qvec = sql`${pgvector.toSql(params.queryEmbedding)}::vector`;
+    return sql`
+      SELECT pages.id AS id,
+             NULL::float AS fts_score,
+             NULL::int AS sub_tier,
+             MIN(page_embeddings.embedding <=> ${qvec}) AS vec_distance
+      FROM page_embeddings
+      JOIN pages ON pages.id = page_embeddings.page_id
+      WHERE ${params.scope}
+        AND page_embeddings.workspace_id = ${params.workspaceId}
+        AND page_embeddings.model_dimensions = ${params.dimensions}
+        AND page_embeddings.fingerprint = ${params.fingerprint}
+      GROUP BY pages.id
+      ORDER BY vec_distance ASC
+      LIMIT ${params.limit}
+    `;
+  }
+
   /**
    * Cosine search over the embeddings, scoped to a workspace AND a set of
    * spaces the caller may read (see semanticSearch access-scoping). Orders by

apps/server/src/database/types/embeddings.types.ts

@@ -7,6 +7,11 @@ export interface PageEmbeddings {
   spaceId: string;
   modelName: string;
   modelDimensions: number;
+  // #530 PR-1: the active embedding fingerprint (model id + revision + prefix
+  // scheme + dimensions). NULL on legacy rows written before this column existed.
+  // Search filters candidates by the ACTIVE fingerprint so a revision/prefix
+  // change never mixes incompatible vectors.
+  fingerprint: string | null;
   workspaceId: string;
   // Nullable: page-body embeddings have no attachment (only attachment chunks set it).
   attachmentId: string | null;

apps/server/src/database/utils.ts

@@ -108,6 +108,23 @@ export function isUniqueViolation(err: unknown): boolean {
   return (err as { code?: unknown } | null | undefined)?.code === PG_UNIQUE_VIOLATION;
 }
 
+/** Postgres `query_canceled` SQLSTATE — raised when statement_timeout fires. */
+const PG_QUERY_CANCELED = '57014';
+
+/**
+ * Whether `err` is a Postgres statement-timeout cancellation (SQLSTATE `57014`).
+ * Used by #530 semantic search to degrade a slow vector scan to lexical-only
+ * instead of hanging/500-ing. Matches on the SQLSTATE (the driver surfaces it as
+ * `.code`), with a message fallback for any wrapper that drops the code.
+ */
+export function isStatementTimeout(err: unknown): boolean {
+  if ((err as { code?: unknown } | null | undefined)?.code === PG_QUERY_CANCELED) {
+    return true;
+  }
+  const msg = err instanceof Error ? err.message : '';
+  return /canceling statement due to statement timeout/i.test(msg);
+}
+
 /**
  * The name of the UNIQUE index/constraint a `23505` error violated, or
  * undefined. The `kysely-postgres-js` / `postgres@3.x` driver surfaces it as

apps/server/src/integrations/ai/ai.service.embedding.spec.ts

@@ -0,0 +1,143 @@
+import { AiService, computeEmbeddingFingerprint } from './ai.service';
+
+/**
+ * #530 Search Phase B (PR-1) unit coverage for the embedding layer:
+ *  - computeEmbeddingFingerprint: a revision bump / prefix toggle MUST change the
+ *    fingerprint even when the bare model name + dimension are unchanged (it is
+ *    deliberately NOT the bare model name);
+ *  - embedQuery: applies the QUERY prefix and embeds under the short SEARCH embed
+ *    timeout (not the long batch timeout);
+ *  - embedWithModel: a hung model + short timeout degrades with a clear timeout
+ *    error (the search caller then falls back to the lexical path).
+ */
+describe('computeEmbeddingFingerprint (#530)', () => {
+  const base = {
+    modelId: 'intfloat/multilingual-e5-small',
+    revision: 'sha-aaa',
+    queryPrefix: 'query: ',
+    docPrefix: 'passage: ',
+    dimensions: 384,
+  };
+
+  it('is deterministic for identical inputs', () => {
+    expect(computeEmbeddingFingerprint(base)).toBe(
+      computeEmbeddingFingerprint({ ...base }),
+    );
+  });
+
+  it('CHANGES on a revision bump (same model name + dimension)', () => {
+    const a = computeEmbeddingFingerprint(base);
+    const b = computeEmbeddingFingerprint({ ...base, revision: 'sha-bbb' });
+    expect(b).not.toBe(a);
+  });
+
+  it('CHANGES on a query-prefix toggle (same model name + dimension + revision)', () => {
+    const a = computeEmbeddingFingerprint(base);
+    const b = computeEmbeddingFingerprint({ ...base, queryPrefix: '' });
+    expect(b).not.toBe(a);
+  });
+
+  it('CHANGES on a doc-prefix toggle', () => {
+    const a = computeEmbeddingFingerprint(base);
+    const b = computeEmbeddingFingerprint({ ...base, docPrefix: '' });
+    expect(b).not.toBe(a);
+  });
+
+  it('CHANGES on a dimension change', () => {
+    const a = computeEmbeddingFingerprint(base);
+    const b = computeEmbeddingFingerprint({ ...base, dimensions: 768 });
+    expect(b).not.toBe(a);
+  });
+
+  it('is NOT the bare model name (guards the mutation)', () => {
+    // If the fingerprint were the bare model name, a revision bump would not
+    // change it — the tests above would red. Assert it directly too.
+    expect(computeEmbeddingFingerprint(base)).not.toBe(base.modelId);
+  });
+
+  it('distinguishes swapped prefixes — ("q","") != ("","q")', () => {
+    const a = computeEmbeddingFingerprint({
+      ...base,
+      queryPrefix: 'q',
+      docPrefix: '',
+    });
+    const b = computeEmbeddingFingerprint({
+      ...base,
+      queryPrefix: '',
+      docPrefix: 'q',
+    });
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('AiService.embedQuery (#530)', () => {
+  function makeService(): AiService {
+    // The constructor body only stores its deps; embedQuery is fully driven by
+    // the spied resolveEmbeddingProvider + embedWithModel below.
+    return new AiService({} as any, {} as any, {} as any);
+  }
+
+  it('prepends the query prefix and returns the provider fingerprint', async () => {
+    const svc = makeService();
+    jest.spyOn(svc, 'resolveEmbeddingProvider').mockResolvedValue({
+      model: { modelId: 'm' } as any,
+      queryPrefix: 'query: ',
+      docPrefix: 'passage: ',
+      fingerprint: 'fp-active',
+    });
+    const embedSpy = jest
+      .spyOn(svc, 'embedWithModel')
+      .mockResolvedValue([[0.1, 0.2, 0.3]]);
+
+    const res = await svc.embedQuery('ws-1', 'кофе');
+
+    // The single embedded value carries the query prefix.
+    expect(embedSpy).toHaveBeenCalledTimes(1);
+    const [, wsArg, valuesArg, timeoutArg] = embedSpy.mock.calls[0];
+    expect(wsArg).toBe('ws-1');
+    expect(valuesArg).toEqual(['query: кофе']);
+    // Bound by the SHORT search-embed timeout (default 800ms), not the 120000ms
+    // batch timeout.
+    expect(timeoutArg).toBe(800);
+    expect(res).toEqual({ vector: [0.1, 0.2, 0.3], fingerprint: 'fp-active' });
+  });
+
+  it('propagates a no-provider error (drives the no-provider degrade)', async () => {
+    const svc = makeService();
+    const { AiEmbeddingNotConfiguredException } = await import(
+      './ai-embedding-not-configured.exception'
+    );
+    jest
+      .spyOn(svc, 'resolveEmbeddingProvider')
+      .mockRejectedValue(new AiEmbeddingNotConfiguredException());
+    await expect(svc.embedQuery('ws-1', 'x')).rejects.toBeInstanceOf(
+      AiEmbeddingNotConfiguredException,
+    );
+  });
+});
+
+describe('AiService.embedWithModel timeout (#530)', () => {
+  it('degrades a hung model with a timeout error under the short window', async () => {
+    const svc = new AiService({} as any, {} as any, {} as any);
+    // A model whose doEmbed never resolves but honours the abort signal, so the
+    // AbortSignal.timeout fires and embedWithModel raises a clear timeout error.
+    const hangingModel: any = {
+      specificationVersion: 'v2',
+      provider: 'fake',
+      modelId: 'fake',
+      maxEmbeddingsPerCall: 100,
+      supportsParallelCalls: true,
+      doEmbed: ({ abortSignal }: { abortSignal?: AbortSignal }) =>
+        new Promise((_resolve, reject) => {
+          abortSignal?.addEventListener('abort', () => {
+            const err = new Error('The operation was aborted');
+            err.name = 'AbortError';
+            reject(err);
+          });
+        }),
+    };
+    await expect(
+      svc.embedWithModel(hangingModel, 'ws-1', ['x'], 30),
+    ).rejects.toThrow(/timed out/i);
+  });
+});

apps/server/src/integrations/ai/ai.service.ts

@@ -23,6 +23,50 @@ import {
 import { AiProviderCredentialsRepo } from '@docmost/db/repos/ai-chat/ai-provider-credentials.repo';
 import { SecretBoxService } from '../crypto/secret-box';
 import { AiDriver } from './ai.types';
+import { createHash } from 'node:crypto';
+
+/**
+ * A resolved embedding provider for #530 semantic search. `model` is the AI SDK
+ * embedding model; `queryPrefix`/`docPrefix` are prepended to a query / a stored
+ * chunk respectively (e5-style `"query: "` / `"passage: "`, empty for a non-e5
+ * provider); `fingerprint` is the deterministic id of the whole configuration.
+ */
+export interface ResolvedEmbeddingProvider {
+  model: EmbeddingModel;
+  queryPrefix: string;
+  docPrefix: string;
+  fingerprint: string;
+}
+
+/**
+ * Deterministic embedding FINGERPRINT (#530). Encodes model id + revision +
+ * prefix scheme + dimensions so that ANY of them changing (a revision bump, a
+ * prefix toggle) yields a DIFFERENT fingerprint even when the bare model name and
+ * dimension are unchanged. Deliberately NOT the bare model name: two rows from
+ * the same model but a different revision/prefix must not be fused together.
+ *
+ * Exported as a pure function so it can be unit-tested in isolation and reused by
+ * the indexer without a service instance.
+ */
+export function computeEmbeddingFingerprint(parts: {
+  modelId: string;
+  revision: string;
+  queryPrefix: string;
+  docPrefix: string;
+  dimensions: number | null;
+}): string {
+  // The two prefixes are SEPARATE keys (not a concatenated string): JSON.stringify
+  // escapes each independently, so the prefix scheme ("a","") is distinct from
+  // ("","a") with no separator/collision hazard even if a prefix contains spaces.
+  const canonical = JSON.stringify({
+    m: parts.modelId,
+    r: parts.revision,
+    q: parts.queryPrefix,
+    d: parts.docPrefix,
+    dim: parts.dimensions ?? 0,
+  });
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 32);
+}
 
 /**
  * Optional chat-model override carried by an agent role (`ai_agent_roles.
@@ -362,11 +406,112 @@ export class AiService {
   async embedTexts(workspaceId: string, texts: string[]): Promise<number[][]> {
     if (texts.length === 0) return [];
     const model = await this.getEmbeddingModel(workspaceId);
-    // Bound the embedding call: a slow/hung embeddings endpoint must fail loudly
-    // (and let the caller move on to the next page) instead of blocking forever.
-    // The single signal caps the WHOLE call, including the SDK's internal
-    // retries/backoff (embedMany defaults to maxRetries: 2).
-    const timeoutMs = AiService.embeddingTimeoutMs();
+    return this.embedWithModel(model, workspaceId, texts);
+  }
+
+  /**
+   * #530: resolve the embedding provider for a workspace. Prefers the workspace's
+   * own configured embedding provider; falls back to the GLOBAL env provider (a
+   * TEI sidecar via the OpenAI-compatible path) when the workspace has none.
+   * Returns the model + the query/doc prefixes + the config fingerprint. Throws
+   * AiEmbeddingNotConfiguredException when NEITHER resolves, so callers can drive
+   * a `no-provider` degrade path.
+   */
+  async resolveEmbeddingProvider(
+    workspaceId: string,
+  ): Promise<ResolvedEmbeddingProvider> {
+    // 1. Per-workspace provider (uses the workspace's own creds/endpoint). When
+    //    it is not configured getEmbeddingModel throws the not-configured
+    //    exception; we swallow ONLY that and fall through to the global provider.
+    try {
+      const model = await this.getEmbeddingModel(workspaceId);
+      const modelId =
+        typeof model === 'string' ? model : (model.modelId ?? 'unknown');
+      // A per-workspace (typically non-e5) provider gets no e5-style prefixes.
+      return {
+        model,
+        queryPrefix: '',
+        docPrefix: '',
+        fingerprint: computeEmbeddingFingerprint({
+          modelId,
+          revision: 'workspace',
+          queryPrefix: '',
+          docPrefix: '',
+          dimensions: null,
+        }),
+      };
+    } catch (err) {
+      if (!(err instanceof AiEmbeddingNotConfiguredException)) throw err;
+    }
+
+    // 2. Global env provider (TEI sidecar). TEI is OpenAI-compatible, so reuse
+    //    the existing openai path — no new SDK. A dummy key is fine for a
+    //    keyless self-hosted sidecar.
+    const endpoint = process.env.EMBEDDING_ENDPOINT?.trim();
+    const globalModel = process.env.EMBEDDING_MODEL?.trim();
+    if (endpoint && globalModel) {
+      const model = createOpenAI({
+        baseURL: endpoint,
+        apiKey: process.env.EMBEDDING_API_KEY || 'unused',
+      }).textEmbeddingModel(globalModel);
+      const queryPrefix = process.env.EMBEDDING_QUERY_PREFIX ?? '';
+      const docPrefix = process.env.EMBEDDING_DOC_PREFIX ?? '';
+      const dimRaw = Number(process.env.EMBEDDING_DIMENSIONS);
+      const dimensions = Number.isFinite(dimRaw) && dimRaw > 0 ? dimRaw : null;
+      return {
+        model,
+        queryPrefix,
+        docPrefix,
+        fingerprint: computeEmbeddingFingerprint({
+          modelId: globalModel,
+          revision: process.env.EMBEDDING_REVISION ?? '',
+          queryPrefix,
+          docPrefix,
+          dimensions,
+        }),
+      };
+    }
+
+    // Neither resolved -> drives semantic.reason=no-provider.
+    throw new AiEmbeddingNotConfiguredException();
+  }
+
+  /**
+   * #530: embed a SEARCH QUERY. Resolves the provider, prepends its query prefix,
+   * and embeds the single value under its OWN short timeout
+   * (SEARCH_EMBED_TIMEOUT_MS, default 800ms) — NOT the long batch-indexing
+   * timeout — so a slow/hung sidecar degrades search fast. Throws on
+   * timeout/error (the caller degrades to the lexical-only path). Returns the
+   * vector plus the active fingerprint used to filter candidate rows.
+   */
+  async embedQuery(
+    workspaceId: string,
+    text: string,
+  ): Promise<{ vector: number[]; fingerprint: string }> {
+    const provider = await this.resolveEmbeddingProvider(workspaceId);
+    const [vector] = await this.embedWithModel(
+      provider.model,
+      workspaceId,
+      [provider.queryPrefix + text],
+      AiService.searchEmbedTimeoutMs(),
+    );
+    return { vector, fingerprint: provider.fingerprint };
+  }
+
+  /**
+   * Embed values with an EXPLICIT model, bounded by `timeoutMs` (default: the
+   * batch-indexing timeout). Shared core of embedTexts / embedQuery: a slow/hung
+   * embeddings endpoint must fail loudly instead of blocking forever. The single
+   * signal caps the WHOLE call, including the SDK's internal retries/backoff
+   * (embedMany defaults to maxRetries: 2).
+   */
+  async embedWithModel(
+    model: EmbeddingModel,
+    workspaceId: string,
+    texts: string[],
+    timeoutMs: number = AiService.embeddingTimeoutMs(),
+  ): Promise<number[][]> {
+    if (texts.length === 0) return [];
     const signal = AbortSignal.timeout(timeoutMs);
     try {
       const { embeddings } = await embedMany({
@@ -391,8 +536,8 @@ export class AiService {
       if (signal.aborted && abortLike) {
         throw new Error(
           `Embedding request timed out after ${timeoutMs}ms ` +
-            `(workspace ${workspaceId}, ${texts.length} chunk(s)). ` +
-            `Increase AI_EMBEDDING_TIMEOUT_MS or check the embeddings endpoint.`,
+            `(workspace ${workspaceId}, ${texts.length} value(s)). ` +
+            `Increase the embedding timeout or check the embeddings endpoint.`,
         );
       }
       throw err;
@@ -408,6 +553,16 @@ export class AiService {
     return Number.isFinite(raw) && raw > 0 ? raw : 120_000;
   }
 
+  /**
+   * #530: per-call timeout for the interactive SEARCH query embed. Much shorter
+   * than the batch-indexing timeout (a search request cannot wait 2 minutes on
+   * the sidecar). Configurable via SEARCH_EMBED_TIMEOUT_MS; default 800ms.
+   */
+  private static searchEmbedTimeoutMs(): number {
+    const raw = Number(process.env.SEARCH_EMBED_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : 800;
+  }
+
   // Build a tiny valid WAV (mono, 16-bit PCM, 16 kHz, ~1s of silence), used only
   // as a connectivity probe for the STT endpoint in testConnection.
   private static silentWavProbe(): Uint8Array {

apps/server/src/integrations/environment/environment.service.ts

@@ -70,23 +70,6 @@ export class EnvironmentService {
     return this.configService.get<string>('JWT_TOKEN_EXPIRES_IN', '90d');
   }
 
-  // Kill-switch for the agent API-key feature. Default ON (unset -> enabled): a
-  // deploy that never sets the variable must NOT silently kill every agent. The
-  // parse is STRICT — the value is validated by environment.validation to be
-  // exactly 'true' or 'false' (or absent), so a typo like `=0`/`=off`/`=False`
-  // fails at boot rather than being read as "enabled" (which would leave an
-  // operator who yanked the switch during an incident with it still on). When
-  // OFF: validate() denies every api-key token and the issuance endpoints 404.
-  isApiKeysEnabled(): boolean {
-    return this.configService.get<string>('API_KEYS_ENABLED', 'true') !== 'false';
-  }
-
-  // Raw value (or undefined) for the boot log, so the state after each deploy is
-  // verifiable in container logs: `API keys: ENABLED/DISABLED (API_KEYS_ENABLED=...)`.
-  getApiKeysEnabledRaw(): string | undefined {
-    return this.configService.get<string>('API_KEYS_ENABLED');
-  }
-
   getCookieExpiresIn(): Date {
     const expiresInStr = this.getJwtTokenExpiresIn();
     let msUntilExpiry: number;

apps/server/src/integrations/environment/environment.validation.ts

@@ -103,15 +103,6 @@ export class EnvironmentVariables {
   @IsString()
   TYPESENSE_LOCALE: string;
 
-  // Agent API-key kill-switch. Optional (absent -> default ON). STRICT: only the
-  // literals 'true'/'false' are accepted, so `=0`/`=off`/`=False` fail at boot
-  // instead of being silently read as "enabled" — the switch must actually flip
-  // when an operator flips it. See EnvironmentService.isApiKeysEnabled.
-  @IsOptional()
-  @IsIn(['true', 'false'])
-  @IsString()
-  API_KEYS_ENABLED: string;
-
   @IsOptional()
   @ValidateIf((obj) => obj.AI_DRIVER)
   @IsIn(['openai', 'openai-compatible', 'gemini', 'ollama'])

apps/server/test/integration/search-lexical.int-spec.ts

@@ -1,7 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { Kysely, sql } from 'kysely';
+import { Logger } from '@nestjs/common';
 import { SearchService } from 'src/core/search/search.service';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { PageEmbeddingRepo } from '@docmost/db/repos/ai-chat/page-embedding.repo';
+import { AiEmbeddingNotConfiguredException } from 'src/integrations/ai/ai-embedding-not-configured.exception';
 import {
   getTestDb,
   destroyTestDb,
@@ -53,10 +56,19 @@ describe('SearchService #529 lexical overhaul [integration]', () => {
   // Service wired to the real DB + real PageRepo (recursive descendants) with
   // stubbed space-membership + permission repos so a test controls scope and the
   // permission filter explicitly. `accessibleIds` (when set) is the KEEP list.
+  // #530: a FAKE AiService whose embedQuery is fully controlled per test. By
+  // DEFAULT it throws AiEmbeddingNotConfiguredException, so the semantic arm is
+  // omitted and every Phase-A case runs the BYTE-IDENTICAL lexical path — the
+  // semantic layer must never change lexical behaviour on degrade. Semantic cases
+  // pass `embedVector` (a deterministic 384-dim query vector) or `embedThrows`.
   function buildService(opts?: {
     userSpaceIds?: string[];
     accessibleIds?: string[] | null;
     filterThrows?: boolean;
+    embedVector?: number[];
+    embedFingerprint?: string;
+    embedThrows?: 'no-provider' | 'degraded';
+    slowVectorArm?: boolean;
   }): SearchService {
     const pageRepo = new PageRepo(db as any, null as any, null as any);
     const spaceMemberRepo = {
@@ -71,15 +83,86 @@ describe('SearchService #529 lexical overhaul [integration]', () => {
           : pageIds;
       },
     };
+    const aiService = {
+      embedQuery: async () => {
+        if (opts?.embedVector) {
+          return {
+            vector: opts.embedVector,
+            fingerprint: opts.embedFingerprint ?? ACTIVE_FP,
+          };
+        }
+        if (opts?.embedThrows === 'degraded') {
+          const err = new Error('embedding request timed out after 1ms');
+          err.name = 'TimeoutError';
+          throw err;
+        }
+        // Default (and explicit 'no-provider'): no embedding provider resolved.
+        throw new AiEmbeddingNotConfiguredException();
+      },
+    };
+    // Real repo on the migrated test DB — exercises the actual vector-candidate
+    // SQL (pgvector <=>, fingerprint + dimension filters). When slowVectorArm is
+    // set, wrap the arm so it sleeps well past the (tiny, test-set) statement
+    // timeout, forcing a 57014 cancellation to exercise the degrade-to-lexical net.
+    const realRepo = new PageEmbeddingRepo(db as any);
+    const pageEmbeddingRepo = opts?.slowVectorArm
+      ? {
+          vectorCandidateArm: (p: any) => {
+            const inner = realRepo.vectorCandidateArm(p);
+            return sql`SELECT * FROM (${inner}) AS slowarm WHERE (SELECT true FROM pg_sleep(0.5))`;
+          },
+        }
+      : realRepo;
     return new SearchService(
       db as any,
       pageRepo as any,
       {} as any,
       spaceMemberRepo as any,
       pagePermissionRepo as any,
+      aiService as any,
+      pageEmbeddingRepo as any,
     );
   }
 
+  // Active embedding fingerprint used by planted rows + the fake query embed.
+  const ACTIVE_FP = 'fp-active-530';
+
+  // A deterministic unit-ish 384-dim vector with a single 1 at `concept`. Two
+  // vectors of the same concept have cosine distance 0; different concepts are
+  // orthogonal (distance 1), so nearest-neighbour ordering is fully controlled.
+  function conceptVec(concept: number): number[] {
+    const v = new Array(384).fill(0);
+    v[concept % 384] = 1;
+    return v;
+  }
+
+  // Plant one chunk embedding for a page via the REAL repo (exercises the #530
+  // fingerprint insert path). Dimension is fixed at 384 to match conceptVec.
+  async function plantEmbedding(
+    pageId: string,
+    vector: number[],
+    fingerprint: string = ACTIVE_FP,
+    planSpaceId: string = spaceId,
+  ): Promise<void> {
+    const repo = new PageEmbeddingRepo(db as any);
+    await repo.insertChunks([
+      {
+        pageId,
+        workspaceId,
+        spaceId: planSpaceId,
+        attachmentId: null,
+        chunkIndex: 0,
+        chunkStart: 0,
+        chunkLength: 1,
+        content: 'planted chunk',
+        modelName: 'test-model',
+        modelDimensions: 384,
+        fingerprint,
+        embedding: vector,
+      },
+    ]);
+  }
+
   const search = (service: SearchService, params: any) =>
     service.searchPage(params, { userId: 'u-1', workspaceId }) as any;
 
@@ -609,4 +692,324 @@ describe('SearchService #529 lexical overhaul [integration]', () => {
     expect(hit2).toBeDefined();
     expect(hit2.path).toEqual([]);
   });
+
+  // === #530 Phase B (PR-1): semantic fusion ==================================
+  // Deterministic fake embedder (no live model) + real PageEmbeddingRepo on the
+  // migrated DB with planted vectors + the active fingerprint, so cosine ordering
+  // is fully controlled. Each case runs in its OWN space so planted rows never
+  // leak across tests.
+  describe('#530 semantic fusion', () => {
+    // 1. Vector-only hit: nearest to a page that has NO lexical match for the
+    //    query term — it appears via the vector arm, and a pure-lexical run does
+    //    not return it. Mutation (a): drop the vector arm -> this reddens.
+    it('#530-1 a vector-only hit appears; a pure-lexical run would not return it', async () => {
+      const s = (await createSpace(db, workspaceId)).id;
+      const page = await insertPage({
+        title: 'нейтральный вект заголовок',
+        textContent: 'содержимое без искомого термина',
+        spaceId: s,
+      });
+      await plantEmbedding(page, conceptVec(1), ACTIVE_FP, s);
+
+      const svc = buildService({ embedVector: conceptVec(1), userSpaceIds: [s] });
+      const res = await search(svc, { query: 'квазонимикс', spaceId: s });
+      expect(res.items.map((i: any) => i.id)).toContain(page);
+      expect(res.semantic.available).toBe(true);
+      expect(res.semantic.state).toBe('full');
+
+      // Pure-lexical (default degrade): the vector-only page is absent.
+      const lex = buildService({ userSpaceIds: [s] });
+      const res2 = await search(lex, { query: 'квазонимикс', spaceId: s });
+      expect(res2.items.map((i: any) => i.id)).not.toContain(page);
+      expect(res2.semantic.available).toBe(false);
+    });
+
+    // 2. Sidecar down: embedQuery throws -> results = the lexical set; semantic
+    //    unavailable; the fixed 'search.semantic.degraded' event is logged.
+    it('#530-2 sidecar-down degrades to lexical and logs search.semantic.degraded', async () => {
+      const s = (await createSpace(db, workspaceId)).id;
+      const lexHit = await insertPage({
+        title: 'семдвамаркер лексический',
+        textContent: 'обычный текст',
+        spaceId: s,
+      });
+      const warnSpy = jest
+        .spyOn(Logger.prototype, 'warn')
+        .mockImplementation(() => undefined as any);
+      try {
+        const svc = buildService({ embedThrows: 'degraded', userSpaceIds: [s] });
+        const res = await search(svc, { query: 'семдвамаркер', spaceId: s });
+        expect(res.items.map((i: any) => i.id)).toContain(lexHit);
+        expect(res.semantic.available).toBe(false);
+        expect(res.semantic.reason).toBe('degraded');
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('search.semantic.degraded'),
+        );
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    // 3. No provider: resolveEmbeddingProvider yields none -> lexical results,
+    //    reason no-provider, no 500.
+    it('#530-3 no-provider yields lexical results with reason no-provider', async () => {
+      const s = (await createSpace(db, workspaceId)).id;
+      const hit = await insertPage({
+        title: 'семтримаркер тема',
+        textContent: 'текст',
+        spaceId: s,
+      });
+      const svc = buildService({ embedThrows: 'no-provider', userSpaceIds: [s] });
+      const res = await search(svc, { query: 'семтримаркер', spaceId: s });
+      expect(res.items.map((i: any) => i.id)).toContain(hit);
+      expect(res.semantic.available).toBe(false);
+      expect(res.semantic.reason).toBe('no-provider');
+    });
+
+    // 4. Permission over the union: a restricted vector-only hit is dropped from
+    //    items AND total; with the permission filter throwing the call rejects
+    //    (fail-closed, never fail-open). Mutation (b): move filterAccessiblePageIds
+    //    inside the semantic try/catch -> the reject assertion reddens.
+    it('#530-4 permission filters a vector-only hit from items AND total (fail-closed)', async () => {
+      const s = (await createSpace(db, workspaceId)).id;
+      const visibleLex = await insertPage({
+        title: 'семчетмаркер видимый',
+        textContent: 'доступный текст',
+        spaceId: s,
+      });
+      const hiddenVec = await insertPage({
+        title: 'скрытая вект страница',
+        textContent: 'содержимое без искомого термина',
+        spaceId: s,
+      });
+      await plantEmbedding(hiddenVec, conceptVec(4), ACTIVE_FP, s);
+
+      // Query hits visibleLex lexically; hiddenVec only via the vector arm.
+      const svc = buildService({
+        embedVector: conceptVec(4),
+        accessibleIds: [visibleLex],
+        userSpaceIds: [s],
+      });
+      const res = await search(svc, { query: 'семчетмаркер', spaceId: s });
+      const ids = res.items.map((i: any) => i.id);
+      expect(ids).toContain(visibleLex);
+      expect(ids).not.toContain(hiddenVec);
+      // The hidden vector hit does not leak into total either.
+      expect(res.total).toBe(1);
+      expect(ids).toHaveLength(res.total);
+
+      // A permission-query error PROPAGATES (never a fail-open empty result).
+      const boom = buildService({
+        embedVector: conceptVec(4),
+        filterThrows: true,
+        userSpaceIds: [s],
+      });
+      await expect(
+        search(boom, { query: 'семчетмаркер', spaceId: s }),
+      ).rejects.toThrow(/permission query failed/);
+    });
+
+    // 5. Hung sidecar under a short embed timeout: graceful degrade (never a 500).
+    it('#530-5 a hung sidecar under a short timeout degrades gracefully', async () => {
+      const s = (await createSpace(db, workspaceId)).id;
+      const hit = await insertPage({
+        title: 'семпятьмаркер тема',
+        textContent: 'текст',
+        spaceId: s,
+      });
+      process.env.SEARCH_EMBED_TIMEOUT_MS = '1';
+      try {
+        const svc = buildService({ embedThrows: 'degraded', userSpaceIds: [s] });
+        const res = await search(svc, { query: 'семпятьмаркер', spaceId: s });
+        expect(res.items.map((i: any) => i.id)).toContain(hit);
+        expect(res.semantic.available).toBe(false);
+        expect(res.semantic.reason).toBe('degraded');
+      } finally {
+        delete process.env.SEARCH_EMBED_TIMEOUT_MS;
+      }
+    });
+
+    // 6. A page matched BOTH lexically and by vector is fused (de-duped), not
+    //    returned twice — the agg CTE collapses it to one row.
+    it('#530-6 a page matched lexically AND by vector appears once', async () => {
+      const s = (await createSpace(db, workspaceId)).id;
+      const both = await insertPage({
+        title: 'семшестьмаркер общий',
+        textContent: 'и лексика и вектор',
+        spaceId: s,
+      });
+      await plantEmbedding(both, conceptVec(6), ACTIVE_FP, s);
+      const svc = buildService({ embedVector: conceptVec(6), userSpaceIds: [s] });
+      const res = await search(svc, { query: 'семшестьмаркер', spaceId: s });
+      const ids = res.items.map((i: any) => i.id);
+      expect(ids.filter((id: string) => id === both)).toHaveLength(1);
+      expect(res.total).toBe(1);
+    });
+
+    // 7. Fingerprint isolation: a planted row under a DIFFERENT fingerprint is not
+    //    a vector candidate for the active-fingerprint query (guards mixing
+    //    generations). It only appears if it also matches lexically (it does not).
+    it('#530-7 a stale-fingerprint vector row is not fused into results', async () => {
+      const s = (await createSpace(db, workspaceId)).id;
+      const stale = await insertPage({
+        title: 'нейтральный семь заголовок',
+        textContent: 'без искомого термина совсем',
+        spaceId: s,
+      });
+      // Same concept vector as the query, but an OLD generation fingerprint.
+      await plantEmbedding(stale, conceptVec(7), 'fp-stale-old', s);
+      const svc = buildService({ embedVector: conceptVec(7), userSpaceIds: [s] });
+      const res = await search(svc, { query: 'квазонимиксseven', spaceId: s });
+      expect(res.items.map((i: any) => i.id)).not.toContain(stale);
+    });
+
+    // 8. Stale embedding space_id (moved page): a page currently in space B whose
+    //    embedding rows still carry space A (movePageToSpace does NOT reindex) is
+    //    STILL a vector hit when searching B — space scoping is enforced only by
+    //    the pages join (pages.space_id, always current), NOT by a stale
+    //    page_embeddings.space_id. Guards against re-adding that predicate (which
+    //    would wrongly drop the moved page's vector-only hit).
+    it('#530-8 a vector hit with a STALE embedding space_id (moved page) is still returned', async () => {
+      const newSpace = (await createSpace(db, workspaceId)).id;
+      const oldSpace = (await createSpace(db, workspaceId)).id;
+      // The page currently lives in newSpace (as after a move into newSpace).
+      const page = await insertPage({
+        title: 'перемещённая вект страница',
+        textContent: 'содержимое без искомого термина',
+        spaceId: newSpace,
+      });
+      // Its embedding was stamped with the OLD space and never reindexed.
+      await plantEmbedding(page, conceptVec(8), ACTIVE_FP, oldSpace);
+      const svc = buildService({
+        embedVector: conceptVec(8),
+        userSpaceIds: [newSpace],
+      });
+      const res = await search(svc, {
+        query: 'квазонимиксeight',
+        spaceId: newSpace,
+      });
+      // Survives despite page_embeddings.space_id (oldSpace) != pages.space_id.
+      expect(res.items.map((i: any) => i.id)).toContain(page);
+      expect(res.semantic.available).toBe(true);
+    });
+
+    // 9. Statement-timeout safety net: a pathologically slow vector scan is
+    //    cancelled (SQLSTATE 57014) and search degrades to lexical-only — the
+    //    lexical hit survives, the vector-only hit vanishes, no 500/hang, and the
+    //    degraded event is logged. Mutation: make the fallback re-throw instead of
+    //    degrading -> this test reds (the call rejects with 57014).
+    it('#530-9 a vector-query timeout degrades to lexical (57014), never 500', async () => {
+      const s = (await createSpace(db, workspaceId)).id;
+      const lexHit = await insertPage({
+        title: 'семдевятьмаркер лексический',
+        textContent: 'обычный текст',
+        spaceId: s,
+      });
+      const vecOnly = await insertPage({
+        title: 'нейтральный девять заголовок',
+        textContent: 'без искомого термина',
+        spaceId: s,
+      });
+      await plantEmbedding(vecOnly, conceptVec(9), ACTIVE_FP, s);
+
+      const warnSpy = jest
+        .spyOn(Logger.prototype, 'warn')
+        .mockImplementation(() => undefined as any);
+      // Tiny per-statement timeout so the 0.5s sleeping arm is cancelled.
+      process.env.SEARCH_VECTOR_STATEMENT_TIMEOUT_MS = '50';
+      try {
+        const svc = buildService({
+          embedVector: conceptVec(9),
+          slowVectorArm: true,
+          userSpaceIds: [s],
+        });
+        const res = await search(svc, { query: 'семдевятьмаркер', spaceId: s });
+        // Lexical result survives; the vector-only page does NOT (arm cancelled).
+        const ids = res.items.map((i: any) => i.id);
+        expect(ids).toContain(lexHit);
+        expect(ids).not.toContain(vecOnly);
+        expect(res.semantic.available).toBe(false);
+        expect(res.semantic.reason).toBe('degraded');
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('search.semantic.degraded'),
+        );
+      } finally {
+        delete process.env.SEARCH_VECTOR_STATEMENT_TIMEOUT_MS;
+        warnSpy.mockRestore();
+      }
+    });
+
+    // 10. SET LOCAL scoping: the search's statement timeout must NOT leak onto a
+    //     later query on the same pooled connection. After a search that set a
+    //     tiny timeout, a deliberately-slow standalone query still completes.
+    it('#530-10 the per-query statement timeout does not leak to later queries', async () => {
+      const s = (await createSpace(db, workspaceId)).id;
+      await insertPage({
+        title: 'семдесятьмаркер тема',
+        textContent: 'текст',
+        spaceId: s,
+      });
+      process.env.SEARCH_VECTOR_STATEMENT_TIMEOUT_MS = '50';
+      try {
+        const svc = buildService({
+          embedVector: conceptVec(10),
+          slowVectorArm: true,
+          userSpaceIds: [s],
+        });
+        // This search trips + resets the local timeout (via SET LOCAL semantics).
+        await search(svc, { query: 'семдесятьмаркер', spaceId: s });
+        // A subsequent query that sleeps 200ms must NOT be cancelled — proving the
+        // 50ms search timeout did not persist on the connection (it would raise
+        // 57014 if it had leaked). SET LOCAL auto-resets at the search tx end.
+        await expect(sql`SELECT pg_sleep(0.2)`.execute(db)).resolves.toBeDefined();
+      } finally {
+        delete process.env.SEARCH_VECTOR_STATEMENT_TIMEOUT_MS;
+      }
+    });
+
+    // 11. COMMIT-path no-leak (locks is_local=true). #530-10 only covers the
+    //     ROLLBACK path (a timed-out search rolls back — a plain session SET would
+    //     ALSO be undone on rollback, so it would NOT catch is_local true->false).
+    //     Here a NORMAL, FAST semantic search COMMITs its transaction; a leaked
+    //     session-level statement_timeout would then persist on the pooled
+    //     connection and cancel later queries. We prove it does NOT: after the
+    //     committing search (bounded at a small 100ms), a 300ms query succeeds.
+    //     Because postgres.js pools, we run several sequential slow queries so at
+    //     least one reuses the connection the committed search ran on (which is
+    //     where a leaked timeout would live); ALL must succeed. Mutation: flip
+    //     is_local true->false -> the committed 100ms timeout leaks and the
+    //     follow-up pg_sleep is cancelled (57014), reddening this test.
+    it('#530-11 a COMMITTED search does not leak its statement timeout (is_local)', async () => {
+      const s = (await createSpace(db, workspaceId)).id;
+      const page = await insertPage({
+        title: 'семодиннадцать вект страница',
+        textContent: 'содержимое без искомого термина',
+        spaceId: s,
+      });
+      await plantEmbedding(page, conceptVec(11), ACTIVE_FP, s);
+      // Small bound: the fast vector arm still completes (<100ms) so the search
+      // COMMITs, but small enough that a LEAKED timeout would cancel the 300ms
+      // follow-ups below.
+      process.env.SEARCH_VECTOR_STATEMENT_TIMEOUT_MS = '100';
+      try {
+        const svc = buildService({
+          embedVector: conceptVec(11),
+          userSpaceIds: [s],
+        });
+        const res = await search(svc, { query: 'семодиннадцать', spaceId: s });
+        // The (committing) vector path actually ran.
+        expect(res.semantic.available).toBe(true);
+        // Each 300ms query must SUCCEED — a leaked 100ms timeout would cancel the
+        // one that reuses the committed search's connection. 8 sweeps cover the
+        // whole pool (max 5 conns), so a leak on any connection is caught.
+        for (let i = 0; i < 8; i++) {
+          await expect(
+            sql`SELECT pg_sleep(0.3)`.execute(db),
+          ).resolves.toBeDefined();
+        }
+      } finally {
+        delete process.env.SEARCH_VECTOR_STATEMENT_TIMEOUT_MS;
+      }
+    });
+  });
 });

docker-compose.yml

@@ -4,11 +4,26 @@ services:
     depends_on:
       - db
       - redis
+      - embeddings
     environment:
       APP_URL: 'http://localhost:3000'
       APP_SECRET: 'REPLACE_WITH_LONG_SECRET'
       DATABASE_URL: 'postgresql://docmost:STRONG_DB_PASSWORD@db:5432/docmost'
       REDIS_URL: 'redis://redis:6379'
+      # #530 semantic search: the GLOBAL embedding provider (the `embeddings` TEI
+      # sidecar below). A workspace that configures its own embedding provider
+      # overrides this. TEI is OpenAI-compatible, so the endpoint is /v1.
+      EMBEDDING_ENDPOINT: 'http://embeddings:80/v1'
+      EMBEDDING_MODEL: 'intfloat/multilingual-e5-small'
+      EMBEDDING_API_KEY: 'unused'
+      EMBEDDING_DIMENSIONS: '384'
+      # MUST match the --revision the sidecar pins (see EMBEDDING_REVISION in
+      # .env). A revision bump changes the embedding fingerprint (PR-2 swaps
+      # generations); keep the two in lockstep.
+      EMBEDDING_REVISION: '${EMBEDDING_REVISION}'
+      # e5 models require these input prefixes; empty them for a non-e5 model.
+      EMBEDDING_QUERY_PREFIX: 'query: '
+      EMBEDDING_DOC_PREFIX: 'passage: '
     ports:
       - "3000:3000"
     restart: unless-stopped
@@ -39,7 +54,33 @@ services:
     volumes:
       - redis_data:/data
 
+  # #530 Text Embeddings Inference (TEI) sidecar — the GLOBAL embedding provider
+  # for semantic search. OpenAI-compatible, reached only on the internal network
+  # (no published port). The model + revision are PINNED so the embedding
+  # fingerprint is stable; set EMBEDDING_REVISION to a real commit sha in .env.
+  embeddings:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9
+    command:
+      - "--model-id"
+      - "intfloat/multilingual-e5-small"
+      - "--revision"
+      - "${EMBEDDING_REVISION}"
+    restart: unless-stopped
+    # Cache downloaded model weights so a restart does not re-download them.
+    volumes:
+      - tei-models:/data
+    # GET /health is TEI's readiness probe. (Drop this block if your TEI image
+    # variant ships without curl.)
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://localhost:80/health || exit 1"]
+      interval: 30s
+      timeout: 5s
+      retries: 5
+      # Model download on first boot can be slow; don't flap as unhealthy meanwhile.
+      start_period: 120s
+
 volumes:
   docmost:
   db_data:
   redis_data:
+  tei-models: