From dd79bfdcd2189db66f36c191bf9552e46868f30f Mon Sep 17 00:00:00 2001
From: ntorbinskiy <n.torbinskiy@gmail.com>
Date: Thu, 3 Sep 2026 15:23:44 +0300
Subject: [PATCH 1/2] feat(reins): port knowledge base UX and index-state work
 from the Mazda fork (CLEAN-60)

---
 .../agent/components/agent/knowledge/Tab.vue  |   4 +-
 .../knowledge/SourceStatusBadge.vue           |  34 +
 .../components/knowledge/create/Provider.vue  |   2 +-
 .../components/knowledge/edit/Provider.vue    |  49 --
 .../knowledge/graph/LabelPicker.vue           | 144 ++++
 .../components/knowledge/graph/Provider.vue   |  78 +-
 .../knowledge/indexStatus/Badge.vue           |  25 +-
 .../components/knowledge/list/Provider.vue    |   2 +-
 .../knowledge/overview/Provider.vue           | 337 ++++++++
 .../components/knowledge/setup/Wizard.vue     |   4 +-
 .../components/knowledge/sources/AddForm.vue  | 178 -----
 .../knowledge/sources/AddFromArchiveForm.vue  |  97 ---
 .../knowledge/sources/AddFromSitemapForm.vue  | 108 ---
 .../components/knowledge/sources/AddSheet.vue | 358 +++++++++
 .../knowledge/sources/ImportProgress.vue      |  98 +++
 .../knowledge/sources/PreviewSheet.vue        | 166 ++++
 .../components/knowledge/sources/Provider.vue | 473 ++++++++++--
 admin/slices/reins/data/knowledge.gateway.ts  | 107 ++-
 admin/slices/reins/data/knowledge.mapper.ts   | 111 ++-
 admin/slices/reins/domain/format.ts           |  49 ++
 admin/slices/reins/domain/index.ts            |   1 +
 .../slices/reins/domain/knowledge.gateway.ts  |  18 +-
 .../slices/reins/domain/knowledge.service.ts  |  29 +-
 admin/slices/reins/domain/knowledge.types.ts  |  78 ++
 admin/slices/reins/pages/knowledges/[id].vue  | 230 ++++--
 .../reins/pages/knowledges/[id]/edit.vue      |   3 -
 .../reins/pages/knowledges/[id]/index.vue     |  13 +-
 admin/slices/reins/stores/knowledge.ts        | 103 ++-
 .../api/data/repositories/api/schemas.gen.ts  | 198 ++++-
 .../api/data/repositories/api/sdk.gen.ts      |  62 +-
 .../api/data/repositories/api/types.gen.ts    | 154 +++-
 .../components/ui/sidebar/SidebarInset.vue    |   9 +-
 api/package.json                              |   2 +
 .../migration.sql                             |   5 +
 api/src/slices/aws/s3/s3.repository.ts        |  35 +
 api/src/slices/aws/s3/s3.types.ts             |  12 +
 api/src/slices/reins/README.md                | 143 ++++
 .../reins/knowledge/data/knowledge.gateway.ts |  37 +-
 .../reins/knowledge/data/knowledge.mapper.ts  |   4 +-
 .../domain/indexReconcile.service.ts          | 149 ++++
 .../knowledge/domain/indexReconcile.spec.ts   | 215 ++++++
 .../knowledge/domain/knowledge.gateway.ts     |  18 +-
 .../knowledge/domain/knowledge.service.ts     | 201 +++--
 .../reins/knowledge/domain/knowledge.types.ts |  20 +-
 .../reins/knowledge/dtos/knowledge.dto.ts     |  13 +
 .../reins/knowledge/knowledge.controller.ts   |  15 +-
 .../knowledge/knowledge.isolation.spec.ts     |  19 +
 .../reins/knowledge/knowledge.module.ts       |   2 +
 .../reins/knowledge/knowledge.tool.spec.ts    |  78 +-
 .../slices/reins/knowledge/knowledge.tool.ts  |  23 +-
 .../lightrag/data/lightragHttp.client.ts      | 195 +++--
 .../slices/reins/lightrag/data/workspace.ts   |  17 +
 .../reins/lightrag/domain/lightrag.client.ts  |  11 +
 .../reins/lightrag/domain/lightrag.types.ts   |  76 +-
 .../domain/migration.service.spec.ts          |  57 +-
 .../migration/domain/migration.service.ts     |   4 +-
 .../reins/source/data/source.gateway.spec.ts  | 482 ++++++++++++
 .../reins/source/data/source.gateway.ts       | 724 +++++++++++++++++-
 .../reins/source/data/source.mapper.spec.ts   |  32 +
 .../slices/reins/source/data/source.mapper.ts |  21 +
 .../source/data/sourceArchive.writer.spec.ts  | 153 ++++
 .../reins/source/data/sourceArchive.writer.ts | 131 ++++
 .../reins/source/domain/archiveLimit.ts       |  15 +
 .../source/domain/importJob.registry.spec.ts  |  93 +++
 .../reins/source/domain/importJob.registry.ts |  92 +++
 .../reins/source/domain/indexBudget.spec.ts   |  97 +++
 .../slices/reins/source/domain/indexBudget.ts | 101 +++
 .../reins/source/domain/source.gateway.ts     |  38 +
 .../reins/source/domain/source.service.ts     | 140 +++-
 .../reins/source/domain/source.types.ts       | 109 +++
 .../reins/source/dtos/addFromArchive.dto.ts   |  11 +-
 .../reins/source/dtos/exportSources.dto.ts    |  39 +
 .../reins/source/dtos/filterSources.dto.ts    |  41 +
 .../slices/reins/source/dtos/importJob.dto.ts |  25 +
 api/src/slices/reins/source/dtos/index.ts     |   5 +
 .../slices/reins/source/dtos/source.dto.ts    |  23 +-
 .../source/dtos/sourceContent.query.dto.ts    |  21 +
 .../reins/source/dtos/sourcePage.dto.ts       |  11 +
 .../slices/reins/source/source.controller.ts  | 200 ++++-
 api/src/slices/reins/source/source.module.ts  |   2 +
 api/src/slices/reins/source/source.prisma     |   1 +
 bun.lock                                      |  30 +-
 82 files changed, 6456 insertions(+), 854 deletions(-)
 create mode 100644 admin/slices/reins/components/knowledge/SourceStatusBadge.vue
 delete mode 100644 admin/slices/reins/components/knowledge/edit/Provider.vue
 create mode 100644 admin/slices/reins/components/knowledge/graph/LabelPicker.vue
 create mode 100644 admin/slices/reins/components/knowledge/overview/Provider.vue
 delete mode 100644 admin/slices/reins/components/knowledge/sources/AddForm.vue
 delete mode 100644 admin/slices/reins/components/knowledge/sources/AddFromArchiveForm.vue
 delete mode 100644 admin/slices/reins/components/knowledge/sources/AddFromSitemapForm.vue
 create mode 100644 admin/slices/reins/components/knowledge/sources/AddSheet.vue
 create mode 100644 admin/slices/reins/components/knowledge/sources/ImportProgress.vue
 create mode 100644 admin/slices/reins/components/knowledge/sources/PreviewSheet.vue
 create mode 100644 admin/slices/reins/domain/format.ts
 delete mode 100644 admin/slices/reins/pages/knowledges/[id]/edit.vue
 create mode 100644 api/prisma/migrations/20260903130000_source_list_index/migration.sql
 create mode 100644 api/src/slices/reins/README.md
 create mode 100644 api/src/slices/reins/knowledge/domain/indexReconcile.service.ts
 create mode 100644 api/src/slices/reins/knowledge/domain/indexReconcile.spec.ts
 create mode 100644 api/src/slices/reins/source/data/source.gateway.spec.ts
 create mode 100644 api/src/slices/reins/source/data/source.mapper.spec.ts
 create mode 100644 api/src/slices/reins/source/data/sourceArchive.writer.spec.ts
 create mode 100644 api/src/slices/reins/source/data/sourceArchive.writer.ts
 create mode 100644 api/src/slices/reins/source/domain/archiveLimit.ts
 create mode 100644 api/src/slices/reins/source/domain/importJob.registry.spec.ts
 create mode 100644 api/src/slices/reins/source/domain/importJob.registry.ts
 create mode 100644 api/src/slices/reins/source/domain/indexBudget.spec.ts
 create mode 100644 api/src/slices/reins/source/domain/indexBudget.ts
 create mode 100644 api/src/slices/reins/source/dtos/exportSources.dto.ts
 create mode 100644 api/src/slices/reins/source/dtos/filterSources.dto.ts
 create mode 100644 api/src/slices/reins/source/dtos/importJob.dto.ts
 create mode 100644 api/src/slices/reins/source/dtos/sourceContent.query.dto.ts
 create mode 100644 api/src/slices/reins/source/dtos/sourcePage.dto.ts

diff --git a/admin/slices/agent/agent/components/agent/knowledge/Tab.vue b/admin/slices/agent/agent/components/agent/knowledge/Tab.vue
index ed37bb4e..51170aa8 100644
--- a/admin/slices/agent/agent/components/agent/knowledge/Tab.vue
+++ b/admin/slices/agent/agent/components/agent/knowledge/Tab.vue
@@ -152,7 +152,7 @@ function unbindMissing(id: string): void {
                 v-for="k in resolved"
                 :key="k.id"
                 class="cursor-pointer"
-                @click="navigateTo(`/knowledges/${k.id}/edit`)"
+                @click="navigateTo(`/knowledges/${k.id}`)"
               >
                 <TableCell class="font-medium">{{ k.name }}</TableCell>
                 <TableCell class="max-w-md truncate text-muted-foreground">
@@ -167,7 +167,7 @@ function unbindMissing(id: string): void {
                 <TableCell @click.stop>
                   <div class="flex justify-end gap-2">
                     <Button size="sm" variant="outline" as-child>
-                      <NuxtLink :to="`/knowledges/${k.id}/edit`">Open</NuxtLink>
+                      <NuxtLink :to="`/knowledges/${k.id}`">Open</NuxtLink>
                     </Button>
                   </div>
                 </TableCell>
diff --git a/admin/slices/reins/components/knowledge/SourceStatusBadge.vue b/admin/slices/reins/components/knowledge/SourceStatusBadge.vue
new file mode 100644
index 00000000..5cb695ca
--- /dev/null
+++ b/admin/slices/reins/components/knowledge/SourceStatusBadge.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import { Badge } from '#theme/components/ui/badge';
+import type { SourceIndexStatus } from '#reins/stores/knowledge';
+
+const props = defineProps<{ status: SourceIndexStatus }>();
+
+const label = computed(() => {
+  switch (props.status) {
+    case 'indexed':
+      return 'Indexed';
+    case 'failed':
+      return 'Failed';
+    case 'pending':
+      return 'Pending';
+    default:
+      return props.status;
+  }
+});
+
+const variant = computed<'default' | 'destructive' | 'outline'>(() => {
+  switch (props.status) {
+    case 'indexed':
+      return 'default';
+    case 'failed':
+      return 'destructive';
+    default:
+      return 'outline';
+  }
+});
+</script>
+
+<template>
+  <Badge :variant="variant">{{ label }}</Badge>
+</template>
diff --git a/admin/slices/reins/components/knowledge/create/Provider.vue b/admin/slices/reins/components/knowledge/create/Provider.vue
index aac841a4..910264a2 100644
--- a/admin/slices/reins/components/knowledge/create/Provider.vue
+++ b/admin/slices/reins/components/knowledge/create/Provider.vue
@@ -14,7 +14,7 @@ async function onSubmit(values: IKnowledgeFormValues) {
       description: values.description,
     });
     if (created) {
-      await navigateTo(`/knowledges/${created.id}/edit`);
+      await navigateTo(`/knowledges/${created.id}`);
     } else {
       await navigateTo('/knowledges');
     }
diff --git a/admin/slices/reins/components/knowledge/edit/Provider.vue b/admin/slices/reins/components/knowledge/edit/Provider.vue
deleted file mode 100644
index 8a992bf7..00000000
--- a/admin/slices/reins/components/knowledge/edit/Provider.vue
+++ /dev/null
@@ -1,49 +0,0 @@
-<script setup lang="ts">
-import type { IKnowledge } from '#reins/stores/knowledge';
-import type { IKnowledgeFormValues } from '#reins/components/knowledge/item/Form.vue';
-
-const store = useKnowledgeStore();
-const current = inject<Ref<IKnowledge | null>>('knowledge-current');
-const refresh = inject<() => Promise<void>>('knowledge-refresh');
-
-const submitting = ref(false);
-const errorMessage = ref<string | null>(null);
-
-async function onSubmit(values: IKnowledgeFormValues) {
-  if (!current?.value) return;
-  submitting.value = true;
-  errorMessage.value = null;
-  try {
-    await store.update(current.value.id, {
-      name: values.name,
-      description: values.description ?? null,
-    });
-    if (refresh) await refresh();
-  } catch (err: unknown) {
-    const e = err as { response?: { data?: { message?: string } }; message?: string };
-    errorMessage.value = e?.response?.data?.message ?? e?.message ?? 'Update failed';
-  } finally {
-    submitting.value = false;
-  }
-}
-
-function onCancel() {
-  navigateTo('/knowledges');
-}
-</script>
-
-<template>
-  <div v-if="current" class="max-w-2xl">
-    <p v-if="errorMessage" class="mb-3 text-xs text-destructive">{{ errorMessage }}</p>
-    <KnowledgeItemForm
-      :initial-values="{
-        name: current.name,
-        description: current.description ?? undefined,
-      }"
-      :submitting="submitting"
-      submit-label="Save"
-      @submit="onSubmit"
-      @cancel="onCancel"
-    />
-  </div>
-</template>
diff --git a/admin/slices/reins/components/knowledge/graph/LabelPicker.vue b/admin/slices/reins/components/knowledge/graph/LabelPicker.vue
new file mode 100644
index 00000000..6362d4a4
--- /dev/null
+++ b/admin/slices/reins/components/knowledge/graph/LabelPicker.vue
@@ -0,0 +1,144 @@
+<script setup lang="ts">
+import { onClickOutside } from '@vueuse/core';
+
+/**
+ * Entity picker for the graph.
+ *
+ * This replaces a plain `<Select>` fed the raw label list, which is what froze
+ * the tab. `/graph/label/list` returns every entity in the whole index - tens
+ * of thousands of them once a real corpus is indexed - and the select mounted a
+ * DOM node for each one on open. Nothing here renders more than MAX_VISIBLE
+ * rows no matter how long the list is; the rest is reached by typing.
+ */
+const ALL = '*';
+const ALL_LABEL = '* (all entities)';
+const MAX_VISIBLE = 50;
+
+const props = defineProps<{
+  modelValue: string;
+  labels: string[];
+  loading?: boolean;
+}>();
+
+const emit = defineEmits<{ 'update:modelValue': [value: string] }>();
+
+const root = ref<HTMLElement | null>(null);
+const open = ref(false);
+const query = ref('');
+
+function displayFor(value: string): string {
+  return value === ALL ? ALL_LABEL : value;
+}
+
+// Matching is done against a lowercased copy built once per label list rather
+// than per keystroke: on 50k entries the difference is the whole point.
+const lowerLabels = computed(() => props.labels.map((l) => l.toLowerCase()));
+
+const filtered = computed<string[]>(() => {
+  const q = query.value.trim().toLowerCase();
+  if (!q) return props.labels;
+  const lower = lowerLabels.value;
+  const found: string[] = [];
+  for (let i = 0; i < lower.length; i += 1) {
+    if (lower[i].includes(q)) found.push(props.labels[i]);
+  }
+  return found;
+});
+
+const visible = computed(() => filtered.value.slice(0, MAX_VISIBLE));
+const hiddenCount = computed(() =>
+  Math.max(0, filtered.value.length - MAX_VISIBLE),
+);
+
+// "* (all)" stays reachable whatever is typed: it is the default view and not
+// an entity in the list.
+const showAllOption = computed(() => {
+  const q = query.value.trim().toLowerCase();
+  return q === '' || ALL_LABEL.includes(q) || q === ALL;
+});
+
+function pick(value: string): void {
+  emit('update:modelValue', value);
+  query.value = displayFor(value);
+  open.value = false;
+}
+
+function focus(): void {
+  open.value = true;
+  // Clearing on focus makes the whole list browsable again; otherwise the
+  // current selection would filter it down to itself.
+  query.value = '';
+}
+
+function close(): void {
+  if (!open.value) return;
+  open.value = false;
+  query.value = displayFor(props.modelValue);
+}
+
+watch(
+  () => props.modelValue,
+  (value) => {
+    if (!open.value) query.value = displayFor(value);
+  },
+  { immediate: true },
+);
+
+onClickOutside(root, close);
+</script>
+
+<template>
+  <div ref="root" class="relative">
+    <Input
+      :model-value="query"
+      :placeholder="loading ? 'Loading entities…' : 'Search entities…'"
+      :disabled="loading"
+      class="w-64"
+      role="combobox"
+      :aria-expanded="open"
+      @focus="focus"
+      @keydown.esc="close"
+      @update:model-value="(v: string | number) => { query = String(v); open = true; }"
+    />
+
+    <div
+      v-if="open"
+      class="absolute z-50 mt-1 max-h-72 w-64 overflow-y-auto rounded-md border bg-popover p-1 shadow-md"
+    >
+      <button
+        v-if="showAllOption"
+        type="button"
+        class="w-full rounded-sm px-2 py-1.5 text-left text-sm hover:bg-accent"
+        :class="modelValue === ALL ? 'bg-accent font-medium' : ''"
+        @click="pick(ALL)"
+      >
+        {{ ALL_LABEL }}
+      </button>
+
+      <button
+        v-for="label in visible"
+        :key="label"
+        type="button"
+        class="w-full truncate rounded-sm px-2 py-1.5 text-left text-sm hover:bg-accent"
+        :class="modelValue === label ? 'bg-accent font-medium' : ''"
+        :title="label"
+        @click="pick(label)"
+      >
+        {{ label }}
+      </button>
+
+      <p
+        v-if="hiddenCount"
+        class="px-2 py-1.5 text-xs text-muted-foreground"
+      >
+        {{ hiddenCount }} more - keep typing to narrow it down
+      </p>
+      <p
+        v-else-if="!visible.length && !showAllOption"
+        class="px-2 py-1.5 text-xs text-muted-foreground"
+      >
+        Nothing matches "{{ query }}"
+      </p>
+    </div>
+  </div>
+</template>
diff --git a/admin/slices/reins/components/knowledge/graph/Provider.vue b/admin/slices/reins/components/knowledge/graph/Provider.vue
index 9dbf5f28..6300fce7 100644
--- a/admin/slices/reins/components/knowledge/graph/Provider.vue
+++ b/admin/slices/reins/components/knowledge/graph/Provider.vue
@@ -3,6 +3,7 @@ import Sigma from 'sigma';
 import type { SigmaNodeEventPayload, SigmaEdgeEventPayload } from 'sigma/types';
 import Graph from 'graphology';
 import forceAtlas2 from 'graphology-layout-forceatlas2';
+import FA2Layout from 'graphology-layout-forceatlas2/worker';
 import {
   ComboboxAnchor,
   ComboboxContent,
@@ -36,8 +37,17 @@ const selectedNode = ref<GraphNodeDto | null>(null);
 const selectedEdge = ref<GraphEdgeDto | null>(null);
 const nodes = ref<GraphNodeDto[]>([]);
 
+// How long the layout is allowed to keep running after a graph is drawn.
+// It runs in a worker, so this only bounds how long positions keep moving.
+const LAYOUT_RUN_MS = 4000;
+// Above this many nodes the O(n^2) repulsion pass gets a Barnes-Hut
+// approximation; below it the exact pass is cheaper than the quadtree.
+const BARNES_HUT_FROM_NODES = 50;
+
 let renderer: Sigma | null = null;
 let graph: Graph | null = null;
+let layout: FA2Layout | null = null;
+let layoutTimer: ReturnType<typeof setTimeout> | null = null;
 const nodeIndex = new Map<string, GraphNodeDto>();
 const edgeIndex = new Map<string, GraphEdgeDto>();
 
@@ -105,6 +115,8 @@ function renderGraph(data: GraphDto): void {
   ensureRenderer();
   if (!graph) return;
 
+  // The worker mutates this graph; it has to go before the contents do.
+  stopLayout();
   graph.clear();
   nodeIndex.clear();
   edgeIndex.clear();
@@ -114,15 +126,20 @@ function renderGraph(data: GraphDto): void {
 
   const nodeSize = data.nodes.length > 50 ? 6 : data.nodes.length > 20 ? 8 : 10;
 
-  for (const node of data.nodes) {
-    graph.addNode(node.id, {
-      x: Math.random(),
-      y: Math.random(),
+  // Seeded on a circle rather than at random: the layout starts from an
+  // untangled state, so it converges in far fewer passes and the first frame
+  // is already readable instead of a knot.
+  const g = graph;
+  data.nodes.forEach((node, i) => {
+    const angle = (2 * Math.PI * i) / data.nodes.length;
+    g.addNode(node.id, {
+      x: Math.cos(angle),
+      y: Math.sin(angle),
       size: nodeSize,
       label: node.label,
       color: colorForType(node.entityType),
     });
-  }
+  });
 
   for (const edge of data.edges) {
     if (!graph.hasNode(edge.source) || !graph.hasNode(edge.target)) continue;
@@ -134,21 +151,53 @@ function renderGraph(data: GraphDto): void {
   }
 
   if (graph.order > 0) {
-    const settings = forceAtlas2.inferSettings(graph);
-    forceAtlas2.assign(graph, {
-      iterations: 200,
-      settings: {
-        ...settings,
-        gravity: 1,
-        scalingRatio: 10,
-      },
-    });
     normalizeAndFit();
+    startLayout();
   }
 
   renderer?.refresh();
 }
 
+/**
+ * ForceAtlas2 in a web worker. The synchronous `forceAtlas2.assign` this
+ * replaces ran 200 passes on the main thread, which froze the whole tab for
+ * ~15s on a dense graph (repulsion is quadratic in nodes, attraction linear in
+ * edges). The worker keeps the UI interactive while positions settle, and the
+ * run is cut off after LAYOUT_RUN_MS so it cannot spin forever.
+ */
+function startLayout(): void {
+  stopLayout();
+  if (!graph || graph.order === 0) return;
+
+  const settings = forceAtlas2.inferSettings(graph);
+  layout = new FA2Layout(graph, {
+    settings: {
+      ...settings,
+      gravity: 1,
+      scalingRatio: 10,
+      barnesHutOptimize: graph.order > BARNES_HUT_FROM_NODES,
+    },
+  });
+  layout.start();
+
+  layoutTimer = setTimeout(() => {
+    stopLayout();
+    normalizeAndFit();
+    renderer?.refresh();
+  }, LAYOUT_RUN_MS);
+}
+
+function stopLayout(): void {
+  if (layoutTimer !== null) {
+    clearTimeout(layoutTimer);
+    layoutTimer = null;
+  }
+  if (layout) {
+    layout.kill();
+    layout = null;
+  }
+}
+
 function normalizeAndFit(): void {
   if (!graph || !renderer) return;
   const g = graph;
@@ -253,6 +302,7 @@ onMounted(async () => {
 });
 
 onBeforeUnmount(() => {
+  stopLayout();
   renderer?.kill();
   renderer = null;
   graph = null;
diff --git a/admin/slices/reins/components/knowledge/indexStatus/Badge.vue b/admin/slices/reins/components/knowledge/indexStatus/Badge.vue
index 8c228a71..3f6ad314 100644
--- a/admin/slices/reins/components/knowledge/indexStatus/Badge.vue
+++ b/admin/slices/reins/components/knowledge/indexStatus/Badge.vue
@@ -2,9 +2,22 @@
 import type { IndexStatus } from '#reins/stores/knowledge';
 import { Badge as UiBadge } from '#theme/components/ui/badge';
 
-const props = defineProps<{ status: IndexStatus }>();
+// `processing` is not a fifth status, it is what the stored one cannot say.
+// A run stops waiting long before LightRAG finishes a large document, so the
+// row reads `ready` while a third of the content is still being chunked. The
+// green "Ready" badge on a base that is only two thirds searchable is what
+// sent people off believing an import had landed. Kept out of `IndexStatus`
+// on purpose: that value also gates the Index button and the 3s poll, and a
+// base waiting on the pipeline must stay indexable - new sources arrive while
+// old ones are still cooking.
+const props = defineProps<{ status: IndexStatus; processing?: boolean }>();
+
+const stillWorking = computed(
+  () => props.processing === true && props.status === 'ready',
+);
 
 const label = computed(() => {
+  if (stillWorking.value) return 'Ready · still indexing';
   switch (props.status) {
     case 'idle':
       return 'Idle';
@@ -25,6 +38,8 @@ const label = computed(() => {
 
 const variant = computed<'default' | 'secondary' | 'destructive' | 'outline'>(
   () => {
+    // Deliberately not the green `default`: searchable, but not all of it.
+    if (stillWorking.value) return 'secondary';
     switch (props.status) {
       case 'ready':
         return 'default';
@@ -38,8 +53,14 @@ const variant = computed<'default' | 'secondary' | 'destructive' | 'outline'>(
     }
   },
 );
+
+const title = computed(() =>
+  stillWorking.value
+    ? 'Some documents are still moving through LightRAG. They are confirmed automatically as it finishes.'
+    : undefined,
+);
 </script>
 
 <template>
-  <UiBadge :variant="variant">{{ label }}</UiBadge>
+  <UiBadge :variant="variant" :title="title">{{ label }}</UiBadge>
 </template>
diff --git a/admin/slices/reins/components/knowledge/list/Provider.vue b/admin/slices/reins/components/knowledge/list/Provider.vue
index 60ffbcda..01f5be22 100644
--- a/admin/slices/reins/components/knowledge/list/Provider.vue
+++ b/admin/slices/reins/components/knowledge/list/Provider.vue
@@ -125,7 +125,7 @@ async function onRemove(item: IKnowledge) {
             <TableCell @click.stop>
               <div class="flex justify-end gap-2">
                 <Button size="sm" variant="outline" as-child>
-                  <NuxtLink :to="`/knowledges/${item.id}/edit`">Edit</NuxtLink>
+                  <NuxtLink :to="`/knowledges/${item.id}`">Open</NuxtLink>
                 </Button>
                 <Button
                   size="sm"
diff --git a/admin/slices/reins/components/knowledge/overview/Provider.vue b/admin/slices/reins/components/knowledge/overview/Provider.vue
new file mode 100644
index 00000000..7ff67b0e
--- /dev/null
+++ b/admin/slices/reins/components/knowledge/overview/Provider.vue
@@ -0,0 +1,337 @@
+<script setup lang="ts">
+import type { IKnowledge, SourceType } from '#reins/stores/knowledge';
+import { errorMessageOf, formatDateTime } from '#reins/domain';
+
+const store = useKnowledgeStore();
+const current = inject<Ref<IKnowledge | null>>('knowledge-current');
+const refresh = inject<() => Promise<void>>('knowledge-refresh');
+
+const knowledgeId = computed(() => current?.value?.id ?? '');
+
+// ---- counters --------------------------------------------------------------
+
+// `pending` is everything not yet accounted for. It is derived rather than
+// returned so the four tiles always add up to the total, whatever the API
+// reports.
+const counts = computed(() => {
+  const k = current?.value;
+  if (!k) return { total: 0, indexed: 0, processing: 0, failed: 0, pending: 0 };
+  const pending = Math.max(
+    0,
+    k.sourceCount - k.indexedCount - k.processingCount - k.failedCount,
+  );
+  return {
+    total: k.sourceCount,
+    indexed: k.indexedCount,
+    processing: k.processingCount,
+    failed: k.failedCount,
+    pending,
+  };
+});
+
+const progressPercent = computed(() => {
+  const { total, indexed } = counts.value;
+  return total === 0 ? 0 : Math.round((indexed / total) * 100);
+});
+
+// ---- breakdown by type -----------------------------------------------------
+
+const TYPES: readonly SourceType[] = ['file', 'url', 'text'];
+const TYPE_LABELS: Record<SourceType, string> = {
+  file: 'Files',
+  url: 'URLs',
+  text: 'Text',
+};
+
+const typeCounts = ref<Record<SourceType, number> | null>(null);
+
+// One head request per type: `total` comes back on a page of one row, so this
+// is three tiny queries rather than pulling 355 records to count them here.
+async function loadTypeCounts(): Promise<void> {
+  const id = knowledgeId.value;
+  if (!id) return;
+  try {
+    const pages = await Promise.all(
+      TYPES.map((type) => store.listSources(id, { page: 1, perPage: 1, type })),
+    );
+    const next: Record<SourceType, number> = { file: 0, url: 0, text: 0 };
+    TYPES.forEach((type, i) => {
+      next[type] = pages[i].total;
+    });
+    typeCounts.value = next;
+  } catch {
+    // A breakdown is a nicety. Losing it must not blank the page.
+    typeCounts.value = null;
+  }
+}
+
+const presentTypes = computed<Array<[SourceType, number]>>(() => {
+  const counted = typeCounts.value;
+  if (!counted) return [];
+  return TYPES.map((type): [SourceType, number] => [type, counted[type]]).filter(
+    ([, n]) => n > 0,
+  );
+});
+
+// ---- runtime ---------------------------------------------------------------
+
+const runtime = computed(() => store.runtime);
+const setup = computed(() => store.setup);
+
+const setupChecks = computed(() => [
+  { label: 'Service URL', ok: setup.value.hasUrl },
+  { label: 'Chat model selected', ok: setup.value.hasCredentialsSelected },
+  { label: 'S3 bucket', ok: setup.value.hasBucket },
+  { label: 'Reachable', ok: setup.value.isHealthy },
+]);
+
+onMounted(() => {
+  // `statusChecked` survives navigation inside the console, so this is a first
+  // visit only cost.
+  if (!store.statusChecked) void store.fetchStatus();
+  void loadTypeCounts();
+});
+
+watch(knowledgeId, () => {
+  void loadTypeCounts();
+});
+
+// ---- details form ----------------------------------------------------------
+
+const name = ref('');
+const description = ref('');
+const submitting = ref(false);
+const errorMessage = ref<string | null>(null);
+const savedAt = ref<number | null>(null);
+
+// Keyed on the id, not on the object. The parent re-fetches this knowledge
+// every few seconds while a run is in flight and hands back a fresh object each
+// time; syncing on that would retype the fields under the user mid-sentence.
+watch(
+  knowledgeId,
+  () => {
+    const k = current?.value;
+    if (!k) return;
+    name.value = k.name;
+    description.value = k.description ?? '';
+  },
+  { immediate: true },
+);
+
+const nameError = computed<string | null>(() => {
+  const trimmed = name.value.trim();
+  if (!trimmed) return 'Name is required';
+  if (trimmed.length < 2) return 'Name must be at least 2 characters';
+  return null;
+});
+
+const dirty = computed(() => {
+  const k = current?.value;
+  if (!k) return false;
+  return (
+    name.value.trim() !== k.name ||
+    description.value.trim() !== (k.description ?? '')
+  );
+});
+
+async function save(): Promise<void> {
+  const k = current?.value;
+  if (!k || nameError.value) return;
+  submitting.value = true;
+  errorMessage.value = null;
+  try {
+    await store.update(k.id, {
+      name: name.value.trim(),
+      description: description.value.trim() || null,
+    });
+    if (refresh) await refresh();
+    savedAt.value = Date.now();
+  } catch (err: unknown) {
+    errorMessage.value = errorMessageOf(err, 'Could not save');
+  } finally {
+    submitting.value = false;
+  }
+}
+</script>
+
+<template>
+  <div v-if="current" class="flex min-w-0 flex-col gap-6">
+    <section class="grid gap-3 sm:grid-cols-2 xl:grid-cols-4">
+      <div class="rounded-md border bg-card p-4">
+        <p class="text-xs text-muted-foreground">Sources</p>
+        <p class="mt-1 text-2xl font-semibold">{{ counts.total }}</p>
+      </div>
+      <div class="rounded-md border bg-card p-4">
+        <p class="text-xs text-muted-foreground">Indexed</p>
+        <p class="mt-1 text-2xl font-semibold">{{ counts.indexed }}</p>
+        <p class="text-xs text-muted-foreground">{{ progressPercent }}% of total</p>
+      </div>
+      <div class="rounded-md border bg-card p-4">
+        <p class="text-xs text-muted-foreground">Processing</p>
+        <p class="mt-1 text-2xl font-semibold">{{ counts.processing }}</p>
+        <p class="text-xs text-muted-foreground">
+          Handed over, confirmed automatically
+        </p>
+      </div>
+      <div
+        class="rounded-md border bg-card p-4"
+        :class="counts.failed ? 'border-destructive/40' : ''"
+      >
+        <p class="text-xs text-muted-foreground">Failed</p>
+        <p
+          class="mt-1 text-2xl font-semibold"
+          :class="counts.failed ? 'text-destructive' : ''"
+        >
+          {{ counts.failed }}
+        </p>
+        <p v-if="counts.pending" class="text-xs text-muted-foreground">
+          {{ counts.pending }} never sent
+        </p>
+      </div>
+    </section>
+
+    <div class="grid min-w-0 gap-6 lg:grid-cols-2">
+      <section class="flex min-w-0 flex-col gap-6">
+        <div class="rounded-md border bg-card p-4">
+          <h2 class="text-sm font-semibold">Details</h2>
+          <div class="mt-4 grid gap-4">
+            <div class="grid gap-2">
+              <Label for="knowledge-name">Name</Label>
+              <Input
+                id="knowledge-name"
+                v-model="name"
+                :aria-invalid="!!nameError"
+              />
+              <p v-if="nameError" class="text-xs text-destructive">
+                {{ nameError }}
+              </p>
+            </div>
+            <div class="grid gap-2">
+              <Label for="knowledge-description">Description</Label>
+              <Textarea
+                id="knowledge-description"
+                v-model="description"
+                rows="3"
+                placeholder="Optional"
+              />
+            </div>
+            <p v-if="errorMessage" class="text-xs text-destructive">
+              {{ errorMessage }}
+            </p>
+            <div class="flex items-center gap-3">
+              <Button
+                :disabled="submitting || !dirty || !!nameError"
+                @click="save"
+              >
+                {{ submitting ? 'Saving…' : 'Save' }}
+              </Button>
+              <span v-if="savedAt && !dirty" class="text-xs text-muted-foreground">
+                Saved
+              </span>
+            </div>
+          </div>
+        </div>
+
+        <div class="rounded-md border bg-card p-4">
+          <h2 class="text-sm font-semibold">Content</h2>
+          <dl class="mt-3 grid gap-2 text-sm">
+            <div
+              v-for="[type, n] in presentTypes"
+              :key="type"
+              class="flex justify-between gap-4"
+            >
+              <dt class="text-muted-foreground">{{ TYPE_LABELS[type] }}</dt>
+              <dd class="font-medium">{{ n }}</dd>
+            </div>
+            <p
+              v-if="!presentTypes.length"
+              class="text-sm text-muted-foreground"
+            >
+              No sources yet.
+            </p>
+            <div class="flex justify-between gap-4 border-t pt-2">
+              <dt class="text-muted-foreground">Last indexed</dt>
+              <dd class="font-medium">{{ formatDateTime(current.indexedAt) }}</dd>
+            </div>
+            <div class="flex justify-between gap-4">
+              <dt class="text-muted-foreground">Last run started</dt>
+              <dd class="font-medium">
+                {{ formatDateTime(current.indexStartedAt) }}
+              </dd>
+            </div>
+          </dl>
+        </div>
+      </section>
+
+      <section class="flex min-w-0 flex-col gap-6">
+        <div class="rounded-md border bg-card p-4">
+          <h2 class="text-sm font-semibold">Runtime</h2>
+          <p class="mt-1 text-xs text-muted-foreground">
+            What the indexing service is actually running. Read from the service
+            itself, so it reflects how it was started rather than what is picked
+            in Settings.
+          </p>
+          <dl v-if="runtime" class="mt-3 grid gap-2 text-sm">
+            <div class="flex justify-between gap-4">
+              <dt class="text-muted-foreground">LLM</dt>
+              <dd class="min-w-0 truncate font-medium" :title="runtime.llmModel ?? ''">
+                {{ runtime.llmBinding ?? '-' }} · {{ runtime.llmModel ?? '-' }}
+              </dd>
+            </div>
+            <div class="flex justify-between gap-4">
+              <dt class="text-muted-foreground">Embedding</dt>
+              <dd
+                class="min-w-0 truncate font-medium"
+                :title="runtime.embeddingModel ?? ''"
+              >
+                {{ runtime.embeddingBinding ?? '-' }} ·
+                {{ runtime.embeddingModel ?? '-' }}
+              </dd>
+            </div>
+            <div v-if="runtime.embeddingBindingHost" class="flex justify-between gap-4">
+              <dt class="text-muted-foreground">Embedding host</dt>
+              <dd
+                class="min-w-0 truncate font-medium"
+                :title="runtime.embeddingBindingHost"
+              >
+                {{ runtime.embeddingBindingHost }}
+              </dd>
+            </div>
+          </dl>
+          <p v-else class="mt-3 text-sm text-muted-foreground">
+            Not reported. The service is unreachable or not configured.
+          </p>
+        </div>
+
+        <div class="rounded-md border bg-card p-4">
+          <h2 class="text-sm font-semibold">Service</h2>
+          <p class="mt-1 text-xs text-muted-foreground">
+            Everything indexing needs. A missing bucket fails uploads silently,
+            so it is worth a look before blaming a document.
+          </p>
+          <ul class="mt-3 grid gap-2 text-sm">
+            <li
+              v-for="check in setupChecks"
+              :key="check.label"
+              class="flex items-center justify-between gap-4"
+            >
+              <span class="text-muted-foreground">{{ check.label }}</span>
+              <span
+                class="font-medium"
+                :class="check.ok ? 'text-emerald-600' : 'text-destructive'"
+              >
+                {{ check.ok ? 'OK' : 'Missing' }}
+              </span>
+            </li>
+          </ul>
+          <NuxtLink
+            to="/settings/knowledge"
+            class="mt-3 inline-block text-xs underline underline-offset-2"
+          >
+            Open knowledge settings
+          </NuxtLink>
+        </div>
+      </section>
+    </div>
+  </div>
+</template>
diff --git a/admin/slices/reins/components/knowledge/setup/Wizard.vue b/admin/slices/reins/components/knowledge/setup/Wizard.vue
index 55afdbd4..fab63498 100644
--- a/admin/slices/reins/components/knowledge/setup/Wizard.vue
+++ b/admin/slices/reins/components/knowledge/setup/Wizard.vue
@@ -28,7 +28,7 @@ const steps = computed<IStep[]>(() => [
     id: 'embedding-credential',
     title: 'Create an embedding LLM credential',
     description:
-      'Knowledge needs a model that turns source chunks into vectors (e.g. OpenAI text-embedding-3-small).',
+      'Knowledge needs a model that turns source chunks into vectors (e.g. OpenAI text-embedding-3-small). Anthropic has no embeddings API, so a Claude credential cannot fill this role.',
     done: props.setup.hasEmbeddingCredential,
     cta: { label: 'Create embedding credential', to: '/llms/create?capability=embedding' },
   },
@@ -44,7 +44,7 @@ const steps = computed<IStep[]>(() => [
     id: 'service-config',
     title: 'Configure the Knowledge service',
     description:
-      'Set the LightRAG URL, S3 bucket, pick chat and embedding credentials, then turn the service on.',
+      'Set the LightRAG URL, S3 bucket and chat credential, then turn the service on. The embedding model comes from the LightRAG container env, not from here.',
     done: configStepDone.value,
     cta: { label: 'Open settings', to: '/settings/knowledge' },
   },
diff --git a/admin/slices/reins/components/knowledge/sources/AddForm.vue b/admin/slices/reins/components/knowledge/sources/AddForm.vue
deleted file mode 100644
index 04024929..00000000
--- a/admin/slices/reins/components/knowledge/sources/AddForm.vue
+++ /dev/null
@@ -1,178 +0,0 @@
-<script setup lang="ts">
-import type { SourceType } from '#reins/stores/knowledge';
-
-// Mirrors MAX_FILES_PER_BATCH in the API's source.controller.
-const MAX_FILES_PER_BATCH = 250;
-
-const props = defineProps<{ knowledgeId: string }>();
-const emit = defineEmits<{ added: [] }>();
-
-const store = useKnowledgeStore();
-const open = ref(false);
-const submitting = ref(false);
-const errorMessage = ref<string | null>(null);
-
-const type = ref<SourceType>('text');
-const name = ref('');
-const content = ref('');
-const url = ref('');
-const files = ref<File[]>([]);
-const fileInput = ref<HTMLInputElement | null>(null);
-
-function reset() {
-  type.value = 'text';
-  name.value = '';
-  content.value = '';
-  url.value = '';
-  files.value = [];
-  if (fileInput.value) fileInput.value.value = '';
-  errorMessage.value = null;
-}
-
-async function submit() {
-  submitting.value = true;
-  errorMessage.value = null;
-  try {
-    if (type.value === 'text') {
-      if (!name.value.trim() || !content.value.trim()) {
-        throw new Error('Name and content are required');
-      }
-      await store.addTextSource(
-        props.knowledgeId,
-        name.value.trim(),
-        content.value,
-      );
-    } else if (type.value === 'url') {
-      if (!name.value.trim() || !url.value.trim()) {
-        throw new Error('Name and URL are required');
-      }
-      await store.addUrlSource(
-        props.knowledgeId,
-        name.value.trim(),
-        url.value.trim(),
-      );
-    } else if (type.value === 'file') {
-      if (!files.value.length) throw new Error('Pick at least one file');
-      // Checked here as well as server-side: past the cap the upload is
-      // rejected only after the whole body has been sent, so catching it
-      // before the request saves uploading a batch that cannot be accepted.
-      if (files.value.length > MAX_FILES_PER_BATCH) {
-        throw new Error(
-          `Too many files: ${files.value.length}. Add at most ${MAX_FILES_PER_BATCH} at a time, or use "Upload archive" below for a larger set.`,
-        );
-      }
-      const result = await store.addFileSources(props.knowledgeId, files.value);
-      // A batch can partly succeed. Refresh the list either way, but keep the
-      // form open with the reason when something was rejected, so the user
-      // isn't left guessing why fewer sources appeared than files picked.
-      emit('added');
-      if (result.failed > 0 || result.added === 0) {
-        errorMessage.value = summarize(result);
-        return;
-      }
-      reset();
-      open.value = false;
-      return;
-    }
-    emit('added');
-    reset();
-    open.value = false;
-  } catch (err: unknown) {
-    const e = err as { response?: { data?: { message?: string } }; message?: string };
-    errorMessage.value = e?.response?.data?.message ?? e?.message ?? 'Add failed';
-  } finally {
-    submitting.value = false;
-  }
-}
-
-function summarize(result: {
-  added: number;
-  skipped: number;
-  failed: number;
-  errors: string[];
-}): string {
-  const parts = [`${result.added} added`];
-  if (result.skipped) parts.push(`${result.skipped} already existed`);
-  if (result.failed) parts.push(`${result.failed} failed`);
-  const head = parts.join(', ');
-  return result.errors.length ? `${head}. ${result.errors.join('; ')}` : head;
-}
-
-function onFileChange(e: Event) {
-  const target = e.target as HTMLInputElement;
-  files.value = target.files ? Array.from(target.files) : [];
-}
-
-function cancel() {
-  reset();
-  open.value = false;
-}
-</script>
-
-<template>
-  <div class="rounded-md border bg-card p-4">
-    <div v-if="!open" class="flex items-center justify-between">
-      <p class="text-sm text-muted-foreground">Add a source (text, URL, or files).</p>
-      <Button size="sm" @click="open = true">Add source</Button>
-    </div>
-
-    <form v-else class="flex flex-col gap-4" @submit.prevent="submit">
-      <div class="grid gap-2">
-        <Label for="source-type">Type</Label>
-        <select
-          id="source-type"
-          v-model="type"
-          class="h-9 w-full rounded-md border bg-background px-3 text-sm"
-        >
-          <option value="text">Text</option>
-          <option value="url">URL</option>
-          <option value="file">Files</option>
-        </select>
-      </div>
-
-      <div v-if="type !== 'file'" class="grid gap-2">
-        <Label for="source-name">Name</Label>
-        <Input id="source-name" v-model="name" />
-      </div>
-
-      <div v-if="type === 'text'" class="grid gap-2">
-        <Label for="source-content">Content</Label>
-        <Textarea id="source-content" v-model="content" rows="8" />
-      </div>
-
-      <div v-if="type === 'url'" class="grid gap-2">
-        <Label for="source-url">URL</Label>
-        <Input id="source-url" v-model="url" placeholder="https://example.com/doc" />
-      </div>
-
-      <div v-if="type === 'file'" class="grid gap-2">
-        <Label for="source-file">Files</Label>
-        <input
-          id="source-file"
-          ref="fileInput"
-          type="file"
-          multiple
-          class="text-sm"
-          @change="onFileChange"
-        />
-        <p class="text-xs text-muted-foreground">
-          Pick one or several files (up to {{ MAX_FILES_PER_BATCH }}). Each
-          becomes its own source; names already present on this knowledge are
-          skipped. For a larger set use "Upload archive" below.
-        </p>
-        <p v-if="files.length" class="text-xs text-muted-foreground">
-          Selected: {{ files.map((f) => f.name).join(', ') }}
-        </p>
-      </div>
-
-      <p v-if="errorMessage" class="text-xs text-destructive">{{ errorMessage }}</p>
-
-      <div class="flex items-center gap-2">
-        <Button type="submit" :disabled="submitting">
-          {{ submitting ? 'Saving…' : 'Add' }}
-        </Button>
-        <Button type="button" variant="ghost" @click="cancel">Cancel</Button>
-      </div>
-    </form>
-  </div>
-</template>
diff --git a/admin/slices/reins/components/knowledge/sources/AddFromArchiveForm.vue b/admin/slices/reins/components/knowledge/sources/AddFromArchiveForm.vue
deleted file mode 100644
index 960ac16b..00000000
--- a/admin/slices/reins/components/knowledge/sources/AddFromArchiveForm.vue
+++ /dev/null
@@ -1,97 +0,0 @@
-<script setup lang="ts">
-
-const props = defineProps<{ knowledgeId: string }>();
-const emit = defineEmits<{ added: [] }>();
-
-const store = useKnowledgeStore();
-const open = ref(false);
-const submitting = ref(false);
-const errorMessage = ref<string | null>(null);
-const successMessage = ref<string | null>(null);
-const file = ref<File | null>(null);
-
-function onFileChange(e: Event) {
-  const target = e.target as HTMLInputElement;
-  file.value = target.files?.[0] ?? null;
-}
-
-async function submit() {
-  if (!file.value) {
-    errorMessage.value = 'Pick a .zip archive first';
-    return;
-  }
-  submitting.value = true;
-  errorMessage.value = null;
-  successMessage.value = null;
-  try {
-    const result = await store.addSourcesFromArchive(
-      props.knowledgeId,
-      file.value,
-    );
-    successMessage.value = `Detected ${result.detected} file${result.detected === 1 ? '' : 's'}. Importing in the background - refresh the list to watch sources appear, then run Index.`;
-    emit('added');
-    file.value = null;
-  } catch (err: unknown) {
-    const e = err as {
-      response?: { data?: { message?: string } };
-      message?: string;
-    };
-    errorMessage.value =
-      e?.response?.data?.message ?? e?.message ?? 'Archive import failed';
-  } finally {
-    submitting.value = false;
-  }
-}
-
-function cancel() {
-  file.value = null;
-  errorMessage.value = null;
-  successMessage.value = null;
-  open.value = false;
-}
-</script>
-
-<template>
-  <div class="rounded-md border bg-card p-4">
-    <div v-if="!open" class="flex items-center justify-between">
-      <p class="text-sm text-muted-foreground">
-        Bulk-import a .zip of documents (pdf, docx, xlsx, txt, html, ...) as
-        file sources.
-      </p>
-      <Button size="sm" variant="outline" @click="open = true">
-        Upload archive
-      </Button>
-    </div>
-
-    <form v-else class="flex flex-col gap-4" @submit.prevent="submit">
-      <div class="grid gap-2">
-        <Label for="archive-file">Zip archive</Label>
-        <input
-          id="archive-file"
-          type="file"
-          accept=".zip,application/zip"
-          class="text-sm"
-          @change="onFileChange"
-        />
-        <p class="text-xs text-muted-foreground">
-          Every supported file inside becomes a source. Unsupported files
-          (images, video) and macOS metadata are skipped automatically.
-        </p>
-      </div>
-
-      <p v-if="errorMessage" class="text-xs text-destructive">
-        {{ errorMessage }}
-      </p>
-      <p v-if="successMessage" class="text-xs text-emerald-600">
-        {{ successMessage }}
-      </p>
-
-      <div class="flex items-center gap-2">
-        <Button type="submit" :disabled="submitting">
-          {{ submitting ? 'Uploading…' : 'Upload' }}
-        </Button>
-        <Button type="button" variant="ghost" @click="cancel">Close</Button>
-      </div>
-    </form>
-  </div>
-</template>
diff --git a/admin/slices/reins/components/knowledge/sources/AddFromSitemapForm.vue b/admin/slices/reins/components/knowledge/sources/AddFromSitemapForm.vue
deleted file mode 100644
index 0ff1780c..00000000
--- a/admin/slices/reins/components/knowledge/sources/AddFromSitemapForm.vue
+++ /dev/null
@@ -1,108 +0,0 @@
-<script setup lang="ts">
-
-const props = defineProps<{ knowledgeId: string }>();
-const emit = defineEmits<{ added: [] }>();
-
-const store = useKnowledgeStore();
-const open = ref(false);
-const submitting = ref(false);
-const errorMessage = ref<string | null>(null);
-const successMessage = ref<string | null>(null);
-
-const sitemapUrl = ref('');
-const urlPrefix = ref('');
-
-function reset() {
-  sitemapUrl.value = '';
-  urlPrefix.value = '';
-  errorMessage.value = null;
-  successMessage.value = null;
-}
-
-async function submit() {
-  if (!sitemapUrl.value.trim()) {
-    errorMessage.value = 'Sitemap URL is required';
-    return;
-  }
-  submitting.value = true;
-  errorMessage.value = null;
-  successMessage.value = null;
-  try {
-    const result = await store.addSourcesFromSitemap(
-      props.knowledgeId,
-      sitemapUrl.value.trim(),
-      urlPrefix.value.trim() || undefined,
-    );
-    successMessage.value = `Added ${result.added} of ${result.discovered} discovered URL${result.discovered === 1 ? '' : 's'}. Run Index to ingest into the knowledge base.`;
-    emit('added');
-    sitemapUrl.value = '';
-    urlPrefix.value = '';
-  } catch (err: unknown) {
-    const e = err as {
-      response?: { data?: { message?: string } };
-      message?: string;
-    };
-    errorMessage.value =
-      e?.response?.data?.message ?? e?.message ?? 'Sitemap import failed';
-  } finally {
-    submitting.value = false;
-  }
-}
-
-function cancel() {
-  reset();
-  open.value = false;
-}
-</script>
-
-<template>
-  <div class="rounded-md border bg-card p-4">
-    <div v-if="!open" class="flex items-center justify-between">
-      <p class="text-sm text-muted-foreground">
-        Bulk-import every page from a sitemap.xml (or sitemap-index) as
-        url-type sources.
-      </p>
-      <Button size="sm" variant="outline" @click="open = true">
-        Add from sitemap
-      </Button>
-    </div>
-
-    <form v-else class="flex flex-col gap-4" @submit.prevent="submit">
-      <div class="grid gap-2">
-        <Label for="sitemap-url">Sitemap URL</Label>
-        <Input
-          id="sitemap-url"
-          v-model="sitemapUrl"
-          placeholder="https://developer.paypal.com/sitemap.xml"
-        />
-      </div>
-
-      <div class="grid gap-2">
-        <Label for="sitemap-prefix">URL prefix filter (optional)</Label>
-        <Input
-          id="sitemap-prefix"
-          v-model="urlPrefix"
-          placeholder="https://developer.paypal.com/docs/checkout/"
-        />
-        <p class="text-xs text-muted-foreground">
-          Only URLs starting with this prefix will be added. Leave empty to
-          import every page in the sitemap.
-        </p>
-      </div>
-
-      <p v-if="errorMessage" class="text-xs text-destructive">
-        {{ errorMessage }}
-      </p>
-      <p v-if="successMessage" class="text-xs text-emerald-600">
-        {{ successMessage }}
-      </p>
-
-      <div class="flex items-center gap-2">
-        <Button type="submit" :disabled="submitting">
-          {{ submitting ? 'Importing…' : 'Import' }}
-        </Button>
-        <Button type="button" variant="ghost" @click="cancel">Close</Button>
-      </div>
-    </form>
-  </div>
-</template>
diff --git a/admin/slices/reins/components/knowledge/sources/AddSheet.vue b/admin/slices/reins/components/knowledge/sources/AddSheet.vue
new file mode 100644
index 00000000..99f7af3b
--- /dev/null
+++ b/admin/slices/reins/components/knowledge/sources/AddSheet.vue
@@ -0,0 +1,358 @@
+<script setup lang="ts">
+import { errorMessageOf } from '#reins/domain';
+
+// Mirrors MAX_FILES_PER_BATCH in the API's source.controller.
+const MAX_FILES_PER_BATCH = 250;
+
+/**
+ * Every way a source can enter a knowledge base, in one place. These used to be
+ * three permanently expanded cards stacked above the table, which cost most of
+ * the first screen to advertise actions taken once and then never again. A
+ * sheet keeps the table at the top of the page and gives each mode room for its
+ * own explanation.
+ */
+type AddMode = 'files' | 'archive' | 'text' | 'url' | 'sitemap';
+
+const MODES: readonly { value: AddMode; label: string }[] = [
+  { value: 'files', label: 'Files' },
+  { value: 'archive', label: 'Archive' },
+  { value: 'text', label: 'Text' },
+  { value: 'url', label: 'URL' },
+  { value: 'sitemap', label: 'Sitemap' },
+];
+
+const SUBMIT_LABELS: Record<AddMode, string> = {
+  files: 'Upload',
+  archive: 'Upload',
+  text: 'Add',
+  url: 'Add',
+  sitemap: 'Import',
+};
+
+function isAddMode(value: unknown): value is AddMode {
+  return MODES.some((m) => m.value === value);
+}
+
+const props = defineProps<{ knowledgeId: string }>();
+const emit = defineEmits<{ added: [] }>();
+
+const store = useKnowledgeStore();
+
+const open = ref(false);
+const mode = ref<AddMode>('files');
+const submitting = ref(false);
+const errorMessage = ref<string | null>(null);
+const successMessage = ref<string | null>(null);
+
+const name = ref('');
+const content = ref('');
+const url = ref('');
+const files = ref<File[]>([]);
+const archive = ref<File | null>(null);
+const sitemapUrl = ref('');
+const urlPrefix = ref('');
+
+const fileInput = ref<HTMLInputElement | null>(null);
+const archiveInput = ref<HTMLInputElement | null>(null);
+
+function clearMessages(): void {
+  errorMessage.value = null;
+  successMessage.value = null;
+}
+
+function resetAll(): void {
+  name.value = '';
+  content.value = '';
+  url.value = '';
+  files.value = [];
+  archive.value = null;
+  sitemapUrl.value = '';
+  urlPrefix.value = '';
+  if (fileInput.value) fileInput.value.value = '';
+  if (archiveInput.value) archiveInput.value.value = '';
+  clearMessages();
+}
+
+// A message about a zip is meaningless once the user is looking at the text
+// form, so switching modes wipes the notices but keeps whatever was typed.
+function selectMode(value: unknown): void {
+  if (!isAddMode(value)) return;
+  mode.value = value;
+  clearMessages();
+}
+
+function onFilesChange(e: Event): void {
+  const target = e.target as HTMLInputElement;
+  files.value = target.files ? Array.from(target.files) : [];
+}
+
+function onArchiveChange(e: Event): void {
+  const target = e.target as HTMLInputElement;
+  archive.value = target.files?.[0] ?? null;
+}
+
+function summarize(result: {
+  added: number;
+  skipped: number;
+  failed: number;
+  errors: string[];
+}): string {
+  const parts = [`${result.added} added`];
+  if (result.skipped) parts.push(`${result.skipped} already existed`);
+  if (result.failed) parts.push(`${result.failed} failed`);
+  const head = parts.join(', ');
+  return result.errors.length ? `${head}. ${result.errors.join('; ')}` : head;
+}
+
+interface AddOutcome {
+  /** Close the sheet: nothing left on screen the user still has to read. */
+  close: boolean;
+  notice: string | null;
+  /**
+   * The request went through but not everything landed. Distinct from a thrown
+   * error, which means nothing was sent at all - a half-successful batch still
+   * changed the list, so the table has to be refreshed either way.
+   */
+  problem: string | null;
+}
+
+/**
+ * Text, URL and a clean file batch are finished the moment they return. A
+ * sitemap or an archive reports a count the user needs to read, and an archive
+ * keeps running in the background after the request returns, so those stay open
+ * with the result on screen.
+ *
+ * Validation failures throw, because nothing reached the server.
+ */
+async function runMode(): Promise<AddOutcome> {
+  const id = props.knowledgeId;
+  const done: AddOutcome = { close: true, notice: null, problem: null };
+
+  if (mode.value === 'text') {
+    if (!name.value.trim() || !content.value.trim()) {
+      throw new Error('Name and content are required');
+    }
+    await store.addTextSource(id, name.value.trim(), content.value);
+    return done;
+  }
+
+  if (mode.value === 'url') {
+    if (!name.value.trim() || !url.value.trim()) {
+      throw new Error('Name and URL are required');
+    }
+    await store.addUrlSource(id, name.value.trim(), url.value.trim());
+    return done;
+  }
+
+  if (mode.value === 'files') {
+    if (!files.value.length) throw new Error('Pick at least one file');
+    // Checked here as well as server-side: past the cap the upload is rejected
+    // only after the whole body has been sent, so catching it before the
+    // request saves uploading a batch that cannot be accepted.
+    if (files.value.length > MAX_FILES_PER_BATCH) {
+      throw new Error(
+        `Too many files: ${files.value.length}. Add at most ${MAX_FILES_PER_BATCH} at a time, or use the Archive tab for a larger set.`,
+      );
+    }
+    const result = await store.addFileSources(id, files.value);
+    if (result.failed > 0 || result.added === 0) {
+      return { close: false, notice: null, problem: summarize(result) };
+    }
+    return done;
+  }
+
+  if (mode.value === 'archive') {
+    if (!archive.value) throw new Error('Pick a .zip archive first');
+    const result = await store.addSourcesFromArchive(id, archive.value);
+    archive.value = null;
+    if (archiveInput.value) archiveInput.value.value = '';
+    return {
+      close: false,
+      problem: null,
+      notice: `Detected ${result.detected} file${result.detected === 1 ? '' : 's'}. Importing in the background - progress shows under the table; run Index once it finishes.`,
+    };
+  }
+
+  if (!sitemapUrl.value.trim()) throw new Error('Sitemap URL is required');
+  const result = await store.addSourcesFromSitemap(
+    id,
+    sitemapUrl.value.trim(),
+    urlPrefix.value.trim() || undefined,
+  );
+  sitemapUrl.value = '';
+  urlPrefix.value = '';
+  return {
+    close: false,
+    problem: null,
+    notice: `Added ${result.added} of ${result.discovered} discovered URL${result.discovered === 1 ? '' : 's'}. Run Index to ingest them.`,
+  };
+}
+
+async function submit(): Promise<void> {
+  submitting.value = true;
+  clearMessages();
+  try {
+    const outcome = await runMode();
+    // Reached the server, so the list has moved - refresh it before deciding
+    // what to show, including for a batch that only partly landed.
+    emit('added');
+    if (outcome.problem) {
+      errorMessage.value = outcome.problem;
+      return;
+    }
+    if (outcome.close) {
+      open.value = false;
+      return;
+    }
+    successMessage.value = outcome.notice;
+  } catch (err: unknown) {
+    errorMessage.value = errorMessageOf(err, 'Could not add sources');
+  } finally {
+    submitting.value = false;
+  }
+}
+
+watch(open, (isOpen) => {
+  if (!isOpen) resetAll();
+});
+</script>
+
+<template>
+  <Sheet v-model:open="open">
+    <SheetTrigger as-child>
+      <Button size="sm">Add sources</Button>
+    </SheetTrigger>
+
+    <SheetContent side="right" class="flex w-full flex-col sm:max-w-xl">
+      <SheetHeader>
+        <SheetTitle>Add sources</SheetTitle>
+        <SheetDescription>
+          Anything added here is stored but not searchable until the next Index
+          run.
+        </SheetDescription>
+      </SheetHeader>
+
+      <form class="flex min-h-0 flex-1 flex-col gap-4" @submit.prevent="submit">
+        <Tabs
+          :model-value="mode"
+          class="flex min-h-0 flex-1 flex-col gap-4"
+          @update:model-value="selectMode"
+        >
+          <TabsList class="mx-4 grid grid-cols-5">
+            <TabsTrigger v-for="m in MODES" :key="m.value" :value="m.value">
+              {{ m.label }}
+            </TabsTrigger>
+          </TabsList>
+
+          <div class="min-h-0 flex-1 overflow-y-auto px-4">
+            <TabsContent value="files" class="grid gap-2">
+              <Label for="add-files">Files</Label>
+              <input
+                id="add-files"
+                ref="fileInput"
+                type="file"
+                multiple
+                class="text-sm"
+                @change="onFilesChange"
+              >
+              <p class="text-xs text-muted-foreground">
+                Up to {{ MAX_FILES_PER_BATCH }} at a time. Each file becomes its
+                own source; names already on this knowledge are skipped.
+              </p>
+              <p v-if="files.length" class="text-xs text-muted-foreground">
+                Selected {{ files.length }}: {{ files.map((f) => f.name).join(', ') }}
+              </p>
+            </TabsContent>
+
+            <TabsContent value="archive" class="grid gap-2">
+              <Label for="add-archive">Zip archive</Label>
+              <input
+                id="add-archive"
+                ref="archiveInput"
+                type="file"
+                accept=".zip,application/zip"
+                class="text-sm"
+                @change="onArchiveChange"
+              >
+              <p class="text-xs text-muted-foreground">
+                Every supported file inside (pdf, docx, xlsx, txt, html, …)
+                becomes a source. Images, video and macOS metadata are skipped.
+                Large archives are fine: the zip streams to disk and files
+                upload one by one.
+              </p>
+            </TabsContent>
+
+            <TabsContent value="text" class="grid gap-4">
+              <div class="grid gap-2">
+                <Label for="add-text-name">Name</Label>
+                <Input id="add-text-name" v-model="name" />
+              </div>
+              <div class="grid gap-2">
+                <Label for="add-text-content">Content</Label>
+                <Textarea id="add-text-content" v-model="content" rows="12" />
+              </div>
+            </TabsContent>
+
+            <TabsContent value="url" class="grid gap-4">
+              <div class="grid gap-2">
+                <Label for="add-url-name">Name</Label>
+                <Input id="add-url-name" v-model="name" />
+              </div>
+              <div class="grid gap-2">
+                <Label for="add-url-value">URL</Label>
+                <Input
+                  id="add-url-value"
+                  v-model="url"
+                  placeholder="https://example.com/doc"
+                />
+              </div>
+            </TabsContent>
+
+            <TabsContent value="sitemap" class="grid gap-4">
+              <div class="grid gap-2">
+                <Label for="add-sitemap-url">Sitemap URL</Label>
+                <Input
+                  id="add-sitemap-url"
+                  v-model="sitemapUrl"
+                  placeholder="https://example.com/sitemap.xml"
+                />
+                <p class="text-xs text-muted-foreground">
+                  A sitemap.xml or a sitemap index. Every page it lists is added
+                  as a url-type source.
+                </p>
+              </div>
+              <div class="grid gap-2">
+                <Label for="add-sitemap-prefix">URL prefix filter (optional)</Label>
+                <Input
+                  id="add-sitemap-prefix"
+                  v-model="urlPrefix"
+                  placeholder="https://example.com/docs/"
+                />
+                <p class="text-xs text-muted-foreground">
+                  Only URLs starting with this prefix are added. Leave empty to
+                  import the whole sitemap.
+                </p>
+              </div>
+            </TabsContent>
+
+            <p v-if="errorMessage" class="mt-4 text-sm text-destructive">
+              {{ errorMessage }}
+            </p>
+            <p v-if="successMessage" class="mt-4 text-sm text-emerald-600">
+              {{ successMessage }}
+            </p>
+          </div>
+        </Tabs>
+
+        <SheetFooter class="gap-2">
+          <Button type="submit" :disabled="submitting">
+            {{ submitting ? 'Working…' : SUBMIT_LABELS[mode] }}
+          </Button>
+          <Button type="button" variant="ghost" @click="open = false">
+            Close
+          </Button>
+        </SheetFooter>
+      </form>
+    </SheetContent>
+  </Sheet>
+</template>
diff --git a/admin/slices/reins/components/knowledge/sources/ImportProgress.vue b/admin/slices/reins/components/knowledge/sources/ImportProgress.vue
new file mode 100644
index 00000000..3081af5d
--- /dev/null
+++ b/admin/slices/reins/components/knowledge/sources/ImportProgress.vue
@@ -0,0 +1,98 @@
+<script setup lang="ts">
+import { Button } from '#theme/components/ui/button';
+import type { IImportJob } from '#reins/stores/knowledge';
+
+const props = defineProps<{ jobs: IImportJob[] }>();
+
+// Finished jobs the user has closed. Ids only; the list itself keeps coming
+// from the API so a job that is still running can never be dismissed.
+const dismissed = ref<Set<string>>(new Set());
+
+const visible = computed(() =>
+  props.jobs.filter((j) => j.status === 'running' || !dismissed.value.has(j.id)),
+);
+
+const expanded = ref<Set<string>>(new Set());
+
+function processed(job: IImportJob): number {
+  return job.added + job.skipped + job.failed;
+}
+
+function percent(job: IImportJob): number {
+  if (job.detected === 0) return 100;
+  return Math.min(100, Math.round((processed(job) / job.detected) * 100));
+}
+
+function dismiss(id: string) {
+  dismissed.value = new Set([...dismissed.value, id]);
+}
+
+function toggle(id: string) {
+  const next = new Set(expanded.value);
+  if (next.has(id)) next.delete(id);
+  else next.add(id);
+  expanded.value = next;
+}
+</script>
+
+<template>
+  <div v-if="visible.length" class="flex flex-col gap-2">
+    <div
+      v-for="job in visible"
+      :key="job.id"
+      class="rounded-md border bg-card p-3 text-sm"
+      :class="job.status === 'failed' ? 'border-destructive/50' : ''"
+    >
+      <div class="flex items-center justify-between gap-3">
+        <div class="min-w-0">
+          <span v-if="job.status === 'running'">Importing archive:</span>
+          <span v-else-if="job.status === 'done'">Archive imported:</span>
+          <span v-else class="text-destructive">Archive import failed:</span>
+          <span class="ml-1 font-medium">{{ job.added }} / {{ job.detected }} added</span>
+          <span class="text-muted-foreground"> · {{ job.skipped }} skipped</span>
+          <span :class="job.failed ? 'text-destructive' : 'text-muted-foreground'">
+            · {{ job.failed }} failed
+          </span>
+        </div>
+        <div class="flex shrink-0 items-center gap-1">
+          <Button
+            v-if="job.errors.length"
+            size="sm"
+            variant="ghost"
+            @click="toggle(job.id)"
+          >
+            {{ expanded.has(job.id) ? 'Hide errors' : `Show errors (${job.errors.length})` }}
+          </Button>
+          <Button
+            v-if="job.status !== 'running'"
+            size="sm"
+            variant="ghost"
+            @click="dismiss(job.id)"
+          >
+            Dismiss
+          </Button>
+        </div>
+      </div>
+
+      <div class="mt-2 h-1.5 w-full overflow-hidden rounded bg-muted">
+        <div
+          class="h-full transition-all"
+          :class="job.status === 'failed' ? 'bg-destructive' : 'bg-primary'"
+          :style="{ width: `${percent(job)}%` }"
+        />
+      </div>
+
+      <ul
+        v-if="expanded.has(job.id)"
+        class="mt-2 max-h-40 list-disc space-y-0.5 overflow-auto pl-5 text-xs text-muted-foreground"
+      >
+        <li v-for="(line, i) in job.errors" :key="i" class="break-words">
+          {{ line }}
+        </li>
+        <li v-if="job.failed > job.errors.length" class="italic">
+          … and {{ job.failed - job.errors.length }} more
+        </li>
+      </ul>
+    </div>
+  </div>
+</template>
diff --git a/admin/slices/reins/components/knowledge/sources/PreviewSheet.vue b/admin/slices/reins/components/knowledge/sources/PreviewSheet.vue
new file mode 100644
index 00000000..ac2fc071
--- /dev/null
+++ b/admin/slices/reins/components/knowledge/sources/PreviewSheet.vue
@@ -0,0 +1,166 @@
+<script setup lang="ts">
+import { Button } from '#theme/components/ui/button';
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+} from '#theme/components/ui/sheet';
+import type { ISource, ISourcePreview } from '#reins/stores/knowledge';
+import { formatBytes } from '#reins/domain';
+
+const props = defineProps<{
+  knowledgeId: string;
+  source: ISource | null;
+}>();
+const emit = defineEmits<{ close: [] }>();
+
+const store = useKnowledgeStore();
+
+const preview = ref<ISourcePreview | null>(null);
+const text = ref<string | null>(null);
+const loading = ref(false);
+const errorMessage = ref<string | null>(null);
+// URLs handed to "Open in new tab". Revoking one while that tab still loads
+// would blank it, so they outlive the sheet and go on unmount only.
+const externalUrls: string[] = [];
+
+type PreviewKind = 'frame' | 'text' | 'none';
+
+// What the browser can render inside an iframe or we can dump as text. Office
+// formats fall through to "none": no plugin renders them client-side, so the
+// sheet offers the download instead.
+function kindFor(contentType: string): PreviewKind {
+  const type = contentType.split(';')[0].trim().toLowerCase();
+  if (type === 'application/pdf' || type === 'text/html' || type.startsWith('image/')) {
+    return 'frame';
+  }
+  if (
+    type.startsWith('text/') ||
+    type === 'application/json' ||
+    type === 'application/xml' ||
+    type === 'application/csv'
+  ) {
+    return 'text';
+  }
+  return 'none';
+}
+
+const kind = computed<PreviewKind>(() =>
+  preview.value ? kindFor(preview.value.contentType) : 'none',
+);
+
+const open = computed(() => props.source !== null);
+
+function reset() {
+  preview.value?.revoke();
+  preview.value = null;
+  text.value = null;
+  errorMessage.value = null;
+}
+
+async function load(source: ISource) {
+  reset();
+  loading.value = true;
+  try {
+    const p = await store.previewSource(props.knowledgeId, source.id);
+    // The user may have clicked another row (or closed the sheet) while this
+    // one was in flight; a stale response must neither show nor leak its URL.
+    if (props.source?.id !== source.id) {
+      p.revoke();
+      return;
+    }
+    preview.value = p;
+    if (kindFor(p.contentType) === 'text') {
+      text.value = await p.blob.text();
+    }
+  } catch (err: unknown) {
+    if (props.source?.id !== source.id) return;
+    const e = err as {
+      response?: { data?: { message?: string } };
+      message?: string;
+    };
+    errorMessage.value =
+      e?.response?.data?.message ?? e?.message ?? 'Could not load this source';
+  } finally {
+    if (props.source?.id === source.id) loading.value = false;
+  }
+}
+
+watch(
+  () => props.source,
+  (source) => {
+    if (source) void load(source);
+    else reset();
+  },
+  { immediate: true },
+);
+
+onBeforeUnmount(() => {
+  reset();
+  for (const url of externalUrls) URL.revokeObjectURL(url);
+  externalUrls.length = 0;
+});
+
+function openInNewTab() {
+  if (!preview.value) return;
+  // Fresh URL for the other tab so closing this sheet cannot pull it away.
+  const url = URL.createObjectURL(preview.value.blob);
+  externalUrls.push(url);
+  window.open(url, '_blank', 'noopener');
+}
+
+async function download() {
+  if (!props.source) return;
+  await store.downloadSource(props.knowledgeId, props.source.id);
+}
+</script>
+
+<template>
+  <Sheet :open="open" @update:open="(v: boolean) => !v && emit('close')">
+    <SheetContent side="right" class="flex w-full flex-col sm:max-w-3xl">
+      <SheetHeader>
+        <SheetTitle class="truncate pr-6" :title="source?.name">
+          {{ source?.name ?? '' }}
+        </SheetTitle>
+        <SheetDescription v-if="preview">
+          {{ preview.contentType.split(';')[0] }} · {{ formatBytes(preview.size) }}
+        </SheetDescription>
+      </SheetHeader>
+
+      <div class="min-h-0 flex-1 overflow-hidden px-4">
+        <div v-if="loading" class="py-6 text-sm text-muted-foreground">
+          Loading…
+        </div>
+        <p v-else-if="errorMessage" class="py-6 text-sm text-destructive">
+          {{ errorMessage }}
+        </p>
+        <iframe
+          v-else-if="preview && kind === 'frame'"
+          :src="preview.url"
+          :title="source?.name"
+          class="h-full w-full rounded-md border bg-white"
+        />
+        <pre
+          v-else-if="preview && kind === 'text'"
+          class="h-full overflow-auto rounded-md border bg-muted/40 p-3 text-xs whitespace-pre-wrap break-words"
+        >{{ text ?? '' }}</pre>
+        <div
+          v-else-if="preview"
+          class="rounded-md border border-dashed p-6 text-center text-sm text-muted-foreground"
+        >
+          No inline preview for this file type. Download it to open locally.
+        </div>
+      </div>
+
+      <SheetFooter class="gap-2">
+        <Button variant="outline" :disabled="!preview" @click="openInNewTab">
+          Open in new tab
+        </Button>
+        <Button :disabled="!source" @click="download">Download</Button>
+      </SheetFooter>
+    </SheetContent>
+  </Sheet>
+</template>
diff --git a/admin/slices/reins/components/knowledge/sources/Provider.vue b/admin/slices/reins/components/knowledge/sources/Provider.vue
index 425ee72a..a49b613b 100644
--- a/admin/slices/reins/components/knowledge/sources/Provider.vue
+++ b/admin/slices/reins/components/knowledge/sources/Provider.vue
@@ -1,6 +1,34 @@
 <script setup lang="ts">
-import { useIntervalFn } from '@vueuse/core';
-import type { IKnowledge, ISource } from '#reins/stores/knowledge';
+import { refDebounced, useIntervalFn } from '@vueuse/core';
+import type {
+  IImportJob,
+  IKnowledge,
+  ISource,
+  ISourceFilter,
+  ISourcePage,
+  SourceIndexStatus,
+  SourceType,
+} from '#reins/stores/knowledge';
+import { Download, Eye, Trash2 } from 'lucide-vue-next';
+import { errorMessageOf, formatBytes, formatDate } from '#reins/domain';
+import { Button } from '#theme/components/ui/button';
+import { Checkbox } from '#theme/components/ui/checkbox';
+import { Input } from '#theme/components/ui/input';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '#theme/components/ui/select';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '#theme/components/ui/table';
 
 const route = useRoute();
 const store = useKnowledgeStore();
@@ -8,55 +36,214 @@ const confirmStore = useConfirmStore();
 const current = inject<Ref<IKnowledge | null>>('knowledge-current');
 const refresh = inject<() => Promise<void>>('knowledge-refresh');
 
-const sources = ref<ISource[]>([]);
+const knowledgeId = computed(() => route.params.id as string);
+
+// ---- filters ---------------------------------------------------------------
+
+const PER_PAGE = 50;
+const STATUS_OPTIONS: { value: SourceIndexStatus | 'all'; label: string }[] = [
+  { value: 'all', label: 'All statuses' },
+  { value: 'indexed', label: 'Indexed' },
+  { value: 'pending', label: 'Pending' },
+  { value: 'failed', label: 'Failed' },
+];
+const TYPE_OPTIONS: { value: SourceType | 'all'; label: string }[] = [
+  { value: 'all', label: 'All types' },
+  { value: 'file', label: 'File' },
+  { value: 'url', label: 'URL' },
+  { value: 'text', label: 'Text' },
+];
+
+const search = ref('');
+const searchDebounced = refDebounced(search, 300);
+const status = ref<SourceIndexStatus | 'all'>('all');
+const type = ref<SourceType | 'all'>('all');
+const page = ref(1);
+
+const filter = computed<ISourceFilter>(() => ({
+  page: page.value,
+  perPage: PER_PAGE,
+  search: searchDebounced.value.trim() || undefined,
+  status: status.value === 'all' ? undefined : status.value,
+  type: type.value === 'all' ? undefined : type.value,
+}));
+
+// Any filter change starts from page 1 again.
+watch([searchDebounced, status, type], () => {
+  page.value = 1;
+});
+
+// ---- list ------------------------------------------------------------------
+
+// Plain state rather than useAsyncData: this list is mutated from the page
+// itself (add / delete / import / index) and has to reflect a write that just
+// happened. useAsyncData caches per key in a payload shared across the app and
+// neutralizes an entry once its last consumer unmounts, so a refresh() right
+// after a mutation could resolve against a stale or detached entry and leave
+// the table showing the pre-write list until a full page reload.
+const pageData = ref<ISourcePage | null>(null);
 const loading = ref(false);
+const listError = ref<string | null>(null);
 
-async function reload() {
+// Only the newest request may write to the state: filter changes and the 3s
+// poll can overlap, and a slow earlier response must not overwrite a newer one.
+let loadToken = 0;
+
+async function load(): Promise<void> {
+  const token = (loadToken += 1);
   loading.value = true;
   try {
-    sources.value = await store.listSources(route.params.id as string);
+    const result = await store.listSources(knowledgeId.value, filter.value);
+    if (token !== loadToken) return;
+    pageData.value = result;
+    listError.value = null;
+  } catch (err: unknown) {
+    if (token !== loadToken) return;
+    listError.value = errorMessageOf(err, 'Could not load sources');
+  } finally {
+    if (token === loadToken) loading.value = false;
+  }
+}
+
+await load();
+
+watch(filter, () => {
+  void load();
+});
+
+const rows = computed<ISource[]>(() => pageData.value?.items ?? []);
+const total = computed(() => pageData.value?.total ?? 0);
+const pageCount = computed(() => Math.max(1, Math.ceil(total.value / PER_PAGE)));
+
+// A run that finishes mid-way can shrink a filtered result set under the
+// current page; snap back instead of showing an empty page.
+watch(pageCount, (count) => {
+  if (page.value > count) page.value = count;
+});
+
+const hasFilter = computed(
+  () => search.value.trim() !== '' || status.value !== 'all' || type.value !== 'all',
+);
+
+// ---- selection -------------------------------------------------------------
+
+// Two modes and only two. `allMatching` means "every row this filter returns",
+// which is the case the Export button exists for - a page-scoped select-all
+// would quietly mean 50 of 356. Otherwise it is the ticked ids.
+//
+// While `allMatching` is on the row boxes are checked and disabled. "All except
+// these three" cannot be expressed as a filter, so offering to untick one would
+// either lie about what gets exported or need every id the user has never
+// loaded. Leaving the mode is the way back.
+const allMatching = ref(false);
+const selectedIds = ref<Set<string>>(new Set());
+
+const selectedCount = computed(() =>
+  allMatching.value ? total.value : selectedIds.value.size,
+);
+
+// A different filter is a different result set; carrying a selection across it
+// would export rows the user can no longer see.
+watch(filter, () => {
+  allMatching.value = false;
+  selectedIds.value = new Set();
+});
+
+function isRowSelected(id: string): boolean {
+  return allMatching.value || selectedIds.value.has(id);
+}
+
+function toggleRow(id: string, checked: boolean): void {
+  const next = new Set(selectedIds.value);
+  if (checked) next.add(id);
+  else next.delete(id);
+  selectedIds.value = next;
+}
+
+function clearSelection(): void {
+  allMatching.value = false;
+  selectedIds.value = new Set();
+}
+
+function toggleAll(checked: boolean): void {
+  if (!checked) {
+    clearSelection();
+    return;
+  }
+  // Entering the mode drops any ticks: the two cannot both be in play, and
+  // keeping them would make the count ambiguous.
+  allMatching.value = true;
+  selectedIds.value = new Set();
+}
+
+const exporting = ref(false);
+const exportError = ref<string | null>(null);
+
+async function handleExport(): Promise<void> {
+  exporting.value = true;
+  exportError.value = null;
+  try {
+    await store.exportSources(
+      knowledgeId.value,
+      allMatching.value
+        ? {
+            search: filter.value.search,
+            status: filter.value.status,
+            type: filter.value.type,
+          }
+        : { ids: [...selectedIds.value] },
+    );
+  } catch (err: unknown) {
+    exportError.value = errorMessageOf(err, 'Export failed');
   } finally {
-    loading.value = false;
+    exporting.value = false;
+  }
+}
+
+// ---- background imports ----------------------------------------------------
+
+const imports = ref<IImportJob[]>([]);
+
+async function reloadImports() {
+  try {
+    imports.value = await store.listImports(knowledgeId.value);
+  } catch {
+    // Progress is a nicety; a failed poll must not break the page.
   }
 }
 
-await reload();
+await reloadImports();
 
-// While anything is processing, keep the per-source states live so the
-// operator watches the batch move instead of re-clicking (US6).
+const importRunning = computed(() =>
+  imports.value.some((j) => j.status === 'running'),
+);
+const indexing = computed(() => current?.value?.indexStatus === 'indexing');
+
+// While something is moving (index run, archive import) the list changes
+// underneath the user, so keep it fresh; go quiet the moment it stops.
 const { pause, resume } = useIntervalFn(
   async () => {
-    sources.value = await store.listSources(route.params.id as string);
-    if (!sources.value.some((s) => s.indexState === 'processing')) pause();
+    await Promise.all([load(), reloadImports()]);
+    if (indexing.value && refresh) await refresh();
   },
-  4000,
+  3000,
   { immediate: false },
 );
+
 watch(
-  () => sources.value.some((s) => s.indexState === 'processing'),
-  (busy) => {
-    if (busy) resume();
+  [indexing, importRunning],
+  ([isIndexing, isImporting]) => {
+    if (isIndexing || isImporting) resume();
     else pause();
   },
   { immediate: true },
 );
-onBeforeUnmount(() => pause());
-
-const stateBadge: Record<
-  ISource['indexState'],
-  { label: string; variant: 'default' | 'secondary' | 'outline' | 'destructive' }
-> = {
-  queued: { label: 'Queued', variant: 'outline' },
-  processing: { label: 'Processing…', variant: 'secondary' },
-  indexed: { label: 'Indexed', variant: 'default' },
-  failed: { label: 'Failed', variant: 'destructive' },
-};
-
-async function handleReindex(source: ISource) {
-  await store.reindexSource(route.params.id as string, source.id);
-  await reload();
-  resume();
-}
+
+onBeforeUnmount(pause);
+
+// ---- actions ---------------------------------------------------------------
+
+const previewing = ref<ISource | null>(null);
 
 async function handleDelete(source: ISource) {
   const ok = await confirmStore.ask({
@@ -67,90 +254,197 @@ async function handleDelete(source: ISource) {
     variant: 'destructive',
   });
   if (!ok) return;
-  await store.removeSource(route.params.id as string, source.id);
-  await reload();
+  await store.removeSource(knowledgeId.value, source.id);
+  await load();
   if (refresh) await refresh();
 }
 
+async function handleDownload(source: ISource) {
+  await store.downloadSource(knowledgeId.value, source.id);
+}
+
 async function onAdded() {
-  await reload();
+  // The new rows land at the end of the list (oldest first), so a user sitting
+  // on a later page or a filter would not see them; go back to a clean view.
+  search.value = '';
+  status.value = 'all';
+  type.value = 'all';
+  page.value = 1;
+  await Promise.all([load(), reloadImports()]);
   if (refresh) await refresh();
 }
 </script>
 
 <template>
-  <div class="flex flex-col gap-4">
-    <p class="text-sm text-muted-foreground">
-      The content this base answers from — files, web pages, pasted text.
-      Adding a source does not make it searchable yet: press
-      <span class="font-medium text-foreground">Index</span> above once
-      you're done adding.
-    </p>
+  <div class="flex min-w-0 flex-col gap-4">
+    <div class="flex flex-wrap items-center gap-2">
+      <Input
+        v-model="search"
+        placeholder="Search by name…"
+        class="w-64"
+      />
+      <Select v-model="status">
+        <SelectTrigger class="w-40">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem v-for="o in STATUS_OPTIONS" :key="o.value" :value="o.value">
+            {{ o.label }}
+          </SelectItem>
+        </SelectContent>
+      </Select>
+      <Select v-model="type">
+        <SelectTrigger class="w-36">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem v-for="o in TYPE_OPTIONS" :key="o.value" :value="o.value">
+            {{ o.label }}
+          </SelectItem>
+        </SelectContent>
+      </Select>
+      <span class="ml-auto text-sm text-muted-foreground">
+        {{ total }} source{{ total === 1 ? '' : 's' }}
+        <template v-if="loading"> · updating…</template>
+      </span>
+      <KnowledgeSourcesAddSheet :knowledge-id="knowledgeId" @added="onAdded" />
+    </div>
 
-    <KnowledgeSourcesAddForm
-      :knowledge-id="(route.params.id as string)"
-      @added="onAdded"
-    />
+    <KnowledgeSourcesImportProgress :jobs="imports" />
 
-    <KnowledgeSourcesAddFromSitemapForm
-      :knowledge-id="(route.params.id as string)"
-      @added="onAdded"
-    />
+    <div
+      v-if="selectedCount > 0"
+      class="flex flex-wrap items-center gap-3 rounded-md border bg-muted/40 px-3 py-2 text-sm"
+    >
+      <span>
+        Selected <span class="font-medium">{{ selectedCount }}</span>
+        of {{ total }}
+        <template v-if="allMatching && hasFilter"> (current filter)</template>
+      </span>
+      <button
+        type="button"
+        class="text-muted-foreground underline-offset-2 hover:underline"
+        @click="clearSelection"
+      >
+        Clear
+      </button>
+      <Button
+        size="sm"
+        class="ml-auto"
+        :disabled="exporting"
+        @click="handleExport"
+      >
+        {{ exporting ? 'Preparing…' : `Export ${selectedCount} as zip` }}
+      </Button>
+    </div>
 
-    <KnowledgeSourcesAddFromArchiveForm
-      :knowledge-id="(route.params.id as string)"
-      @added="onAdded"
-    />
+    <p v-if="exportError" class="text-sm text-destructive">
+      Export failed: {{ exportError }}
+    </p>
 
-    <div v-if="loading" class="text-sm text-muted-foreground">Loading…</div>
+    <p v-if="listError" class="text-sm text-destructive">
+      Could not load sources: {{ listError }}
+    </p>
 
-    <div v-else-if="sources.length" class="rounded-md border bg-card">
+    <div v-if="rows.length" class="min-w-0 overflow-hidden rounded-md border bg-card">
       <Table>
         <TableHeader>
           <TableRow>
+            <TableHead class="w-10">
+              <Checkbox
+                :model-value="allMatching"
+                aria-label="Select every source matching the current filter"
+                @update:model-value="
+                  (v: boolean | 'indeterminate') => toggleAll(v === true)
+                "
+              />
+            </TableHead>
             <TableHead>Name</TableHead>
-            <TableHead>Type</TableHead>
-            <TableHead>Status</TableHead>
-            <TableHead class="text-right">Actions</TableHead>
+            <TableHead class="w-20">Type</TableHead>
+            <TableHead class="w-24">Size</TableHead>
+            <TableHead class="w-64">Status</TableHead>
+            <TableHead class="w-28">Added</TableHead>
+            <TableHead class="w-28 text-right">Actions</TableHead>
           </TableRow>
         </TableHeader>
         <TableBody>
-          <TableRow v-for="s in sources" :key="s.id">
-            <TableCell class="font-medium">{{ s.name }}</TableCell>
+          <TableRow v-for="s in rows" :key="s.id">
+            <TableCell>
+              <Checkbox
+                :model-value="isRowSelected(s.id)"
+                :disabled="allMatching"
+                :aria-label="`Select ${s.name}`"
+                @update:model-value="
+                  (v: boolean | 'indeterminate') => toggleRow(s.id, v === true)
+                "
+              />
+            </TableCell>
+            <TableCell class="max-w-md font-medium">
+              <a
+                v-if="s.type === 'url' && s.url"
+                :href="s.url"
+                target="_blank"
+                rel="noopener"
+                class="block truncate underline-offset-2 hover:underline"
+                :title="s.url"
+              >
+                {{ s.name }}
+              </a>
+              <span v-else class="block truncate" :title="s.name">{{ s.name }}</span>
+            </TableCell>
             <TableCell class="text-muted-foreground">{{ s.type }}</TableCell>
+            <TableCell class="text-muted-foreground">{{ formatBytes(s.sizeBytes) }}</TableCell>
             <TableCell>
-              <div class="flex flex-col gap-0.5">
-                <Badge
-                  :variant="stateBadge[s.indexState].variant"
-                  class="w-fit"
-                >
-                  {{ stateBadge[s.indexState].label }}
-                </Badge>
+              <!-- The width cap is not cosmetic: an index error is one long
+                   unbreakable line (chunk ids, model names), and without a
+                   ceiling its min-content width sets the width of the whole
+                   table and pushes the page sideways. -->
+              <div class="flex max-w-60 flex-col gap-1">
+                <KnowledgeSourceStatusBadge :status="s.indexStatus" class="w-fit" />
                 <span
-                  v-if="s.indexState === 'failed' && s.indexError"
-                  class="max-w-md text-xs text-destructive"
+                  v-if="s.indexStatus === 'failed' && s.indexError"
+                  class="line-clamp-2 text-xs break-words text-destructive"
+                  :title="s.indexError"
                 >
                   {{ s.indexError }}
                 </span>
               </div>
             </TableCell>
+            <TableCell class="text-muted-foreground">{{ formatDate(s.createdAt) }}</TableCell>
             <TableCell class="text-right">
-              <div class="flex justify-end gap-2">
+              <!-- Icons rather than three word-buttons: the labels cost more
+                   horizontal room than the Name column had to spare, and these
+                   three actions are the same on every row. -->
+              <div class="flex justify-end gap-0.5">
                 <Button
-                  v-if="s.indexState === 'failed'"
-                  size="sm"
-                  variant="outline"
-                  @click="handleReindex(s)"
+                  v-if="s.type !== 'url'"
+                  size="icon-sm"
+                  variant="ghost"
+                  title="Preview"
+                  @click="previewing = s"
+                >
+                  <Eye class="size-4" />
+                  <span class="sr-only">Preview {{ s.name }}</span>
+                </Button>
+                <Button
+                  v-if="s.type !== 'url'"
+                  size="icon-sm"
+                  variant="ghost"
+                  title="Download"
+                  @click="handleDownload(s)"
                 >
-                  Retry
+                  <Download class="size-4" />
+                  <span class="sr-only">Download {{ s.name }}</span>
                 </Button>
                 <Button
-                  size="sm"
+                  size="icon-sm"
                   variant="ghost"
                   class="text-destructive"
+                  title="Delete"
                   @click="handleDelete(s)"
                 >
-                  Delete
+                  <Trash2 class="size-4" />
+                  <span class="sr-only">Delete {{ s.name }}</span>
                 </Button>
               </div>
             </TableCell>
@@ -160,10 +454,29 @@ async function onAdded() {
     </div>
 
     <div
-      v-else
+      v-else-if="!loading && !listError"
       class="rounded-md border border-dashed p-6 text-center text-sm text-muted-foreground"
     >
-      No sources yet. Add one above, then run Index.
+      <template v-if="hasFilter">No sources match these filters.</template>
+      <template v-else>No sources yet. Add one above, then run Index.</template>
     </div>
+
+    <div v-if="pageCount > 1" class="flex items-center justify-end gap-2 text-sm">
+      <span class="text-muted-foreground">
+        Page {{ page }} of {{ pageCount }} · {{ total }} total
+      </span>
+      <Button size="sm" variant="outline" :disabled="page <= 1" @click="page--">
+        Prev
+      </Button>
+      <Button size="sm" variant="outline" :disabled="page >= pageCount" @click="page++">
+        Next
+      </Button>
+    </div>
+
+    <KnowledgeSourcesPreviewSheet
+      :knowledge-id="knowledgeId"
+      :source="previewing"
+      @close="previewing = null"
+    />
   </div>
 </template>
diff --git a/admin/slices/reins/data/knowledge.gateway.ts b/admin/slices/reins/data/knowledge.gateway.ts
index 9331fe88..a80dc94c 100644
--- a/admin/slices/reins/data/knowledge.gateway.ts
+++ b/admin/slices/reins/data/knowledge.gateway.ts
@@ -7,19 +7,43 @@ import type {
   ICreateKnowledgeInput,
   IGraph,
   IGraphLabels,
+  IImportJob,
   IKnowledge,
   IKnowledgePage,
   IKnowledgeStatus,
   IQueryResult,
   ISource,
   ISourceArchiveResult,
+  ISourceContent,
+  ISourceExportSelection,
   ISourceFilesResult,
+  ISourceFilter,
+  ISourcePage,
   ISourceSitemapResult,
   IUpdateKnowledgeInput,
   KnowledgeQueryMode,
+  SourceContentDisposition,
 } from '../domain/knowledge.types';
 import { KnowledgeMapper } from './knowledge.mapper';
 
+/**
+ * Pulls the human filename out of a Content-Disposition header, preferring
+ * the RFC 5987 `filename*` (UTF-8, survives Cyrillic) over the ASCII
+ * fallback `filename`.
+ */
+function filenameFromDisposition(header: unknown, fallback: string): string {
+  if (typeof header !== 'string') return fallback;
+  const utf8 = header.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
+  if (utf8) {
+    try {
+      return decodeURIComponent(utf8);
+    } catch {
+      // Malformed encoding: fall through to the plain filename.
+    }
+  }
+  return header.match(/filename="?([^";]+)"?/)?.[1] ?? fallback;
+}
+
 export class KnowledgeGateway extends BaseGateway implements IKnowledgeGateway {
   private mapper = new KnowledgeMapper();
 
@@ -114,12 +138,91 @@ export class KnowledgeGateway extends BaseGateway implements IKnowledgeGateway {
     });
   }
 
-  listSources(id: string): Promise<ISource[]> {
+  listSources(id: string, filter: ISourceFilter): Promise<ISourcePage> {
     return this.execute(async () => {
       const res = await KnowledgeSourcesService.getKnowledgeSources({
         path: { knowledgeId: id },
+        query: {
+          page: filter.page,
+          perPage: filter.perPage,
+          search: filter.search || undefined,
+          status: filter.status,
+          type: filter.type,
+        },
       });
-      return this.mapper.toSourceList(unwrapEnvelope(res.data));
+      return this.mapper.toSourcePage(unwrapEnvelope(res.data), filter);
+    });
+  }
+
+  listImports(id: string): Promise<IImportJob[]> {
+    return this.execute(async () => {
+      const res = await KnowledgeSourcesService.getKnowledgeSourceImports({
+        path: { knowledgeId: id },
+      });
+      return this.mapper.toImportJobs(unwrapEnvelope(res.data));
+    });
+  }
+
+  // Raw bytes, so the generated SDK (which expects the JSON envelope) is
+  // bypassed: axios blob response on the shared instance keeps the Bearer
+  // header, and the filename comes back in Content-Disposition.
+  fetchSourceContent(
+    id: string,
+    sourceId: string,
+    disposition: SourceContentDisposition,
+  ): Promise<ISourceContent> {
+    return this.execute(async () => {
+      const res = await apiClient.instance.get<unknown>(
+        `/knowledges/${id}/sources/${sourceId}/content`,
+        { params: { disposition }, responseType: 'blob' },
+      );
+      const blob = res.data instanceof Blob ? res.data : new Blob([]);
+      return {
+        blob,
+        filename: filenameFromDisposition(
+          res.headers['content-disposition'],
+          sourceId,
+        ),
+        contentType:
+          typeof res.headers['content-type'] === 'string'
+            ? res.headers['content-type']
+            : blob.type,
+      };
+    });
+  }
+
+  exportSources(
+    id: string,
+    selection: ISourceExportSelection,
+  ): Promise<ISourceContent> {
+    return this.execute(async () => {
+      // Ids win when present, matching the API: a tick-list and a filter can
+      // disagree by the time the request lands, and the ticks are what the
+      // user actually saw.
+      const params: Record<string, string> = {};
+      if (selection.ids && selection.ids.length > 0) {
+        params.ids = selection.ids.join(',');
+      } else {
+        if (selection.search) params.search = selection.search;
+        if (selection.status) params.status = selection.status;
+        if (selection.type) params.type = selection.type;
+      }
+      const res = await apiClient.instance.get<unknown>(
+        `/knowledges/${id}/sources/export`,
+        { params, responseType: 'blob' },
+      );
+      const blob = res.data instanceof Blob ? res.data : new Blob([]);
+      return {
+        blob,
+        filename: filenameFromDisposition(
+          res.headers['content-disposition'],
+          `${id}-sources.zip`,
+        ),
+        contentType:
+          typeof res.headers['content-type'] === 'string'
+            ? res.headers['content-type']
+            : blob.type,
+      };
     });
   }
 
diff --git a/admin/slices/reins/data/knowledge.mapper.ts b/admin/slices/reins/data/knowledge.mapper.ts
index 8fa0e708..b49b36b3 100644
--- a/admin/slices/reins/data/knowledge.mapper.ts
+++ b/admin/slices/reins/data/knowledge.mapper.ts
@@ -1,19 +1,25 @@
 import type {
   IGraph,
   IGraphLabels,
+  IImportJob,
   IKnowledge,
   IKnowledgePage,
+  IKnowledgeRuntimeConfig,
   IKnowledgeSetupStatus,
   IKnowledgeStatus,
+  ImportJobStatus,
   IndexStatus,
   InstanceState,
   IQueryResult,
   ISource,
   ISourceArchiveResult,
   ISourceFilesResult,
+  ISourceFilter,
+  ISourcePage,
   ISourceSitemapResult,
   MigrationState,
   SourceIndexState,
+  SourceIndexStatus,
   SourceType,
 } from '../domain/knowledge.types';
 
@@ -26,6 +32,34 @@ const INDEX_STATUSES = new Set<IndexStatus>([
   'partial',
 ]);
 const SOURCE_TYPES = new Set<SourceType>(['file', 'url', 'text']);
+const SOURCE_INDEX_STATUSES = new Set<SourceIndexStatus>([
+  'indexed',
+  'pending',
+  'failed',
+]);
+const IMPORT_JOB_STATUSES = new Set<ImportJobStatus>([
+  'running',
+  'done',
+  'failed',
+]);
+
+function isSourceIndexStatus(value: unknown): value is SourceIndexStatus {
+  return (
+    typeof value === 'string' &&
+    SOURCE_INDEX_STATUSES.has(value as SourceIndexStatus)
+  );
+}
+
+function isImportJobStatus(value: unknown): value is ImportJobStatus {
+  return (
+    typeof value === 'string' && IMPORT_JOB_STATUSES.has(value as ImportJobStatus)
+  );
+}
+
+function num(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
 const SOURCE_INDEX_STATES = new Set<SourceIndexState>([
   'queued',
   'processing',
@@ -91,6 +125,10 @@ export class KnowledgeMapper {
       indexError: nullableStr(o.indexError),
       indexedAt: nullableStr(o.indexedAt),
       indexStartedAt: nullableStr(o.indexStartedAt),
+      sourceCount: num(o.sourceCount),
+      indexedCount: num(o.indexedCount),
+      failedCount: num(o.failedCount),
+      processingCount: num(o.processingCount),
       instanceState:
         typeof o.instanceState === 'string' &&
         INSTANCE_STATES.has(o.instanceState as InstanceState)
@@ -148,6 +186,14 @@ export class KnowledgeMapper {
       mimeType: nullableStr(o.mimeType),
       content: nullableStr(o.content),
       sizeBytes: typeof o.sizeBytes === 'number' ? o.sizeBytes : null,
+      indexed: bool(o.indexed),
+      // Older API builds only send `indexed`; derive the status from it so
+      // the table still renders sensibly against them.
+      indexStatus: isSourceIndexStatus(o.indexStatus)
+        ? o.indexStatus
+        : bool(o.indexed)
+          ? 'indexed'
+          : 'pending',
       indexState:
         typeof o.indexState === 'string' &&
         SOURCE_INDEX_STATES.has(o.indexState as SourceIndexState)
@@ -167,12 +213,69 @@ export class KnowledgeMapper {
       .filter((s): s is ISource => s !== null);
   }
 
+  toSourcePage(raw: unknown, requested: ISourceFilter): ISourcePage {
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+      const o = raw as Record<string, unknown>;
+      return {
+        items: this.toSourceList(o.items),
+        total: num(o.total),
+        page: num(o.page) || requested.page,
+        perPage: num(o.perPage) || requested.perPage,
+      };
+    }
+    return { items: [], total: 0, page: requested.page, perPage: requested.perPage };
+  }
+
+  toImportJob(raw: unknown): IImportJob | null {
+    if (!raw || typeof raw !== 'object') return null;
+    const o = raw as Record<string, unknown>;
+    if (typeof o.id !== 'string') return null;
+    return {
+      id: o.id,
+      knowledgeId: str(o.knowledgeId),
+      kind: 'archive',
+      status: isImportJobStatus(o.status) ? o.status : 'done',
+      detected: num(o.detected),
+      added: num(o.added),
+      skipped: num(o.skipped),
+      failed: num(o.failed),
+      errors: strList(o.errors),
+      startedAt: str(o.startedAt),
+      finishedAt: nullableStr(o.finishedAt),
+    };
+  }
+
+  toImportJobs(raw: unknown): IImportJob[] {
+    if (!Array.isArray(raw)) return [];
+    return raw
+      .map((j) => this.toImportJob(j))
+      .filter((j): j is IImportJob => j !== null);
+  }
+
   toStatus(raw: unknown): IKnowledgeStatus {
     if (!raw || typeof raw !== 'object' || typeof (raw as Record<string, unknown>).enabled !== 'boolean') {
-      return { enabled: false, setup: { ...EMPTY_SETUP } };
+      return { enabled: false, setup: { ...EMPTY_SETUP }, runtime: null };
     }
     const o = raw as Record<string, unknown>;
-    return { enabled: o.enabled === true, setup: this.toSetup(o.setup) };
+    return {
+      enabled: o.enabled === true,
+      setup: this.toSetup(o.setup),
+      runtime: this.toRuntime(o.runtime),
+    };
+  }
+
+  private toRuntime(raw: unknown): IKnowledgeRuntimeConfig | null {
+    if (!raw || typeof raw !== 'object') return null;
+    const o = raw as Record<string, unknown>;
+    const nullableStr = (value: unknown): string | null =>
+      typeof value === 'string' && value.length > 0 ? value : null;
+    return {
+      llmBinding: nullableStr(o.llmBinding),
+      llmModel: nullableStr(o.llmModel),
+      embeddingBinding: nullableStr(o.embeddingBinding),
+      embeddingModel: nullableStr(o.embeddingModel),
+      embeddingBindingHost: nullableStr(o.embeddingBindingHost),
+    };
   }
 
   toQueryResult(raw: unknown): IQueryResult {
@@ -194,10 +297,10 @@ export class KnowledgeMapper {
     if (raw && typeof raw === 'object') {
       const o = raw as Record<string, unknown>;
       if (typeof o.detected === 'number' && typeof o.started === 'boolean') {
-        return { detected: o.detected, started: o.started };
+        return { detected: o.detected, started: o.started, jobId: str(o.jobId) };
       }
     }
-    return { detected: 0, started: false };
+    return { detected: 0, started: false, jobId: '' };
   }
 
   toFilesResult(raw: unknown): ISourceFilesResult {
diff --git a/admin/slices/reins/domain/format.ts b/admin/slices/reins/domain/format.ts
new file mode 100644
index 00000000..7b0cc751
--- /dev/null
+++ b/admin/slices/reins/domain/format.ts
@@ -0,0 +1,49 @@
+/** Human-readable byte count for tables and previews; `-` when unknown. */
+export function formatBytes(size: number | null): string {
+  if (size === null) return '-';
+  if (size < 1024) return `${size} B`;
+  if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`;
+  return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Readable message out of an unknown thrown value.
+ *
+ * The API wraps failures in an envelope, so the sentence worth showing sits at
+ * `response.data.message` rather than on the Error itself. Everything else
+ * falls back to the caller's wording: rendering `[object Object]` in a red box
+ * tells a user nothing.
+ */
+export function errorMessageOf(err: unknown, fallback: string): string {
+  if (typeof err === 'string' && err.trim()) return err;
+  if (!isRecord(err)) return fallback;
+
+  const response = err.response;
+  if (isRecord(response) && isRecord(response.data)) {
+    const message = response.data.message;
+    if (typeof message === 'string' && message.trim()) return message;
+  }
+
+  const message = err.message;
+  return typeof message === 'string' && message.trim() ? message : fallback;
+}
+
+function parseDate(iso: string | null | undefined): Date | null {
+  if (!iso) return null;
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+/** Date only, for table columns where the time of day is noise. */
+export function formatDate(iso: string | null | undefined): string {
+  return parseDate(iso)?.toLocaleDateString() ?? '-';
+}
+
+/** Date and time, for "when did this last finish" readouts. */
+export function formatDateTime(iso: string | null | undefined): string {
+  return parseDate(iso)?.toLocaleString() ?? 'never';
+}
diff --git a/admin/slices/reins/domain/index.ts b/admin/slices/reins/domain/index.ts
index dfd79c76..a4072382 100644
--- a/admin/slices/reins/domain/index.ts
+++ b/admin/slices/reins/domain/index.ts
@@ -1,3 +1,4 @@
 export * from './knowledge.gateway';
 export * from './knowledge.service';
 export * from './knowledge.types';
+export * from './format';
diff --git a/admin/slices/reins/domain/knowledge.gateway.ts b/admin/slices/reins/domain/knowledge.gateway.ts
index 270b25fc..984a9a50 100644
--- a/admin/slices/reins/domain/knowledge.gateway.ts
+++ b/admin/slices/reins/domain/knowledge.gateway.ts
@@ -2,16 +2,22 @@ import type {
   ICreateKnowledgeInput,
   IGraph,
   IGraphLabels,
+  IImportJob,
   IKnowledge,
   IKnowledgePage,
   IKnowledgeStatus,
   IQueryResult,
   ISource,
   ISourceArchiveResult,
+  ISourceContent,
+  ISourceExportSelection,
   ISourceFilesResult,
+  ISourceFilter,
+  ISourcePage,
   ISourceSitemapResult,
   IUpdateKnowledgeInput,
   KnowledgeQueryMode,
+  SourceContentDisposition,
 } from './knowledge.types';
 
 /** Contract for the knowledge-bases API. Implemented by `KnowledgeGateway`. */
@@ -37,7 +43,17 @@ export abstract class IKnowledgeGateway {
     mode: KnowledgeQueryMode,
     topK: number,
   ): Promise<IQueryResult>;
-  abstract listSources(id: string): Promise<ISource[]>;
+  abstract listSources(id: string, filter: ISourceFilter): Promise<ISourcePage>;
+  abstract listImports(id: string): Promise<IImportJob[]>;
+  abstract fetchSourceContent(
+    id: string,
+    sourceId: string,
+    disposition: SourceContentDisposition,
+  ): Promise<ISourceContent>;
+  abstract exportSources(
+    id: string,
+    selection: ISourceExportSelection,
+  ): Promise<ISourceContent>;
   abstract addTextSource(
     id: string,
     name: string,
diff --git a/admin/slices/reins/domain/knowledge.service.ts b/admin/slices/reins/domain/knowledge.service.ts
index 270af239..c32482be 100644
--- a/admin/slices/reins/domain/knowledge.service.ts
+++ b/admin/slices/reins/domain/knowledge.service.ts
@@ -3,16 +3,22 @@ import type {
   ICreateKnowledgeInput,
   IGraph,
   IGraphLabels,
+  IImportJob,
   IKnowledge,
   IKnowledgePage,
   IKnowledgeStatus,
   IQueryResult,
   ISource,
   ISourceArchiveResult,
+  ISourceContent,
+  ISourceExportSelection,
   ISourceFilesResult,
+  ISourceFilter,
+  ISourcePage,
   ISourceSitemapResult,
   IUpdateKnowledgeInput,
   KnowledgeQueryMode,
+  SourceContentDisposition,
 } from './knowledge.types';
 
 /**
@@ -70,8 +76,27 @@ export class KnowledgeService {
     return this.gateway.query(id, q, mode, topK);
   }
 
-  listSources(id: string): Promise<ISource[]> {
-    return this.gateway.listSources(id);
+  listSources(id: string, filter: ISourceFilter): Promise<ISourcePage> {
+    return this.gateway.listSources(id, filter);
+  }
+
+  listImports(id: string): Promise<IImportJob[]> {
+    return this.gateway.listImports(id);
+  }
+
+  fetchSourceContent(
+    id: string,
+    sourceId: string,
+    disposition: SourceContentDisposition,
+  ): Promise<ISourceContent> {
+    return this.gateway.fetchSourceContent(id, sourceId, disposition);
+  }
+
+  exportSources(
+    id: string,
+    selection: ISourceExportSelection,
+  ): Promise<ISourceContent> {
+    return this.gateway.exportSources(id, selection);
   }
 
   addTextSource(
diff --git a/admin/slices/reins/domain/knowledge.types.ts b/admin/slices/reins/domain/knowledge.types.ts
index 07a3e09c..d4ac14a4 100644
--- a/admin/slices/reins/domain/knowledge.types.ts
+++ b/admin/slices/reins/domain/knowledge.types.ts
@@ -23,6 +23,7 @@ export type IndexStatus =
   | 'empty'
   | 'partial';
 export type SourceType = 'file' | 'url' | 'text';
+export type SourceIndexStatus = 'indexed' | 'pending' | 'failed';
 export type KnowledgeQueryMode = 'hybrid' | 'local' | 'global' | 'naive';
 
 export type InstanceState =
@@ -41,6 +42,12 @@ export interface IKnowledge {
   indexError: string | null;
   indexedAt: string | null;
   indexStartedAt: string | null;
+  /** Index progress over the attached sources, as counted by the API. */
+  sourceCount: number;
+  indexedCount: number;
+  failedCount: number;
+  /** Handed to LightRAG, not finished yet. Not an error, just not done. */
+  processingCount: number;
   instanceState: InstanceState;
   instanceError: string | null;
   migrationState: MigrationState;
@@ -70,6 +77,8 @@ export interface ISource {
   mimeType: string | null;
   content: string | null;
   sizeBytes: number | null;
+  indexed: boolean;
+  indexStatus: SourceIndexStatus;
   /** "indexed" means searchable — not merely handed over. */
   indexState: SourceIndexState;
   indexError: string | null;
@@ -78,6 +87,59 @@ export interface ISource {
   updatedAt: string;
 }
 
+export interface ISourceFilter {
+  page: number;
+  perPage: number;
+  search?: string;
+  status?: SourceIndexStatus;
+  type?: SourceType;
+}
+
+export interface ISourcePage {
+  items: ISource[];
+  total: number;
+  page: number;
+  perPage: number;
+}
+
+export type ImportJobStatus = 'running' | 'done' | 'failed';
+
+/** Progress of one background bulk import (archive). */
+export interface IImportJob {
+  id: string;
+  knowledgeId: string;
+  kind: 'archive';
+  status: ImportJobStatus;
+  detected: number;
+  added: number;
+  skipped: number;
+  failed: number;
+  errors: string[];
+  startedAt: string;
+  finishedAt: string | null;
+}
+
+/**
+ * What the Export button sends. Either the ticked ids, or the same filter the
+ * table is showing - "select all" must not mean "the 50 rows on this page",
+ * and 356 ids in a query string is not a URL.
+ */
+export interface ISourceExportSelection {
+  ids?: string[];
+  search?: string;
+  status?: SourceIndexStatus;
+  type?: SourceType;
+}
+
+export type SourceContentDisposition = 'inline' | 'attachment';
+
+/** Bytes of a source as fetched for preview or download. */
+export interface ISourceContent {
+  blob: Blob;
+  filename: string;
+  contentType: string;
+}
+
 export interface ICreateKnowledgeInput {
   name: string;
   description?: string;
@@ -97,14 +159,30 @@ export interface IKnowledgeSetupStatus {
   isHealthy: boolean;
 }
 
+/**
+ * What LightRAG is actually running, read from its own /health. Its bindings
+ * are resolved from container env at startup, so this is the effective config
+ * regardless of what is selected in the admin.
+ */
+export interface IKnowledgeRuntimeConfig {
+  llmBinding: string | null;
+  llmModel: string | null;
+  embeddingBinding: string | null;
+  embeddingModel: string | null;
+  embeddingBindingHost: string | null;
+}
+
 export interface IKnowledgeStatus {
   enabled: boolean;
   setup: IKnowledgeSetupStatus;
+  runtime: IKnowledgeRuntimeConfig | null;
 }
 
 export interface ISourceArchiveResult {
   detected: number;
   started: boolean;
+  /** Id of the background job to follow via listImports. */
+  jobId: string;
 }
 
 export interface ISourceSitemapResult {
diff --git a/admin/slices/reins/pages/knowledges/[id].vue b/admin/slices/reins/pages/knowledges/[id].vue
index 0d2fab9b..dad65b44 100644
--- a/admin/slices/reins/pages/knowledges/[id].vue
+++ b/admin/slices/reins/pages/knowledges/[id].vue
@@ -1,57 +1,52 @@
 <script setup lang="ts">
 import { useIntervalFn } from '@vueuse/core';
 import { Button } from '#theme/components/ui/button';
-import type { IKnowledge, ISource } from '#reins/stores/knowledge';
+import type { IKnowledge } from '#reins/stores/knowledge';
 
 const route = useRoute();
 const store = useKnowledgeStore();
+const confirmStore = useConfirmStore();
 
 const knowledgeId = computed(() => route.params.id as string);
 const current = ref<IKnowledge | null>(null);
-const sources = ref<ISource[]>([]);
 const indexing = ref(false);
 const indexError = ref<string | null>(null);
 
 async function refresh() {
-  [current.value, sources.value] = await Promise.all([
-    store.fetchById(knowledgeId.value),
-    store.listSources(knowledgeId.value).catch(() => []),
-  ]);
+  current.value = await store.fetchById(knowledgeId.value);
 }
 
 await refresh();
 
-// What the base holds and whether it can answer — visible without leaving
-// the header (FR-023).
-const searchableCount = computed(
-  () => sources.value.filter((s) => s.indexState === 'indexed').length,
-);
-const queuedCount = computed(
-  () => sources.value.filter((s) => s.indexState === 'queued').length,
-);
-const canAnswer = computed(
-  () =>
-    searchableCount.value > 0 &&
-    (current.value?.instanceState === 'ready' ||
-      current.value?.migrationState !== 'done'),
-);
+const POLL_RUNNING_MS = 3000;
+// Reconciliation is a background drip, not a live run: a large document sits in
+// LightRAG's pipeline for the better part of an hour, and watching that at the
+// run cadence would be thousands of requests to catch a badge that changes once.
+const POLL_PROCESSING_MS = 15000;
+
+// 'running' is a run executing right now; 'processing' is LightRAG still
+// chunking documents a finished run stopped waiting for. Both mean the page is
+// out of date soon, at very different speeds.
+const outstanding = computed<'running' | 'processing' | 'none'>(() => {
+  const k = current.value;
+  if (!k) return 'none';
+  if (k.indexStatus === 'indexing') return 'running';
+  return k.processingCount > 0 ? 'processing' : 'none';
+});
 
 const { pause, resume } = useIntervalFn(
-  async () => {
-    await refresh();
-    if (current.value?.indexStatus !== 'indexing') {
-      pause();
-    }
-  },
-  3000,
+  refresh,
+  computed(() =>
+    outstanding.value === 'running' ? POLL_RUNNING_MS : POLL_PROCESSING_MS,
+  ),
   { immediate: false },
 );
 
 watch(
-  () => current.value?.indexStatus,
-  (status) => {
-    if (status === 'indexing') resume();
-    else pause();
+  outstanding,
+  (state) => {
+    if (state === 'none') pause();
+    else resume();
   },
   { immediate: true },
 );
@@ -60,8 +55,55 @@ onBeforeUnmount(() => {
   pause();
 });
 
+// Sources that an index run will actually push through LightRAG. Ones already
+// indexed are only re-checked, so they cost nothing.
+const toIndex = computed(() => {
+  if (!current.value) return 0;
+  return current.value.sourceCount - current.value.indexedCount;
+});
+
+const progressPercent = computed(() => {
+  if (!current.value || current.value.sourceCount === 0) return 0;
+  return Math.round(
+    (current.value.indexedCount / current.value.sourceCount) * 100,
+  );
+});
+
 async function handleIndex() {
   if (!current.value) return;
+
+  // Re-indexing is what costs money (LLM over every unindexed document), and
+  // people were pressing it "to be sure". Say exactly what will happen first.
+  //
+  // The count is a floor, not a promise: it is derived from what Ranch has
+  // recorded, while the run asks LightRAG about every source and re-sends
+  // whatever it no longer holds. After the LightRAG index is cleared this
+  // dialog said "42 of 210" and then sent all 210, so the wording has to admit
+  // that rather than quote a number it cannot guarantee.
+  const total = current.value.sourceCount;
+  // Sources LightRAG is still chunking are waited on, not re-sent, so they do
+  // not belong in the "never confirmed" bucket that reads as work to redo.
+  const processing = current.value.processingCount;
+  const neverConfirmed = toIndex.value - current.value.failedCount - processing;
+  const breakdown = [
+    `${current.value.failedCount} failed earlier`,
+    ...(processing > 0 ? [`${processing} still processing`] : []),
+    `${neverConfirmed} never confirmed`,
+  ].join(', ');
+  const knownWork =
+    toIndex.value === 0
+      ? `All ${total} source${total === 1 ? ' is' : 's are'} marked indexed, so this run may only re-verify them.`
+      : `At least ${toIndex.value} of ${total} source${total === 1 ? '' : 's'} will go through the LLM (${breakdown}).`;
+  const description = `${knownWork} Every source is re-checked against LightRAG, and any it no longer holds is sent again - if the LightRAG index was cleared, that means all ${total}. This costs money and can take a while on a large base.`;
+
+  const ok = await confirmStore.ask({
+    title: `Index ${current.value.name}?`,
+    description,
+    confirmLabel: 'Start indexing',
+    cancelLabel: 'Cancel',
+  });
+  if (!ok) return;
+
   indexing.value = true;
   indexError.value = null;
   try {
@@ -76,25 +118,64 @@ async function handleIndex() {
   }
 }
 
-// Everyday path first (add content, ask); the graph is an inspection
-// surface and sits last rather than mid-flow (FR-024).
 const tabs = computed(() => [
+  { to: `/knowledges/${knowledgeId.value}`, label: 'Overview' },
   { to: `/knowledges/${knowledgeId.value}/sources`, label: 'Sources' },
-  { to: `/knowledges/${knowledgeId.value}/query`, label: 'Query' },
-  { to: `/knowledges/${knowledgeId.value}/edit`, label: 'General' },
   { to: `/knowledges/${knowledgeId.value}/graph`, label: 'Graph' },
+  { to: `/knowledges/${knowledgeId.value}/query`, label: 'Query' },
 ]);
 
+// Deliberately not NuxtLink's `active-class`. That prop appends classes rather
+// than replacing them, so `border-primary` and the base `border-transparent`
+// end up at equal specificity and the winner is decided by their order in the
+// generated stylesheet, not by the markup - which is why the selected tab was
+// never highlighted. Binding the whole class set on an explicit match removes
+// the conflict. Exact comparison, because Overview's path is a prefix of every
+// sibling's and a prefix match would light all four at once.
+function isActive(to: string): boolean {
+  return route.path.replace(/\/+$/, '') === to;
+}
+
+// The index error is a concatenation of one message per failed source, so on a
+// large base it is a paragraph, not a line. Show the shape of it and let the
+// full text be asked for.
+const ERROR_PREVIEW_CHARS = 160;
+const errorExpanded = ref(false);
+const errorIsLong = computed(
+  () => (current.value?.indexError?.length ?? 0) > ERROR_PREVIEW_CHARS,
+);
+
 const indexDisabled = computed(
   () => current.value?.indexStatus === 'indexing' || indexing.value,
 );
 
+// Whether the base can answer, and the isolation-era retrieval health —
+// visible without leaving the header (FR-023). Derived from the row's
+// counts: the source list endpoint pages at 200 and these numbers must not.
+const canAnswer = computed(() => {
+  const k = current.value;
+  if (!k) return false;
+  return (
+    k.indexedCount > 0 &&
+    (k.instanceState === 'ready' || k.migrationState !== 'done')
+  );
+});
+const queuedCount = computed(() => {
+  const k = current.value;
+  if (!k) return 0;
+  // Never sent and not failed: what the Index button will actually process.
+  return Math.max(
+    k.sourceCount - k.indexedCount - k.processingCount - k.failedCount,
+    0,
+  );
+});
+
 provide('knowledge-current', current);
 provide('knowledge-refresh', refresh);
 </script>
 
 <template>
-  <div class="flex flex-col gap-6">
+  <div class="flex min-w-0 flex-col gap-6">
     <NuxtLink
       to="/knowledges"
       class="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground"
@@ -103,15 +184,26 @@ provide('knowledge-refresh', refresh);
     </NuxtLink>
 
     <div v-if="current" class="flex items-start justify-between gap-4">
-      <div class="min-w-0">
+      <div class="min-w-0 flex-1">
         <h1 class="text-2xl font-semibold truncate">{{ current.name }}</h1>
         <div class="mt-1 flex flex-wrap items-center gap-2 text-sm text-muted-foreground">
-          <KnowledgeIndexStatusBadge :status="current.indexStatus" />
+          <KnowledgeIndexStatusBadge
+            :status="current.indexStatus"
+            :processing="current.processingCount > 0"
+          />
           <span>
-            {{ sources.length }} {{ sources.length === 1 ? 'source' : 'sources' }}
-            <template v-if="sources.length">
-              · {{ searchableCount }} searchable
-            </template>
+            Indexed
+            <span class="font-medium text-foreground">{{ current.indexedCount }}</span>
+            / {{ current.sourceCount }}
+          </span>
+          <span
+            v-if="current.processingCount"
+            title="Handed to LightRAG and still being chunked. They are confirmed automatically as it finishes."
+          >
+            · {{ current.processingCount }} processing
+          </span>
+          <span v-if="current.failedCount" class="text-destructive">
+            · {{ current.failedCount }} failed
           </span>
           <span v-if="canAnswer" class="text-emerald-600">
             · ready to answer
@@ -125,9 +217,33 @@ provide('knowledge-refresh', refresh);
           <span v-else-if="current.instanceState === 'starting'">
             · retrieval starting…
           </span>
-          <span v-if="current.indexError" class="text-destructive">
+        </div>
+
+        <div v-if="current.indexError" class="mt-2 max-w-3xl text-sm text-destructive">
+          <p
+            class="break-words"
+            :class="{ 'line-clamp-2': errorIsLong && !errorExpanded }"
+          >
             {{ current.indexError }}
-          </span>
+          </p>
+          <button
+            v-if="errorIsLong"
+            type="button"
+            class="mt-1 text-xs underline underline-offset-2"
+            @click="errorExpanded = !errorExpanded"
+          >
+            {{ errorExpanded ? 'Show less' : 'Show full error' }}
+          </button>
+        </div>
+        <div
+          v-if="current.indexStatus === 'indexing'"
+          class="mt-2 h-1.5 w-full max-w-md overflow-hidden rounded bg-muted"
+          :title="`${progressPercent}%`"
+        >
+          <div
+            class="h-full bg-primary transition-all"
+            :style="{ width: `${progressPercent}%` }"
+          />
         </div>
         <!-- Only while a migration run is actually executing: with instance
              isolation switched off, notStarted is the permanent, healthy
@@ -159,31 +275,19 @@ provide('knowledge-refresh', refresh);
       has been indexed.
     </div>
 
-    <!-- `custom` slot: exactly one class set is ever applied per state. The
-         old active-class approach set the same properties from two classes
-         at equal specificity, so stylesheet order decided the winner and
-         nothing ever highlighted. -->
     <nav class="flex gap-1 border-b">
       <NuxtLink
         v-for="tab in tabs"
         :key="tab.to"
-        v-slot="{ href, navigate, isActive }"
         :to="tab.to"
-        custom
+        class="border-b-2 px-3 py-2 text-sm transition-colors"
+        :class="
+          isActive(tab.to)
+            ? 'border-primary font-medium text-foreground'
+            : 'border-transparent text-muted-foreground hover:text-foreground'
+        "
       >
-        <a
-          :href="href ?? undefined"
-          class="border-b-2 px-3 py-2 text-sm transition-colors"
-          :class="
-            isActive
-              ? 'border-primary font-medium text-foreground'
-              : 'border-transparent text-muted-foreground hover:text-foreground'
-          "
-          :aria-current="isActive ? 'page' : undefined"
-          @click="navigate"
-        >
-          {{ tab.label }}
-        </a>
+        {{ tab.label }}
       </NuxtLink>
     </nav>
 
diff --git a/admin/slices/reins/pages/knowledges/[id]/edit.vue b/admin/slices/reins/pages/knowledges/[id]/edit.vue
deleted file mode 100644
index 0fc8fc24..00000000
--- a/admin/slices/reins/pages/knowledges/[id]/edit.vue
+++ /dev/null
@@ -1,3 +0,0 @@
-<template>
-  <KnowledgeEditProvider />
-</template>
diff --git a/admin/slices/reins/pages/knowledges/[id]/index.vue b/admin/slices/reins/pages/knowledges/[id]/index.vue
index 8a2d72f3..8c2babe3 100644
--- a/admin/slices/reins/pages/knowledges/[id]/index.vue
+++ b/admin/slices/reins/pages/knowledges/[id]/index.vue
@@ -1,14 +1,3 @@
-<script setup lang="ts">
-// The sectionless URL /knowledges/:id used to render an empty body — the
-// layout has tabs but no default child. Land on the everyday section, with
-// the Sources tab correctly marked current (FR-027, SC-010).
-const route = useRoute();
-
-await navigateTo(`/knowledges/${route.params.id as string}/sources`, {
-  replace: true,
-});
-</script>
-
 <template>
-  <div />
+  <KnowledgeOverviewProvider />
 </template>
diff --git a/admin/slices/reins/stores/knowledge.ts b/admin/slices/reins/stores/knowledge.ts
index ea9b2147..19063649 100644
--- a/admin/slices/reins/stores/knowledge.ts
+++ b/admin/slices/reins/stores/knowledge.ts
@@ -2,10 +2,16 @@ import { createServiceGetter } from '#common/composables/createServiceGetter';
 import type {
   ICreateKnowledgeInput,
   IGraph,
+  IImportJob,
   IKnowledge,
+  IKnowledgeRuntimeConfig,
   IKnowledgeSetupStatus,
   IQueryResult,
   ISource,
+  ISourceContent,
+  ISourceExportSelection,
+  ISourceFilter,
+  ISourcePage,
   IUpdateKnowledgeInput,
   KnowledgeQueryMode,
   KnowledgeService,
@@ -17,16 +23,33 @@ import type {
 export type {
   ICreateKnowledgeInput,
   IGraph,
+  IImportJob,
   IKnowledge,
   IKnowledgePage,
+  IKnowledgeRuntimeConfig,
   IKnowledgeSetupStatus,
   IndexStatus,
   IQueryResult,
   ISource,
+  ISourceContent,
+  ISourceExportSelection,
+  ISourceFilter,
+  ISourcePage,
   IUpdateKnowledgeInput,
+  SourceIndexStatus,
   SourceType,
 } from '#reins/domain';
 
+/** An object URL plus what it points at; call `revoke()` when done with it. */
+export interface ISourcePreview {
+  url: string;
+  blob: Blob;
+  filename: string;
+  contentType: string;
+  size: number;
+  revoke: () => void;
+}
+
 const EMPTY_SETUP: IKnowledgeSetupStatus = {
   hasChatCredential: false,
   hasEmbeddingCredential: false,
@@ -45,11 +68,13 @@ export const useKnowledgeStore = defineStore('reins-knowledge', () => {
   const enabled = ref<boolean>(false);
   const statusChecked = ref<boolean>(false);
   const setup = ref<IKnowledgeSetupStatus>(EMPTY_SETUP);
+  const runtime = ref<IKnowledgeRuntimeConfig | null>(null);
 
   async function fetchStatus(): Promise<boolean> {
     const status = await getService().status();
     enabled.value = status.enabled;
     setup.value = status.setup;
+    runtime.value = status.runtime;
     statusChecked.value = true;
     return enabled.value;
   }
@@ -114,8 +139,77 @@ export const useKnowledgeStore = defineStore('reins-knowledge', () => {
     return getService().query(id, q, mode, topK);
   }
 
-  function listSources(id: string) {
-    return getService().listSources(id);
+  function listSources(id: string, filter: ISourceFilter): Promise<ISourcePage> {
+    return getService().listSources(id, filter);
+  }
+
+  function listImports(id: string): Promise<IImportJob[]> {
+    return getService().listImports(id);
+  }
+
+  // Fetches the bytes with the Bearer header and hands back an object URL the
+  // preview sheet can iframe / the browser can open. The caller owns the URL.
+  async function previewSource(
+    id: string,
+    sourceId: string,
+  ): Promise<ISourcePreview> {
+    const content: ISourceContent = await getService().fetchSourceContent(
+      id,
+      sourceId,
+      'inline',
+    );
+    const url = URL.createObjectURL(content.blob);
+    return {
+      url,
+      blob: content.blob,
+      filename: content.filename,
+      contentType: content.contentType,
+      size: content.blob.size,
+      revoke: () => URL.revokeObjectURL(url),
+    };
+  }
+
+  async function downloadSource(id: string, sourceId: string): Promise<void> {
+    const content = await getService().fetchSourceContent(
+      id,
+      sourceId,
+      'attachment',
+    );
+    const url = URL.createObjectURL(content.blob);
+    try {
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = content.filename;
+      document.body.appendChild(a);
+      a.click();
+      a.remove();
+    } finally {
+      // Give the click a tick to start the download before pulling the URL.
+      setTimeout(() => URL.revokeObjectURL(url), 1000);
+    }
+  }
+
+  /**
+   * Downloads the selection as a zip. Same blob-and-anchor dance as
+   * downloadSource: the endpoint returns raw bytes rather than the JSON
+   * envelope, and a plain link cannot carry the bearer token.
+   */
+  async function exportSources(
+    id: string,
+    selection: ISourceExportSelection,
+  ): Promise<void> {
+    const content = await getService().exportSources(id, selection);
+    const url = URL.createObjectURL(content.blob);
+    try {
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = content.filename;
+      document.body.appendChild(a);
+      a.click();
+      a.remove();
+    } finally {
+      setTimeout(() => URL.revokeObjectURL(url), 1000);
+    }
   }
 
   function addTextSource(id: string, name: string, content: string) {
@@ -174,6 +268,7 @@ export const useKnowledgeStore = defineStore('reins-knowledge', () => {
     enabled,
     statusChecked,
     setup,
+    runtime,
     fetchStatus,
     fetchAll,
     fetchById,
@@ -184,6 +279,10 @@ export const useKnowledgeStore = defineStore('reins-knowledge', () => {
     startIndex,
     query,
     listSources,
+    listImports,
+    previewSource,
+    downloadSource,
+    exportSources,
     addTextSource,
     addUrlSource,
     addFileSource,
diff --git a/admin/slices/setup/api/data/repositories/api/schemas.gen.ts b/admin/slices/setup/api/data/repositories/api/schemas.gen.ts
index aac95b51..ed59a1c2 100644
--- a/admin/slices/setup/api/data/repositories/api/schemas.gen.ts
+++ b/admin/slices/setup/api/data/repositories/api/schemas.gen.ts
@@ -419,6 +419,23 @@ export const KnowledgeListItemDtoSchema = {
       type: "string",
       nullable: true,
     },
+    sourceCount: {
+      type: "number",
+      description: "Sources attached to this knowledge",
+    },
+    indexedCount: {
+      type: "number",
+      description: "Sources LightRAG confirmed as processed",
+    },
+    failedCount: {
+      type: "number",
+      description: "Sources whose last index run recorded an error",
+    },
+    processingCount: {
+      type: "number",
+      description:
+        "Sources handed to LightRAG that it has not finished processing. A ready knowledge with a non-zero count is searchable but not complete yet; run Index again once the pipeline drains.",
+    },
     instanceState: {
       type: "string",
       enum: ["absent", "starting", "ready", "failed", "stopping"],
@@ -454,6 +471,10 @@ export const KnowledgeListItemDtoSchema = {
     "indexError",
     "indexedAt",
     "indexStartedAt",
+    "sourceCount",
+    "indexedCount",
+    "failedCount",
+    "processingCount",
     "instanceState",
     "instanceError",
     "migrationState",
@@ -668,6 +689,174 @@ export const KnowledgeQueryResultDtoSchema = {
   required: ["answer", "knowledgeId", "complete", "references"],
 } as const;
 
+export const SourceDtoSchema = {
+  type: "object",
+  properties: {
+    id: {
+      type: "string",
+    },
+    knowledgeId: {
+      type: "string",
+    },
+    type: {
+      type: "string",
+      enum: ["file", "url", "text"],
+    },
+    name: {
+      type: "string",
+    },
+    url: {
+      type: "string",
+      nullable: true,
+    },
+    mimeType: {
+      type: "string",
+      nullable: true,
+    },
+    content: {
+      type: "string",
+      nullable: true,
+    },
+    sizeBytes: {
+      type: "number",
+      nullable: true,
+    },
+    indexed: {
+      type: "boolean",
+      description:
+        'True when indexStatus is "indexed". Kept for older callers.',
+    },
+    indexStatus: {
+      type: "string",
+      enum: ["indexed", "pending", "failed"],
+    },
+    indexState: {
+      type: "string",
+      enum: ["queued", "processing", "indexed", "failed"],
+    },
+    indexError: {
+      type: "string",
+      nullable: true,
+      description:
+        "Error from the last index run, null once the source indexes.",
+    },
+    indexedAt: {
+      type: "string",
+      nullable: true,
+    },
+    createdAt: {
+      format: "date-time",
+      type: "string",
+    },
+    updatedAt: {
+      format: "date-time",
+      type: "string",
+    },
+  },
+  required: [
+    "id",
+    "knowledgeId",
+    "type",
+    "name",
+    "url",
+    "mimeType",
+    "content",
+    "sizeBytes",
+    "indexed",
+    "indexStatus",
+    "indexState",
+    "indexError",
+    "indexedAt",
+    "createdAt",
+    "updatedAt",
+  ],
+} as const;
+
+export const SourcePageDtoSchema = {
+  type: "object",
+  properties: {
+    items: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/SourceDto",
+      },
+    },
+    total: {
+      type: "number",
+      description: "Rows matching the filter across all pages",
+    },
+    page: {
+      type: "number",
+    },
+    perPage: {
+      type: "number",
+    },
+  },
+  required: ["items", "total", "page", "perPage"],
+} as const;
+
+export const ImportJobDtoSchema = {
+  type: "object",
+  properties: {
+    id: {
+      type: "string",
+    },
+    knowledgeId: {
+      type: "string",
+    },
+    kind: {
+      type: "string",
+      enum: ["archive"],
+    },
+    status: {
+      type: "string",
+      enum: ["running", "done", "failed"],
+    },
+    detected: {
+      type: "number",
+      description: "Ingestable entries found up front",
+    },
+    added: {
+      type: "number",
+    },
+    skipped: {
+      type: "number",
+      description: "Entries skipped because a source with that name exists",
+    },
+    failed: {
+      type: "number",
+    },
+    errors: {
+      description: 'First failures as "<name>: <reason>", capped',
+      type: "array",
+      items: {
+        type: "string",
+      },
+    },
+    startedAt: {
+      format: "date-time",
+      type: "string",
+    },
+    finishedAt: {
+      type: "string",
+      nullable: true,
+    },
+  },
+  required: [
+    "id",
+    "knowledgeId",
+    "kind",
+    "status",
+    "detected",
+    "added",
+    "skipped",
+    "failed",
+    "errors",
+    "startedAt",
+    "finishedAt",
+  ],
+} as const;
+
 export const CreateSourceDtoSchema = {
   type: "object",
   properties: {
@@ -756,14 +945,19 @@ export const AddFromArchiveResultDtoSchema = {
       type: "number",
       example: 288,
       description:
-        "Number of ingestable files detected in the archive. Import runs in the background; refresh the sources list to watch them appear.",
+        "Number of ingestable files detected in the archive. Import runs in the background; poll GET .../sources/imports for progress.",
     },
     started: {
       type: "boolean",
       example: true,
     },
+    jobId: {
+      type: "string",
+      description:
+        "Id of the background import job (see GET .../sources/imports)",
+    },
   },
-  required: ["detected", "started"],
+  required: ["detected", "started", "jobId"],
 } as const;
 
 export const AgentDtoSchema = {
diff --git a/admin/slices/setup/api/data/repositories/api/sdk.gen.ts b/admin/slices/setup/api/data/repositories/api/sdk.gen.ts
index c43cb65c..ee3e0255 100644
--- a/admin/slices/setup/api/data/repositories/api/sdk.gen.ts
+++ b/admin/slices/setup/api/data/repositories/api/sdk.gen.ts
@@ -58,7 +58,12 @@ import type {
   QueryKnowledgeData,
   QueryKnowledgeResponse,
   GetKnowledgeSourcesData,
+  GetKnowledgeSourcesResponse,
   AddKnowledgeSourceData,
+  GetKnowledgeSourceImportsData,
+  GetKnowledgeSourceImportsResponse,
+  ExportKnowledgeSourcesData,
+  GetKnowledgeSourceContentData,
   ReindexKnowledgeSourceData,
   AddKnowledgeFileSourcesData,
   AddKnowledgeFileSourcesResponse,
@@ -1164,13 +1169,13 @@ export class KnowledgesService {
 
 export class KnowledgeSourcesService {
   /**
-   * List sources
+   * List sources (paginated)
    */
   public static getKnowledgeSources<ThrowOnError extends boolean = false>(
     options: Options<GetKnowledgeSourcesData, ThrowOnError>,
   ) {
     return (options.client ?? _heyApiClient).get<
-      unknown,
+      GetKnowledgeSourcesResponse,
       unknown,
       ThrowOnError
     >({
@@ -1200,6 +1205,57 @@ export class KnowledgeSourcesService {
     });
   }
 
+  /**
+   * Background imports for this knowledge (running and recent)
+   * Progress of archive imports started through from-archive. Jobs are kept in memory for an hour after they finish.
+   */
+  public static getKnowledgeSourceImports<ThrowOnError extends boolean = false>(
+    options: Options<GetKnowledgeSourceImportsData, ThrowOnError>,
+  ) {
+    return (options.client ?? _heyApiClient).get<
+      GetKnowledgeSourceImportsResponse,
+      unknown,
+      ThrowOnError
+    >({
+      url: "/knowledges/{knowledgeId}/sources/imports",
+      ...options,
+    });
+  }
+
+  /**
+   * Download selected sources as one zip
+   * Selection is either an explicit `ids` list or the same filter the list takes, so "select all" travels as a filter rather than every id. File and text sources become entries; url sources are recorded in the `_ranch-export.yaml` manifest, whose extension the archive importer skips so the zip round-trips through from-archive.
+   */
+  public static exportKnowledgeSources<ThrowOnError extends boolean = false>(
+    options: Options<ExportKnowledgeSourcesData, ThrowOnError>,
+  ) {
+    return (options.client ?? _heyApiClient).get<
+      unknown,
+      unknown,
+      ThrowOnError
+    >({
+      url: "/knowledges/{knowledgeId}/sources/export",
+      ...options,
+    });
+  }
+
+  /**
+   * Stream the stored bytes of a file or text source
+   * Streams the file straight from S3 (or the text body from the row). Not available for url sources - open the url itself.
+   */
+  public static getKnowledgeSourceContent<ThrowOnError extends boolean = false>(
+    options: Options<GetKnowledgeSourceContentData, ThrowOnError>,
+  ) {
+    return (options.client ?? _heyApiClient).get<
+      unknown,
+      unknown,
+      ThrowOnError
+    >({
+      url: "/knowledges/{knowledgeId}/sources/{sourceId}/content",
+      ...options,
+    });
+  }
+
   /**
    * Retry indexing a single source
    * Requeues one source and re-ingests it without touching the rest of the batch. Progress is reported through the source own indexState.
@@ -1257,7 +1313,7 @@ export class KnowledgeSourcesService {
 
   /**
    * Bulk-import sources from a zip archive
-   * Accepts a .zip, extracts every ingestable file (pdf, docx, xlsx, txt, html, ...), and creates one file-type source per entry. Upload runs in the background and streams each entry to S3; the response returns immediately with the detected file count. Indexing into LightRAG happens through the normal reindex flow.
+   * Accepts a .zip, extracts every ingestable file (pdf, docx, xlsx, txt, html, ...), and creates one file-type source per entry. Upload runs in the background and streams each entry to S3; the response returns immediately with the detected file count and a job id to poll via GET .../sources/imports. Indexing into LightRAG happens through the normal reindex flow. Max size: KNOWLEDGE_ARCHIVE_MAX_BYTES (default 4 GiB).
    */
   public static addKnowledgeSourcesFromArchive<
     ThrowOnError extends boolean = false,
diff --git a/admin/slices/setup/api/data/repositories/api/types.gen.ts b/admin/slices/setup/api/data/repositories/api/types.gen.ts
index 8338a3dc..a8ea27fe 100644
--- a/admin/slices/setup/api/data/repositories/api/types.gen.ts
+++ b/admin/slices/setup/api/data/repositories/api/types.gen.ts
@@ -183,6 +183,22 @@ export type KnowledgeListItemDto = {
   indexError: string | null;
   indexedAt: string | null;
   indexStartedAt: string | null;
+  /**
+   * Sources attached to this knowledge
+   */
+  sourceCount: number;
+  /**
+   * Sources LightRAG confirmed as processed
+   */
+  indexedCount: number;
+  /**
+   * Sources whose last index run recorded an error
+   */
+  failedCount: number;
+  /**
+   * Sources handed to LightRAG that it has not finished processing. A ready knowledge with a non-zero count is searchable but not complete yet; run Index again once the pipeline drains.
+   */
+  processingCount: number;
   instanceState: "absent" | "starting" | "ready" | "failed" | "stopping";
   instanceError: string | null;
   migrationState: "notStarted" | "inProgress" | "done" | "failed";
@@ -264,6 +280,63 @@ export type KnowledgeQueryResultDto = {
   references: Array<KnowledgeQueryReferenceDto>;
 };
 
+export type SourceDto = {
+  id: string;
+  knowledgeId: string;
+  type: "file" | "url" | "text";
+  name: string;
+  url: string | null;
+  mimeType: string | null;
+  content: string | null;
+  sizeBytes: number | null;
+  /**
+   * True when indexStatus is "indexed". Kept for older callers.
+   */
+  indexed: boolean;
+  indexStatus: "indexed" | "pending" | "failed";
+  indexState: "queued" | "processing" | "indexed" | "failed";
+  /**
+   * Error from the last index run, null once the source indexes.
+   */
+  indexError: string | null;
+  indexedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type SourcePageDto = {
+  items: Array<SourceDto>;
+  /**
+   * Rows matching the filter across all pages
+   */
+  total: number;
+  page: number;
+  perPage: number;
+};
+
+export type ImportJobDto = {
+  id: string;
+  knowledgeId: string;
+  kind: "archive";
+  status: "running" | "done" | "failed";
+  /**
+   * Ingestable entries found up front
+   */
+  detected: number;
+  added: number;
+  /**
+   * Entries skipped because a source with that name exists
+   */
+  skipped: number;
+  failed: number;
+  /**
+   * First failures as "<name>: <reason>", capped
+   */
+  errors: Array<string>;
+  startedAt: string;
+  finishedAt: string | null;
+};
+
 export type CreateSourceDto = {
   type: "file" | "url" | "text";
   name: string;
@@ -302,10 +375,14 @@ export type AddFromSitemapResultDto = {
 
 export type AddFromArchiveResultDto = {
   /**
-   * Number of ingestable files detected in the archive. Import runs in the background; refresh the sources list to watch them appear.
+   * Number of ingestable files detected in the archive. Import runs in the background; poll GET .../sources/imports for progress.
    */
   detected: number;
   started: boolean;
+  /**
+   * Id of the background import job (see GET .../sources/imports)
+   */
+  jobId: string;
 };
 
 export type AgentDto = {
@@ -2127,14 +2204,26 @@ export type GetKnowledgeSourcesData = {
   path: {
     knowledgeId: string;
   };
-  query?: never;
+  query?: {
+    /**
+     * Case-insensitive substring match on the source name
+     */
+    search?: string;
+    status?: "indexed" | "pending" | "failed";
+    type?: "file" | "url" | "text";
+    page?: number;
+    perPage?: number;
+  };
   url: "/knowledges/{knowledgeId}/sources";
 };
 
 export type GetKnowledgeSourcesResponses = {
-  200: unknown;
+  200: SourcePageDto;
 };
 
+export type GetKnowledgeSourcesResponse =
+  GetKnowledgeSourcesResponses[keyof GetKnowledgeSourcesResponses];
+
 export type AddKnowledgeSourceData = {
   body: CreateSourceDto;
   path: {
@@ -2148,6 +2237,65 @@ export type AddKnowledgeSourceResponses = {
   201: unknown;
 };
 
+export type GetKnowledgeSourceImportsData = {
+  body?: never;
+  path: {
+    knowledgeId: string;
+  };
+  query?: never;
+  url: "/knowledges/{knowledgeId}/sources/imports";
+};
+
+export type GetKnowledgeSourceImportsResponses = {
+  200: Array<ImportJobDto>;
+};
+
+export type GetKnowledgeSourceImportsResponse =
+  GetKnowledgeSourceImportsResponses[keyof GetKnowledgeSourceImportsResponses];
+
+export type ExportKnowledgeSourcesData = {
+  body?: never;
+  path: {
+    knowledgeId: string;
+  };
+  query?: {
+    /**
+     * Comma-separated source ids. When present the filter fields are ignored.
+     */
+    ids?: string;
+    /**
+     * Case-insensitive substring match on the source name
+     */
+    search?: string;
+    status?: "indexed" | "pending" | "failed";
+    type?: "file" | "url" | "text";
+  };
+  url: "/knowledges/{knowledgeId}/sources/export";
+};
+
+export type ExportKnowledgeSourcesResponses = {
+  200: unknown;
+};
+
+export type GetKnowledgeSourceContentData = {
+  body?: never;
+  path: {
+    knowledgeId: string;
+    sourceId: string;
+  };
+  query?: {
+    /**
+     * "inline" lets the browser render what it can (pdf, images, text); "attachment" forces a download.
+     */
+    disposition?: "inline" | "attachment";
+  };
+  url: "/knowledges/{knowledgeId}/sources/{sourceId}/content";
+};
+
+export type GetKnowledgeSourceContentResponses = {
+  200: unknown;
+};
+
 export type ReindexKnowledgeSourceData = {
   body?: never;
   path: {
diff --git a/admin/slices/setup/theme/components/ui/sidebar/SidebarInset.vue b/admin/slices/setup/theme/components/ui/sidebar/SidebarInset.vue
index bad9d22f..644c7168 100644
--- a/admin/slices/setup/theme/components/ui/sidebar/SidebarInset.vue
+++ b/admin/slices/setup/theme/components/ui/sidebar/SidebarInset.vue
@@ -11,7 +11,14 @@ const props = defineProps<{
   <main
     data-slot="sidebar-inset"
     :class="cn(
-      'bg-background relative flex w-full flex-1 flex-col border',
+      // `min-w-0` is load-bearing, not decoration. This is a flex item next to
+      // the sidebar, so without it its min-width resolves to `auto` - the
+      // min-content width of whatever is inside. One wide table (or one long
+      // unbreakable error string) then pushes the whole inset past the
+      // viewport, and the page's own `overflow-x-clip` cannot save it because
+      // the blow-out happened in its parent. With `min-w-0` the inset shrinks
+      // and the table scrolls inside its own container instead.
+      'bg-background relative flex w-full min-w-0 flex-1 flex-col border',
       'md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2',
       props.class,
     )"
diff --git a/api/package.json b/api/package.json
index 6eb3b95c..82c6043f 100644
--- a/api/package.json
+++ b/api/package.json
@@ -58,6 +58,7 @@
     "bcrypt": "^6.0.0",
     "class-transformer": "^0.5",
     "class-validator": "^0.14",
+    "multer": "2.1.1",
     "path-to-regexp": "^8.2.0",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1",
@@ -78,6 +79,7 @@
     "@types/bcrypt": "^6.0.0",
     "@types/express": "^5.0.0",
     "@types/jest": "^29.5.14",
+    "@types/multer": "^2",
     "@types/node": "^22.10.7",
     "@types/supertest": "^6.0.2",
     "dotenv-cli": "^11.0.0",
diff --git a/api/prisma/migrations/20260903130000_source_list_index/migration.sql b/api/prisma/migrations/20260903130000_source_list_index/migration.sql
new file mode 100644
index 00000000..a6756e1f
--- /dev/null
+++ b/api/prisma/migrations/20260903130000_source_list_index/migration.sql
@@ -0,0 +1,5 @@
+-- The source list is paged and filtered per knowledge base, oldest first.
+-- Upstream already has every column this slice reads ("indexError",
+-- "indexedAt", "indexState" arrived with 20260827135035); the only thing the
+-- fork's schema declares that this one does not is the index that list walks.
+CREATE INDEX "Source_knowledgeId_createdAt_idx" ON "Source"("knowledgeId", "createdAt");
diff --git a/api/src/slices/aws/s3/s3.repository.ts b/api/src/slices/aws/s3/s3.repository.ts
index 1a0d2398..57fd1113 100644
--- a/api/src/slices/aws/s3/s3.repository.ts
+++ b/api/src/slices/aws/s3/s3.repository.ts
@@ -6,10 +6,12 @@ import {
   PutObjectCommand,
   S3Client,
 } from '@aws-sdk/client-s3';
+import { Readable } from 'stream';
 import { ISettingGateway } from '#/setting/domain';
 import {
   IS3DownloadedFile,
   IS3FileLocation,
+  IS3ObjectStream,
   IS3StoredFile,
   IS3UploadInput,
   S3RepositoryError,
@@ -77,6 +79,39 @@ export class S3Repository {
     return streamToBuffer(res.Body, location);
   }
 
+  /**
+   * Like download() but hands back the body as a Node stream. For serving a
+   * source to a browser: a 300 MB PDF goes straight from S3 to the response
+   * instead of parking in the API pod's 512Mi.
+   */
+  async getObjectStream(location: IS3FileLocation): Promise<IS3ObjectStream> {
+    const client = await this.getClient();
+    this.logger.log(`stream → s3://${location.bucket}/${location.key}`);
+    let res: GetObjectCommandOutput;
+    try {
+      res = await client.send(
+        new GetObjectCommand({
+          Bucket: location.bucket,
+          Key: location.key,
+        }),
+      );
+    } catch (err) {
+      this.fail('stream', location, err);
+    }
+    if (!isAsyncIterableOfBytes(res.Body)) {
+      throw new S3RepositoryError(
+        'S3 stream body is not an async iterable',
+        location.bucket,
+        location.key,
+      );
+    }
+    return {
+      body: res.Body instanceof Readable ? res.Body : Readable.from(res.Body),
+      contentType: res.ContentType ?? null,
+      contentLength: res.ContentLength ?? null,
+    };
+  }
+
   /**
    * Like `download()`, but also returns the stored content type and user
    * metadata. Used when the object is served straight back to a browser and
diff --git a/api/src/slices/aws/s3/s3.types.ts b/api/src/slices/aws/s3/s3.types.ts
index 2ad970c6..daeb831b 100644
--- a/api/src/slices/aws/s3/s3.types.ts
+++ b/api/src/slices/aws/s3/s3.types.ts
@@ -1,3 +1,5 @@
+import { Readable } from 'stream';
+
 export interface IS3FileLocation {
   bucket: string;
   key: string;
@@ -17,6 +19,16 @@ export interface IS3StoredFile extends IS3FileLocation {
   uri: string;
 }
 
+/**
+ * A GetObject body left as a stream so large files can be piped to an HTTP
+ * response without ever being held whole in memory.
+ */
+export interface IS3ObjectStream {
+  body: Readable;
+  contentType: string | null;
+  contentLength: number | null;
+}
+
 /**
  * A downloaded object plus the parts of its S3 response a caller may need to
  * serve it back — the content type it was stored with and any user metadata.
diff --git a/api/src/slices/reins/README.md b/api/src/slices/reins/README.md
new file mode 100644
index 00000000..b591901f
--- /dev/null
+++ b/api/src/slices/reins/README.md
@@ -0,0 +1,143 @@
+# reins (knowledge / RAG)
+
+Ranch stores sources, hands them to LightRAG, and reads the graph back. A few
+things about that boundary are not obvious from the code and have each cost a
+day of debugging, so they are written down here.
+
+## LightRAG has no per-knowledge isolation
+
+`workspaceOf(knowledgeId)` builds a name and every ingest call carries it, but
+**LightRAG ignores it**. A workspace there belongs to the instance, set by the
+`WORKSPACE` env var or `--workspace` at startup; the document and query
+endpoints have no per-request equivalent. For the PostgreSQL storages every row
+lands in the workspace the container was started with, which is `default` when
+nothing is configured.
+
+Consequences, all of them live today:
+
+- Every knowledge base shares one pile of documents, one entity graph, one set
+  of vectors.
+- A query is not scoped to a base. An agent bound to base A can be answered
+  from base B's documents, with no error and nothing visible in the admin.
+- Deleting "all documents" deletes them for every base at once.
+- Citations come back naming documents the base does not contain. Measured on
+  dev: a base holding three CX-3 files was asked about a CX-70 and answered,
+  with all thirteen references drawn from the other base on that instance.
+- Access control by base is fiction. The only way to keep a document out of an
+  agent's answer is not to upload it.
+
+Real isolation means one LightRAG instance per base, each with its own
+`WORKSPACE` against the shared Postgres (the upstream docs describe this
+layout). That is an infrastructure change and a cost decision, not something
+the API can work around. Per-request workspaces are an open feature request
+upstream, not a version we can move to. Until that changes, treat the LightRAG
+index as global and keep one base per environment if answers must not mix.
+
+Two places in the code follow from this and should be reverted together the day
+isolation exists: `knowledge.tool.ts` issues one query for all bound bases
+instead of one per base (asking each returned N copies of one answer and paid
+for N), and the admin knowledge list warns as soon as a second base appears.
+A design note weighing the alternatives lives in
+`docs/superpowers/specs/2026-08-24-knowledge-isolation-design.md`.
+
+## Indexing costs about an hour per megabyte
+
+Ingest is not chunk-and-embed. Every chunk goes through the LLM twice: once to
+extract entities and relations, then again in the merge pass whenever an entity
+accumulated enough descriptions to need summarising. Both phases scale with
+chunk count, and chunk count follows the length of the text, not the number of
+files.
+
+Measured on the dev cluster (Haiku on Bedrock, `max_async = 4`):
+
+| | |
+|---|---|
+| 1 MB of markdown | 217 chunks |
+| extraction | ~20 min |
+| entity merge | ~35 min |
+| a 3 KB order form | 1 chunk, under a minute |
+
+So a single owner's manual outlasts a hundred order forms, and a 28 MB
+documentation set is a full day of pipeline time. Two things follow. Splitting
+a large PDF into smaller files does not make it faster - the text volume is
+unchanged, and `MAX_PARALLEL_INSERT` caps document-level concurrency anyway.
+And an index run's wait (`indexBudgetMs`) is a bound, not a promise: documents
+routinely outlive the run that submitted them, which is why the row keeps its
+resume handle and `IndexReconcileService` confirms them afterwards.
+
+If indexing has to go faster, the levers in order of effect are LLM
+concurrency, then chunk size (fewer, larger chunks means fewer calls in both
+phases, at the cost of graph detail), then not graph-indexing bulky reference
+material at all.
+
+**Check that a concurrency setting actually took effect.** The dev instance ran
+at `max_async = 4`, the default, while its manifest set `MAX_ASYNC_LLM=8`;
+`MAX_PARALLEL_INSERT` from the same manifest did apply. Upstream renamed
+`MAX_ASYNC` to `MAX_ASYNC_LLM` and kept the old name as a deprecated alias, so
+an image from before that rename honours only `MAX_ASYNC` and silently ignores
+the new one - which is the likeliest explanation, though it was not confirmed
+against the running image. Setting both names is the version-agnostic fix.
+
+Either way, trust `GET /health` over the manifest: it reports the values in
+force. The manifest itself is not in this repo - the Mazda cluster's LightRAG is
+an ArgoCD app (`ranch-lightrag`) from `connectsolutions/mazda-ai-gitops`, path
+`helm/ranch-lightrag`.
+
+## Changing the extraction model requires clearing the LLM cache
+
+LightRAG caches every extraction and summary response in `lightrag_llm_cache`,
+keyed by the content of the chunk and the prompt. **The model is not part of
+that key.** Swap `LLM_MODEL`, re-index the same documents, and LightRAG serves
+the previous model's answers straight from cache: the run takes hours, costs
+money on the handful of uncached chunks, and rebuilds a graph identical to the
+one you were trying to replace. Nothing in the logs says "cache hit", and the
+`LLM output format error` warnings reappear because malformed cached output is
+re-parsed on every rebuild.
+
+The `DELETE /documents` endpoint does not clear this table. When changing the
+extraction model, in order:
+
+```sql
+TRUNCATE lightrag_llm_cache;
+```
+
+then clear the documents, then re-index. Verify the run is real before waiting
+on it - fresh rows should appear for the current hour:
+
+```sql
+SELECT date_trunc('hour', create_time) AS hour, count(*)
+FROM lightrag_llm_cache WHERE cache_type = 'extract' GROUP BY 1 ORDER BY 1;
+```
+
+The same applies to the embedding model, with a bigger blast radius: embedding
+dimension is fixed when the vector tables are created, so changing it needs the
+vector storage recreated, not just the cache emptied.
+
+## Picking an extraction model
+
+Entity and relation extraction asks the model for records in a fixed field
+layout. Models that do not hold that layout produce records that fail to parse,
+which is logged as `LLM output format error` and drops the record silently -
+relations suffer worst, because a relation needs all five fields while an
+entity survives on four.
+
+Measured on the same 1181-chunk corpus:
+
+| model | relations per chunk | format errors |
+|---|---|---|
+| `amazon.nova-lite-v1:0` | 12.6 | ~1 per 3 chunks |
+| `amazon.nova-pro-v1:0` | 7.6 | ~1 per 3 chunks |
+| `us.anthropic.claude-haiku-4-5-...` | 23.0 | 0 in ~2000 calls |
+
+Neither Nova model is usable for this. If a model has to be evaluated, index
+one document dense with short capitalised terms and punctuation inside names -
+tables of UI gestures and part names are what broke the Nova models - and count
+the warnings:
+
+```bash
+kubectl -n <ns> logs deploy/lightrag --since=10m | grep -c "LLM output format error"
+```
+
+Note that this counter reads the *parse* step, so it also fires when cached
+output from an older model is re-parsed. Clear the cache first or the number
+describes the previous model.
diff --git a/api/src/slices/reins/knowledge/data/knowledge.gateway.ts b/api/src/slices/reins/knowledge/data/knowledge.gateway.ts
index 09efe0e8..c3e4ae92 100644
--- a/api/src/slices/reins/knowledge/data/knowledge.gateway.ts
+++ b/api/src/slices/reins/knowledge/data/knowledge.gateway.ts
@@ -4,7 +4,7 @@ import { PrismaService } from '#/setup/prisma/prisma.service';
 import { ILightragClient } from '../../lightrag/domain/lightrag.client';
 import { IKnowledgeGateway } from '../domain/knowledge.gateway';
 import {
-  IKnowledgeData,
+  IKnowledgeRecord,
   ICreateKnowledgeData,
   IUpdateKnowledgeData,
   IFilterKnowledgeParams,
@@ -32,7 +32,7 @@ export class KnowledgeGateway extends IKnowledgeGateway {
     super();
   }
 
-  async findAll(): Promise<IKnowledgeData[]> {
+  async findAll(): Promise<IKnowledgeRecord[]> {
     const records = await this.prisma.knowledge.findMany({
       orderBy: { createdAt: 'desc' },
     });
@@ -98,24 +98,31 @@ export class KnowledgeGateway extends IKnowledgeGateway {
     }
 
     return {
-      items: records.map((r) => ({
-        ...this.mapper.toEntity(r),
-        indexStatus: deriveIndexStatus(statesOf.get(r.id) ?? []),
-        sourcesCount: r._count.sources,
-        totalSizeBytes: sizeOf.get(r.id) ?? 0,
-      })),
+      items: records.map((r) => {
+        const states = statesOf.get(r.id) ?? [];
+        return {
+          ...this.mapper.toEntity(r),
+          indexStatus: deriveIndexStatus(states),
+          sourceCount: r._count.sources,
+          indexedCount: states.filter((s) => s === 'indexed').length,
+          failedCount: states.filter((s) => s === 'failed').length,
+          processingCount: states.filter((s) => s === 'processing').length,
+          sourcesCount: r._count.sources,
+          totalSizeBytes: sizeOf.get(r.id) ?? 0,
+        };
+      }),
       total,
       page,
       perPage,
     };
   }
 
-  async findById(id: string): Promise<IKnowledgeData | null> {
+  async findById(id: string): Promise<IKnowledgeRecord | null> {
     const record = await this.prisma.knowledge.findUnique({ where: { id } });
     return record ? this.mapper.toEntity(record) : null;
   }
 
-  async findExistingByIds(ids: string[]): Promise<IKnowledgeData[]> {
+  async findExistingByIds(ids: string[]): Promise<IKnowledgeRecord[]> {
     if (ids.length === 0) return [];
     const records = await this.prisma.knowledge.findMany({
       where: { id: { in: ids } },
@@ -123,7 +130,7 @@ export class KnowledgeGateway extends IKnowledgeGateway {
     return records.map((r) => this.mapper.toEntity(r));
   }
 
-  async create(data: ICreateKnowledgeData): Promise<IKnowledgeData> {
+  async create(data: ICreateKnowledgeData): Promise<IKnowledgeRecord> {
     const created = await this.prisma.$transaction(async (tx) => {
       const initial = await tx.knowledge.create({
         data: this.mapper.toCreate(data),
@@ -139,7 +146,7 @@ export class KnowledgeGateway extends IKnowledgeGateway {
   async update(
     id: string,
     data: IUpdateKnowledgeData,
-  ): Promise<IKnowledgeData> {
+  ): Promise<IKnowledgeRecord> {
     const record = await this.prisma.knowledge.update({
       where: { id },
       data: {
@@ -155,7 +162,7 @@ export class KnowledgeGateway extends IKnowledgeGateway {
   async updateIndexState(
     id: string,
     patch: IIndexStatePatch,
-  ): Promise<IKnowledgeData> {
+  ): Promise<IKnowledgeRecord> {
     const record = await this.prisma.knowledge.update({
       where: { id },
       data: {
@@ -173,7 +180,7 @@ export class KnowledgeGateway extends IKnowledgeGateway {
   async updateInstanceState(
     id: string,
     patch: IInstanceStatePatch,
-  ): Promise<IKnowledgeData> {
+  ): Promise<IKnowledgeRecord> {
     const record = await this.prisma.knowledge.update({
       where: { id },
       data: {
@@ -192,7 +199,7 @@ export class KnowledgeGateway extends IKnowledgeGateway {
   async updateMigrationState(
     id: string,
     state: MigrationStateTypes,
-  ): Promise<IKnowledgeData> {
+  ): Promise<IKnowledgeRecord> {
     const record = await this.prisma.knowledge.update({
       where: { id },
       data: { migrationState: state },
diff --git a/api/src/slices/reins/knowledge/data/knowledge.mapper.ts b/api/src/slices/reins/knowledge/data/knowledge.mapper.ts
index 0f1d7b7f..f8b50dcd 100644
--- a/api/src/slices/reins/knowledge/data/knowledge.mapper.ts
+++ b/api/src/slices/reins/knowledge/data/knowledge.mapper.ts
@@ -1,7 +1,7 @@
 import { Injectable } from '@nestjs/common';
 import type { Knowledge as PrismaKnowledge, Prisma } from '@prisma/client';
 import {
-  IKnowledgeData,
+  IKnowledgeRecord,
   ICreateKnowledgeData,
   IndexStatusTypes,
   InstanceStateTypes,
@@ -50,7 +50,7 @@ function parseMigrationState(value: string): MigrationStateTypes {
 
 @Injectable()
 export class KnowledgeMapper {
-  toEntity(record: PrismaKnowledge): IKnowledgeData {
+  toEntity(record: PrismaKnowledge): IKnowledgeRecord {
     return {
       id: record.id,
       name: record.name,
diff --git a/api/src/slices/reins/knowledge/domain/indexReconcile.service.ts b/api/src/slices/reins/knowledge/domain/indexReconcile.service.ts
new file mode 100644
index 00000000..4a9695c7
--- /dev/null
+++ b/api/src/slices/reins/knowledge/domain/indexReconcile.service.ts
@@ -0,0 +1,149 @@
+import {
+  Injectable,
+  Logger,
+  OnModuleDestroy,
+  OnModuleInit,
+} from '@nestjs/common';
+import { SourceService } from '../../source/domain/source.service';
+import { ILightragClient } from '../../lightrag/domain/lightrag.client';
+
+const DEFAULT_INTERVAL_SEC = 60;
+
+/**
+ * How long to leave an idle pipeline alone after nudging it. A nudge only
+ * re-queues work LightRAG already holds, so the cost of one is a request; the
+ * cooldown exists so a genuinely unprocessable backlog cannot turn every
+ * reconcile pass into a restart.
+ */
+const RESTART_COOLDOWN_MS = 10 * 60 * 1000;
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Confirms documents LightRAG finished after the index run that submitted them
+ * had already stopped waiting.
+ *
+ * Why this exists: an index run waits a bounded time (see indexBudgetMs) and
+ * then leaves whatever is still moving to be picked up later. On real content
+ * that is the normal case, not the exception - a 1 MB manual is 217 chunks and
+ * spends the better part of an hour in the pipeline, long after any run gave
+ * up on it. Until something writes the confirmation down, the base keeps
+ * reporting "2 of 3" and the only way to move it is for a person to press
+ * Index again and hope the timing works out.
+ *
+ * So a timer does it instead. Each pass asks LightRAG about the handles it
+ * already stored, stamps the ones that came back processed, and leaves the
+ * rest alone. It never uploads anything - re-sending a document is the Index
+ * action's job - so a pass costs a couple of status reads and cannot start
+ * work that costs money.
+ *
+ * Ranch has no scheduler facility, so this is a plain `setInterval` in an
+ * OnModuleInit service, the same pattern as chatSync.service and
+ * agentStatus.service's driftTimer.
+ */
+@Injectable()
+export class IndexReconcileService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(IndexReconcileService.name);
+  private timer?: ReturnType<typeof setInterval>;
+  private running = false;
+  private lastRestartAt = 0;
+
+  constructor(
+    private readonly sources: SourceService,
+    private readonly lightrag: ILightragClient,
+  ) {}
+
+  onModuleInit(): void {
+    const raw = process.env.KNOWLEDGE_RECONCILE_INTERVAL_SEC;
+    const sec =
+      raw === undefined || raw.trim() === ''
+        ? DEFAULT_INTERVAL_SEC
+        : Number(raw);
+    if (!Number.isFinite(sec) || sec <= 0) {
+      this.logger.log('index reconcile disabled');
+      return;
+    }
+    this.logger.log(`index reconcile enabled: every ${sec}s`);
+    this.timer = setInterval(() => {
+      void this.reconcile().catch((err) =>
+        this.logger.error(`scheduled reconcile failed: ${errorMessage(err)}`),
+      );
+    }, sec * 1000);
+    // Nothing here should keep the process alive on its own.
+    this.timer.unref?.();
+  }
+
+  onModuleDestroy(): void {
+    if (this.timer) clearInterval(this.timer);
+  }
+
+  /**
+   * One pass. Returns how many sources became searchable, so a caller (or a
+   * test) can tell a productive pass from a quiet one.
+   */
+  async reconcile(): Promise<number> {
+    // Passes must not overlap: LightRAG's status reads are slow enough on a
+    // large base that a 60 s timer can fire again mid-pass, and two passes
+    // would ask the same questions and write the same rows.
+    if (this.running) return 0;
+    this.running = true;
+    try {
+      const pending = await this.sources.findUnconfirmed();
+      if (pending.length === 0) return 0;
+
+      const outcomes = await this.sources.confirmProcessed(pending);
+      const confirmed = outcomes.filter((o) => o.indexed).length;
+      const stillMoving = outcomes.filter((o) => o.status === 'pending').length;
+
+      if (confirmed > 0) {
+        this.logger.log(
+          `reconcile confirmed ${confirmed} source(s); ${stillMoving} still in the pipeline`,
+        );
+      }
+
+      await this.restartIfStalled(stillMoving);
+      return confirmed;
+    } finally {
+      this.running = false;
+    }
+  }
+
+  /**
+   * Documents waiting on a pipeline that is not running.
+   *
+   * LightRAG keeps its queue in the process and the document statuses in its
+   * database, so the two part company the moment that process is replaced: the
+   * rows still say PENDING, the queue that would have drained them is gone, and
+   * nothing on either side notices. On 2026-09-01 a pod move at 15:27 left 271
+   * documents in exactly that state and they sat there until a person went
+   * looking, because every component was behaving correctly - LightRAG had
+   * nothing queued, and this reconciler was politely waiting for documents no
+   * one would ever process.
+   *
+   * "Still moving" plus "not busy" is that state, and re-queueing is the whole
+   * remedy. Failures are swallowed: recovery is a bonus on top of a reconcile
+   * pass, never a reason to lose one.
+   */
+  private async restartIfStalled(stillMoving: number): Promise<void> {
+    if (stillMoving === 0) return;
+    if (Date.now() - this.lastRestartAt < RESTART_COOLDOWN_MS) return;
+
+    try {
+      const status = await this.lightrag.getPipelineStatus();
+      if (status.busy) return;
+
+      // Stamped before the call, not after: a restart that throws half-way may
+      // still have started the pipeline, and retrying it every minute is worse
+      // than waiting out one cooldown.
+      this.lastRestartAt = Date.now();
+      await this.lightrag.restartPipeline();
+      this.logger.warn(
+        `pipeline idle with ${stillMoving} source(s) waiting; re-queued the backlog`,
+      );
+    } catch (err) {
+      this.logger.error(`pipeline restart failed: ${errorMessage(err)}`);
+    }
+  }
+}
diff --git a/api/src/slices/reins/knowledge/domain/indexReconcile.spec.ts b/api/src/slices/reins/knowledge/domain/indexReconcile.spec.ts
new file mode 100644
index 00000000..96363d82
--- /dev/null
+++ b/api/src/slices/reins/knowledge/domain/indexReconcile.spec.ts
@@ -0,0 +1,215 @@
+import { IndexReconcileService } from './indexReconcile.service';
+import { SourceService } from '../../source/domain/source.service';
+import { ISourceData, ISourceIndexOutcome } from '../../source/domain';
+import { ILightragClient } from '../../lightrag/domain/lightrag.client';
+import { IPipelineStatus } from '../../lightrag/domain/lightrag.types';
+
+function makeSource(id: string): ISourceData {
+  return {
+    id,
+    knowledgeId: 'knowledge-1',
+    type: 'file',
+    name: `${id}.md`,
+    url: 's3://bucket/key',
+    mimeType: 'text/markdown',
+    content: null,
+    sizeBytes: 1024,
+    indexed: false,
+    indexStatus: 'pending',
+    indexState: 'queued',
+    indexError: null,
+    indexedAt: null,
+    createdAt: new Date(0),
+    updatedAt: new Date(0),
+  };
+}
+
+function confirmed(id: string): ISourceIndexOutcome {
+  return {
+    sourceId: id,
+    name: `${id}.md`,
+    status: 'indexed',
+    indexed: true,
+    error: null,
+  };
+}
+
+function moving(id: string): ISourceIndexOutcome {
+  return {
+    sourceId: id,
+    name: `${id}.md`,
+    status: 'pending',
+    indexed: false,
+    error: 'still in LightRAG pipeline',
+  };
+}
+
+function pipeline(busy: boolean): IPipelineStatus {
+  return { busy, docs: 0, currentBatch: 0, latestMessage: '' };
+}
+
+function makeService(
+  stub: Partial<SourceService>,
+  lightrag: Partial<ILightragClient> = {
+    // Busy by default so the existing cases exercise reconciliation only. The
+    // restart path has its own tests below.
+    getPipelineStatus: jest.fn(() => Promise.resolve(pipeline(true))),
+    restartPipeline: jest.fn(() => Promise.resolve()),
+  },
+): IndexReconcileService {
+  return new IndexReconcileService(
+    stub as SourceService,
+    lightrag as ILightragClient,
+  );
+}
+
+describe('IndexReconcileService.reconcile', () => {
+  it('does nothing when no source is waiting on LightRAG', async () => {
+    const confirmProcessed = jest.fn();
+    const service = makeService({
+      findUnconfirmed: jest.fn(() => Promise.resolve([])),
+      confirmProcessed,
+    });
+
+    expect(await service.reconcile()).toBe(0);
+    // The quiet case is the common one, so it must not cost a LightRAG call.
+    expect(confirmProcessed).not.toHaveBeenCalled();
+  });
+
+  it('reports how many sources LightRAG finished since the last pass', async () => {
+    const service = makeService({
+      findUnconfirmed: jest.fn(() =>
+        Promise.resolve([makeSource('src-1'), makeSource('src-2')]),
+      ),
+      confirmProcessed: jest.fn(() =>
+        Promise.resolve([confirmed('src-1'), moving('src-2')]),
+      ),
+    });
+
+    expect(await service.reconcile()).toBe(1);
+  });
+
+  it('does not start a second pass while one is still running', async () => {
+    let release: (() => void) | undefined;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const findUnconfirmed = jest.fn(() =>
+      gate.then(() => [makeSource('src-1')]),
+    );
+    const service = makeService({
+      findUnconfirmed,
+      confirmProcessed: jest.fn(() => Promise.resolve([confirmed('src-1')])),
+    });
+
+    const first = service.reconcile();
+    // Fires while the first pass is still awaiting: on a large base a pass
+    // outlives the interval, and two passes would duplicate every status read.
+    const second = await service.reconcile();
+    release?.();
+
+    expect(second).toBe(0);
+    expect(await first).toBe(1);
+    expect(findUnconfirmed).toHaveBeenCalledTimes(1);
+  });
+
+  it('releases the lock when a pass throws, so it recovers next tick', async () => {
+    const findUnconfirmed = jest
+      .fn()
+      .mockRejectedValueOnce(new Error('lightrag unreachable'))
+      .mockResolvedValueOnce([]);
+    const service = makeService({ findUnconfirmed });
+
+    await expect(service.reconcile()).rejects.toThrow('lightrag unreachable');
+    expect(await service.reconcile()).toBe(0);
+    expect(findUnconfirmed).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('IndexReconcileService: recovering a stalled pipeline', () => {
+  function waiting(stub: Partial<ILightragClient>): IndexReconcileService {
+    return makeService(
+      {
+        findUnconfirmed: jest.fn(() => Promise.resolve([makeSource('src-1')])),
+        confirmProcessed: jest.fn(() => Promise.resolve([moving('src-1')])),
+      },
+      stub,
+    );
+  }
+
+  it('re-queues the backlog when documents wait on a pipeline that is idle', async () => {
+    // The 2026-09-01 outage exactly: LightRAG's in-process queue died with a
+    // replaced pod, its database still said PENDING, and nothing on either side
+    // was going to notice.
+    const restartPipeline = jest.fn(() => Promise.resolve());
+    const service = waiting({
+      getPipelineStatus: jest.fn(() => Promise.resolve(pipeline(false))),
+      restartPipeline,
+    });
+
+    await service.reconcile();
+
+    expect(restartPipeline).toHaveBeenCalledTimes(1);
+  });
+
+  it('leaves a working pipeline alone', async () => {
+    const restartPipeline = jest.fn(() => Promise.resolve());
+    const service = waiting({
+      getPipelineStatus: jest.fn(() => Promise.resolve(pipeline(true))),
+      restartPipeline,
+    });
+
+    await service.reconcile();
+
+    expect(restartPipeline).not.toHaveBeenCalled();
+  });
+
+  it('does not even ask when nothing is waiting', async () => {
+    const getPipelineStatus = jest.fn(() => Promise.resolve(pipeline(false)));
+    const service = makeService(
+      {
+        findUnconfirmed: jest.fn(() => Promise.resolve([makeSource('src-1')])),
+        confirmProcessed: jest.fn(() => Promise.resolve([confirmed('src-1')])),
+      },
+      { getPipelineStatus, restartPipeline: jest.fn() },
+    );
+
+    await service.reconcile();
+
+    expect(getPipelineStatus).not.toHaveBeenCalled();
+  });
+
+  it('nudges once and then holds off, so a stuck backlog cannot become a loop', async () => {
+    const restartPipeline = jest.fn(() => Promise.resolve());
+    const service = waiting({
+      getPipelineStatus: jest.fn(() => Promise.resolve(pipeline(false))),
+      restartPipeline,
+    });
+
+    await service.reconcile();
+    await service.reconcile();
+    await service.reconcile();
+
+    expect(restartPipeline).toHaveBeenCalledTimes(1);
+  });
+
+  it('still reports its confirmations when the restart call fails', async () => {
+    const service = makeService(
+      {
+        findUnconfirmed: jest.fn(() =>
+          Promise.resolve([makeSource('src-1'), makeSource('src-2')]),
+        ),
+        confirmProcessed: jest.fn(() =>
+          Promise.resolve([confirmed('src-1'), moving('src-2')]),
+        ),
+      },
+      {
+        getPipelineStatus: jest.fn(() => Promise.resolve(pipeline(false))),
+        restartPipeline: jest.fn(() => Promise.reject(new Error('502'))),
+      },
+    );
+
+    // Recovery rides along with a reconcile pass; it must never cost one.
+    expect(await service.reconcile()).toBe(1);
+  });
+});
diff --git a/api/src/slices/reins/knowledge/domain/knowledge.gateway.ts b/api/src/slices/reins/knowledge/domain/knowledge.gateway.ts
index 46d097bc..cacc6fea 100644
--- a/api/src/slices/reins/knowledge/domain/knowledge.gateway.ts
+++ b/api/src/slices/reins/knowledge/domain/knowledge.gateway.ts
@@ -1,5 +1,5 @@
 import {
-  IKnowledgeData,
+  IKnowledgeRecord,
   ICreateKnowledgeData,
   IUpdateKnowledgeData,
   IFilterKnowledgeParams,
@@ -14,27 +14,27 @@ import {
 } from './knowledge.types';
 
 export abstract class IKnowledgeGateway {
-  abstract findAll(): Promise<IKnowledgeData[]>;
+  abstract findAll(): Promise<IKnowledgeRecord[]>;
   abstract findPage(params: IFilterKnowledgeParams): Promise<IKnowledgePage>;
-  abstract findById(id: string): Promise<IKnowledgeData | null>;
-  abstract findExistingByIds(ids: string[]): Promise<IKnowledgeData[]>;
-  abstract create(data: ICreateKnowledgeData): Promise<IKnowledgeData>;
+  abstract findById(id: string): Promise<IKnowledgeRecord | null>;
+  abstract findExistingByIds(ids: string[]): Promise<IKnowledgeRecord[]>;
+  abstract create(data: ICreateKnowledgeData): Promise<IKnowledgeRecord>;
   abstract update(
     id: string,
     data: IUpdateKnowledgeData,
-  ): Promise<IKnowledgeData>;
+  ): Promise<IKnowledgeRecord>;
   abstract updateIndexState(
     id: string,
     patch: IIndexStatePatch,
-  ): Promise<IKnowledgeData>;
+  ): Promise<IKnowledgeRecord>;
   abstract updateInstanceState(
     id: string,
     patch: IInstanceStatePatch,
-  ): Promise<IKnowledgeData>;
+  ): Promise<IKnowledgeRecord>;
   abstract updateMigrationState(
     id: string,
     state: MigrationStateTypes,
-  ): Promise<IKnowledgeData>;
+  ): Promise<IKnowledgeRecord>;
   abstract delete(id: string): Promise<void>;
 
   abstract searchKnowledge(
diff --git a/api/src/slices/reins/knowledge/domain/knowledge.service.ts b/api/src/slices/reins/knowledge/domain/knowledge.service.ts
index 602e73a0..d5edf35f 100644
--- a/api/src/slices/reins/knowledge/domain/knowledge.service.ts
+++ b/api/src/slices/reins/knowledge/domain/knowledge.service.ts
@@ -3,11 +3,13 @@ import {
   Logger,
   NotFoundException,
   OnApplicationBootstrap,
+  OnModuleInit,
   ServiceUnavailableException,
 } from '@nestjs/common';
 import { IKnowledgeGateway } from './knowledge.gateway';
 import {
   IKnowledgeData,
+  IKnowledgeRecord,
   ICreateKnowledgeData,
   IndexStatusTypes,
   IUpdateKnowledgeData,
@@ -22,13 +24,12 @@ import {
   IGraphData,
 } from './knowledge.types';
 import { SourceService } from '../../source/domain/source.service';
-import { ISourceData } from '../../source/domain/source.types';
+import { ISourceCounts, ISourceData } from '../../source/domain/source.types';
+import { staleIndexAfterMs } from '../../source/domain/indexBudget';
 import { deriveIndexStatus } from './knowledge.status';
 import { IInstanceGateway } from '../../instance/domain/instance.gateway';
 import { IKnowledgeConfigGateway } from '../../config/domain/knowledgeConfig.gateway';
 
-const STALE_INDEX_AFTER_MS = 10 * 60 * 1000;
-
 const LABELS_DEFAULT_LIMIT = 50;
 const LABELS_MAX_LIMIT = 200;
 
@@ -36,6 +37,13 @@ function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+const NO_SOURCES: ISourceCounts = {
+  total: 0,
+  indexed: 0,
+  failed: 0,
+  processing: 0,
+};
+
 /**
  * The retrieval service's canned response when retrieval found no context at
  * all — the one case it does not generate. Detecting it lets the product say
@@ -71,7 +79,7 @@ export function resolveReference(
 }
 
 @Injectable()
-export class KnowledgeService implements OnApplicationBootstrap {
+export class KnowledgeService implements OnModuleInit, OnApplicationBootstrap {
   private readonly logger = new Logger(KnowledgeService.name);
   private readonly inflightIndexing = new Map<string, Promise<void>>();
 
@@ -86,8 +94,46 @@ export class KnowledgeService implements OnApplicationBootstrap {
     void this.reconcileInstances();
   }
 
-  list(): Promise<IKnowledgeData[]> {
-    return this.gateway.findAll();
+  /**
+   * An index run lives in this process and nowhere else, so a deploy or a
+   * crash takes it with it while the row keeps saying `indexing`. Nothing ever
+   * cleared that, and since the admin disables the Index button on `indexing`,
+   * the base became unindexable until someone called the API by hand.
+   *
+   * Whatever this process finds in `indexing` at startup therefore belongs to
+   * a run that no longer exists: release it. LightRAG keeps working on
+   * whatever was already handed to it, and the sources keep their resume
+   * handles, so the next run continues rather than starting over.
+   */
+  async onModuleInit(): Promise<void> {
+    let released = 0;
+    try {
+      const records = await this.gateway.findAll();
+      for (const record of records) {
+        if (record.indexStatus !== 'indexing') continue;
+        await this.gateway.updateIndexState(record.id, {
+          indexStatus: record.indexedAt ? 'ready' : 'idle',
+        });
+        released += 1;
+      }
+    } catch (err) {
+      // Never block API startup over this: a stuck badge is survivable, a
+      // boot loop is not.
+      this.logger.warn(
+        `could not release abandoned index runs: ${errorMessage(err)}`,
+      );
+      return;
+    }
+    if (released > 0) {
+      this.logger.warn(
+        `released ${released} knowledge base(s) left in 'indexing' by a previous process`,
+      );
+    }
+  }
+
+  async list(): Promise<IKnowledgeData[]> {
+    const records = await this.gateway.findAll();
+    return this.withCounts(records);
   }
 
   listPage(params: IFilterKnowledgeParams): Promise<IKnowledgePage> {
@@ -97,7 +143,8 @@ export class KnowledgeService implements OnApplicationBootstrap {
   async get(id: string): Promise<IKnowledgeData> {
     const k = await this.gateway.findById(id);
     if (!k) throw new NotFoundException(`Knowledge ${id} not found`);
-    return k;
+    const [withCounts] = await this.withCounts([k]);
+    return withCounts;
   }
 
   /** The read the console sees: indexStatus derived from the sources. */
@@ -124,12 +171,50 @@ export class KnowledgeService implements OnApplicationBootstrap {
     id: string,
     data: IUpdateKnowledgeData,
   ): Promise<IKnowledgeData> {
-    await this.get(id);
-    return this.gateway.update(id, data);
+    await this.requireRecord(id);
+    const updated = await this.gateway.update(id, data);
+    const [withCounts] = await this.withCounts([updated]);
+    return withCounts;
+  }
+
+  /** Existence check without the counts round trip that get() adds. */
+  private async requireRecord(id: string): Promise<IKnowledgeRecord> {
+    const k = await this.gateway.findById(id);
+    if (!k) throw new NotFoundException(`Knowledge ${id} not found`);
+    return k;
+  }
+
+  /**
+   * Source progress is owned by the source slice; ask it once for the whole
+   * batch so listing N knowledges costs one round of counts, not N.
+   */
+  private async withCounts(
+    records: IKnowledgeRecord[],
+  ): Promise<IKnowledgeData[]> {
+    if (records.length === 0) return [];
+    const counts = await this.sources.countByKnowledgeIds(
+      records.map((r) => r.id),
+    );
+    return records.map((r) =>
+      this.attachCounts(r, counts.get(r.id) ?? NO_SOURCES),
+    );
+  }
+
+  private attachCounts(
+    record: IKnowledgeRecord,
+    counts: ISourceCounts,
+  ): IKnowledgeData {
+    return {
+      ...record,
+      sourceCount: counts.total,
+      indexedCount: counts.indexed,
+      failedCount: counts.failed,
+      processingCount: counts.processing,
+    };
   }
 
   async delete(id: string): Promise<void> {
-    const record = await this.get(id);
+    const record = await this.requireRecord(id);
     // Order matters: the area's content is removed while the instance can
     // still serve the delete calls, then the instance goes.
     try {
@@ -159,7 +244,7 @@ export class KnowledgeService implements OnApplicationBootstrap {
    * start-up reconciliation and the migration — provision itself is
    * idempotent, so none of them can double-provision.
    */
-  async provisionInstance(k: IKnowledgeData): Promise<void> {
+  async provisionInstance(k: IKnowledgeRecord): Promise<void> {
     try {
       const status = await this.instances.provision({
         knowledgeId: k.id,
@@ -222,11 +307,16 @@ export class KnowledgeService implements OnApplicationBootstrap {
   }
 
   async startIndex(knowledgeId: string): Promise<void> {
-    const k = await this.get(knowledgeId);
+    const k = await this.requireRecord(knowledgeId);
 
     if (k.indexStatus === 'indexing' && k.indexStartedAt) {
       const ageMs = Date.now() - k.indexStartedAt.getTime();
-      if (ageMs < STALE_INDEX_AFTER_MS) {
+      // Scaled to how much text the base holds, not how many rows: a single
+      // 1 MB manual outlasts a hundred order forms, and offering a restart
+      // while the first run is still waiting would set two runs fighting over
+      // the same sources.
+      const sources = await this.sources.findByKnowledge(knowledgeId);
+      if (ageMs < staleIndexAfterMs(sources)) {
         throw new Error(
           `Knowledge ${knowledgeId} already indexing (started ${Math.round(ageMs / 1000)}s ago)`,
         );
@@ -267,10 +357,15 @@ export class KnowledgeService implements OnApplicationBootstrap {
     const complete = k.migrationState === 'done';
 
     // An empty base does not get to generate an answer from no context —
-    // and the retrieval service is not even asked (FR-003).
+    // and the retrieval service is not even asked (FR-003). Only once the
+    // base is isolated, though: pre-migration bases share one index, and
+    // their rows can lag behind what that index actually holds (a stamp
+    // lost to an interrupted run). Vetoing on the rows there would silence
+    // content LightRAG still answers with, so until 'done' the query goes
+    // through exactly as it did before isolation shipped.
     const sources = await this.sources.findByKnowledge(knowledgeId);
     const hasIndexed = sources.some((s) => s.indexState === 'indexed');
-    if (!hasIndexed) {
+    if (complete && !hasIndexed) {
       return {
         answer: null,
         reason: 'no_relevant_content',
@@ -351,60 +446,52 @@ export class KnowledgeService implements OnApplicationBootstrap {
   private async runIndex(knowledgeId: string): Promise<void> {
     try {
       const sources = await this.sources.findByKnowledge(knowledgeId);
-      const failures: { sourceId: string; name: string; error: string }[] = [];
-      const previouslyIndexed = sources.filter(
-        (s) => s.indexState === 'indexed',
-      ).length;
-      let newlyIndexed = 0;
-      for (const source of sources) {
-        if (source.indexState === 'indexed') continue;
-        try {
-          const final = await this.sources.indexSourceAndWait(source);
-          if (final.indexState === 'indexed') {
-            newlyIndexed += 1;
-          } else {
-            failures.push({
-              sourceId: source.id,
-              name: source.name,
-              error: final.indexError ?? 'processing failed',
-            });
-          }
-        } catch (err) {
-          // Per-source failures are isolated so one bad URL (404, empty
-          // body, etc.) does not strand the rest of the batch. Each source
-          // carries its own reason (FR-030/FR-032); the aggregate summary
-          // stays for the base-level view.
-          const message = errorMessage(err);
-          failures.push({
-            sourceId: source.id,
-            name: source.name,
-            error: message,
-          });
-          this.logger.warn(
-            `indexSource failed for ${source.id} (${source.name}): ${message}`,
-          );
-        }
+      // Every source goes through the gateway on every run, including ones
+      // already marked indexed: the gateway re-checks them against LightRAG
+      // and re-ingests anything the pipeline never actually processed. That is
+      // what makes the Index button a real retry instead of a no-op.
+      const outcomes = await this.sources.indexSources(sources);
+
+      const failures = outcomes.filter((o) => o.status === 'failed');
+      const stillProcessing = outcomes.filter((o) => o.status === 'pending');
+      for (const failure of failures) {
+        this.logger.warn(
+          `indexing failed for ${failure.sourceId} (${failure.name}): ${failure.error ?? 'unknown error'}`,
+        );
       }
+      if (stillProcessing.length > 0) {
+        this.logger.log(
+          `${stillProcessing.length} source(s) still in LightRAG's pipeline; the next run will confirm them`,
+        );
+      }
+
+      // Only genuine failures go into indexError. Documents the run stopped
+      // waiting for are not errors: LightRAG is still working on them, they
+      // show as `pending` on their own rows, and painting the whole base red
+      // over them is what made every large re-index look like an outage.
       const summary =
         failures.length === 0
           ? null
           : `${failures.length} source(s) failed: ${failures
               .slice(0, 5)
-              .map((f) => `${f.name} (${f.error})`)
+              .map((f) => `${f.name} (${f.error ?? 'unknown error'})`)
               .join('; ')}${failures.length > 5 ? '; ...' : ''}`;
-      const totalIndexed = previouslyIndexed + newlyIndexed;
-      // 'ready' when at least one document is indexed OR the KB is empty
-      // (nothing to do is a trivially "ready" state). 'failed' only when
-      // there are sources but none ever indexed - so the UI doesn't claim
-      // a KB is queryable when it physically has zero documents.
+      const indexedCount = outcomes.filter((o) => o.indexed).length;
+      // 'ready' means LightRAG confirmed at least one document as processed,
+      // or the base is empty (nothing to do is trivially ready). Accepting an
+      // upload is not enough: that is what used to show `ready` on a base with
+      // an empty graph that answered every query with no context. A run that
+      // only has documents left in the pipeline is not a failed run either -
+      // it failed nothing, so it does not get the failed badge.
+      const nothingWorked = indexedCount === 0 && stillProcessing.length === 0;
       const status: IndexStatusTypes =
-        totalIndexed > 0 || sources.length === 0 ? 'ready' : 'failed';
+        nothingWorked && sources.length > 0 ? 'failed' : 'ready';
       await this.gateway.updateIndexState(knowledgeId, {
         indexStatus: status,
-        // Bump indexedAt only when this run actually added something.
+        // Bump indexedAt only when something is actually searchable now.
         // Preserves the timestamp of the last successful run when the
         // current run failed everything but earlier runs had succeeded.
-        indexedAt: newlyIndexed > 0 ? new Date() : undefined,
+        indexedAt: indexedCount > 0 ? new Date() : undefined,
         indexError: summary,
       });
     } catch (err) {
diff --git a/api/src/slices/reins/knowledge/domain/knowledge.types.ts b/api/src/slices/reins/knowledge/domain/knowledge.types.ts
index 7745daf7..2a604c74 100644
--- a/api/src/slices/reins/knowledge/domain/knowledge.types.ts
+++ b/api/src/slices/reins/knowledge/domain/knowledge.types.ts
@@ -20,7 +20,8 @@ export type MigrationStateTypes =
   | 'done'
   | 'failed';
 
-export interface IKnowledgeData {
+/** One Knowledge row as stored; what the gateway reads and writes. */
+export interface IKnowledgeRecord {
   id: string;
   name: string;
   description: string | null;
@@ -38,6 +39,23 @@ export interface IKnowledgeData {
   updatedAt: Date;
 }
 
+/**
+ * The row plus index progress over its sources, which lives in the source
+ * slice and is stitched on by the service. `indexedCount / sourceCount` is
+ * what the UI shows while a run is in flight.
+ */
+export interface IKnowledgeData extends IKnowledgeRecord {
+  sourceCount: number;
+  indexedCount: number;
+  failedCount: number;
+  /**
+   * Sources LightRAG is still chunking. `ready` with a non-zero value here
+   * means "searchable, but not all of it yet" - without it a base that stopped
+   * waiting on a long document is indistinguishable from a finished one.
+   */
+  processingCount: number;
+}
+
 export interface ICreateKnowledgeData {
   name: string;
   description?: string;
diff --git a/api/src/slices/reins/knowledge/dtos/knowledge.dto.ts b/api/src/slices/reins/knowledge/dtos/knowledge.dto.ts
index 13cb0b8f..0702d0a8 100644
--- a/api/src/slices/reins/knowledge/dtos/knowledge.dto.ts
+++ b/api/src/slices/reins/knowledge/dtos/knowledge.dto.ts
@@ -25,6 +25,19 @@ export class KnowledgeDto implements Omit<
   @ApiProperty({ type: String, nullable: true }) indexError: string | null;
   @ApiProperty({ type: String, nullable: true }) indexedAt: Date | null;
   @ApiProperty({ type: String, nullable: true }) indexStartedAt: Date | null;
+  @ApiProperty({ description: 'Sources attached to this knowledge' })
+  sourceCount: number;
+  @ApiProperty({ description: 'Sources LightRAG confirmed as processed' })
+  indexedCount: number;
+  @ApiProperty({
+    description: 'Sources whose last index run recorded an error',
+  })
+  failedCount: number;
+  @ApiProperty({
+    description:
+      'Sources handed to LightRAG that it has not finished processing. A ready knowledge with a non-zero count is searchable but not complete yet; run Index again once the pipeline drains.',
+  })
+  processingCount: number;
   @ApiProperty({ enum: ['absent', 'starting', 'ready', 'failed', 'stopping'] })
   instanceState: InstanceStateTypes;
   @ApiProperty({ type: String, nullable: true }) instanceError: string | null;
diff --git a/api/src/slices/reins/knowledge/knowledge.controller.ts b/api/src/slices/reins/knowledge/knowledge.controller.ts
index 91e9e2b8..ad23f662 100644
--- a/api/src/slices/reins/knowledge/knowledge.controller.ts
+++ b/api/src/slices/reins/knowledge/knowledge.controller.ts
@@ -15,6 +15,7 @@ import { KnowledgeService } from './domain/knowledge.service';
 import { IKnowledgeConfigGateway } from '../config/domain/knowledgeConfig.gateway';
 import { IGraphData } from './domain/knowledge.types';
 import { ILightragClient } from '../lightrag/domain/lightrag.client';
+import { ILightragRuntimeConfig } from '../lightrag/domain/lightrag.types';
 import { ILlmGateway } from '#/llm/domain';
 import {
   CreateKnowledgeDto,
@@ -79,6 +80,7 @@ export class KnowledgeController {
       hasCredentialsSelected: boolean;
       isHealthy: boolean;
     };
+    runtime: ILightragRuntimeConfig | null;
   }> {
     const [config, selected, hasChat, hasEmbedding] = await Promise.all([
       this.knowledgeConfig.resolve(),
@@ -88,10 +90,12 @@ export class KnowledgeController {
     ]);
 
     let isHealthy = false;
+    let runtime: ILightragRuntimeConfig | null = null;
     if (config.url.length > 0) {
       try {
-        await this.lightrag.health();
-        isHealthy = true;
+        const health = await this.lightrag.health();
+        isHealthy = health.ok;
+        runtime = health.configuration;
       } catch {
         isHealthy = false;
       }
@@ -104,10 +108,13 @@ export class KnowledgeController {
         hasEmbeddingCredential: hasEmbedding,
         hasUrl: config.url.length > 0,
         hasBucket: config.bucket.length > 0,
-        hasCredentialsSelected:
-          selected.chat !== null && selected.embedding !== null,
+        // Only the chat credential is an admin-side choice. The embedding
+        // model is whatever the LightRAG container was started with, so it is
+        // reported through `runtime` instead of being picked here.
+        hasCredentialsSelected: selected.chat !== null,
         isHealthy,
       },
+      runtime,
     };
   }
 
diff --git a/api/src/slices/reins/knowledge/knowledge.isolation.spec.ts b/api/src/slices/reins/knowledge/knowledge.isolation.spec.ts
index 69b4328d..70af5063 100644
--- a/api/src/slices/reins/knowledge/knowledge.isolation.spec.ts
+++ b/api/src/slices/reins/knowledge/knowledge.isolation.spec.ts
@@ -42,6 +42,10 @@ function base(p: Partial<IKnowledgeData> & { id: string }): IKnowledgeData {
     instanceError: null,
     instanceEndpoint: null,
     migrationState: 'done',
+    sourceCount: 0,
+    indexedCount: 0,
+    failedCount: 0,
+    processingCount: 0,
     createdAt: new Date(0),
     updatedAt: new Date(0),
     ...p,
@@ -58,6 +62,8 @@ function source(
     mimeType: null,
     content: 'text',
     sizeBytes: null,
+    indexed: true,
+    indexStatus: 'indexed',
     indexState: 'indexed',
     indexError: null,
     indexedAt: new Date(0),
@@ -129,6 +135,19 @@ function makeHarness(bases: IKnowledgeData[], sources: ISourceData[]): Harness {
     findByKnowledge: jest.fn(async (knowledgeId: string) =>
       sources.filter((s) => s.knowledgeId === knowledgeId),
     ),
+    countByKnowledgeIds: jest.fn(async (knowledgeIds: string[]) => {
+      const counts = new Map();
+      for (const id of knowledgeIds) {
+        const own = sources.filter((s) => s.knowledgeId === id);
+        counts.set(id, {
+          total: own.length,
+          indexed: own.filter((s) => s.indexStatus === 'indexed').length,
+          failed: own.filter((s) => s.indexStatus === 'failed').length,
+          processing: 0,
+        });
+      }
+      return counts;
+    }),
   } as unknown as SourceService;
 
   const instances = {} as IInstanceGateway;
diff --git a/api/src/slices/reins/knowledge/knowledge.module.ts b/api/src/slices/reins/knowledge/knowledge.module.ts
index 0f3f839c..b012311f 100644
--- a/api/src/slices/reins/knowledge/knowledge.module.ts
+++ b/api/src/slices/reins/knowledge/knowledge.module.ts
@@ -10,6 +10,7 @@ import { InstanceModule } from '../instance/instance.module';
 import { KnowledgeController } from './knowledge.controller';
 import { IKnowledgeGateway } from './domain/knowledge.gateway';
 import { KnowledgeService } from './domain/knowledge.service';
+import { IndexReconcileService } from './domain/indexReconcile.service';
 import { KnowledgeGateway } from './data/knowledge.gateway';
 import { KnowledgeMapper } from './data/knowledge.mapper';
 import { KnowledgeTool } from './knowledge.tool';
@@ -29,6 +30,7 @@ import { KnowledgeTool } from './knowledge.tool';
   providers: [
     KnowledgeMapper,
     KnowledgeService,
+    IndexReconcileService,
     { provide: IKnowledgeGateway, useClass: KnowledgeGateway },
     KnowledgeTool,
   ],
diff --git a/api/src/slices/reins/knowledge/knowledge.tool.spec.ts b/api/src/slices/reins/knowledge/knowledge.tool.spec.ts
index 6b84be7d..3da1c649 100644
--- a/api/src/slices/reins/knowledge/knowledge.tool.spec.ts
+++ b/api/src/slices/reins/knowledge/knowledge.tool.spec.ts
@@ -68,7 +68,12 @@ function makeHarness(boundIds: string[]): Harness {
   const findExistingByIds = jest.fn(async (ids: string[]) =>
     ids
       .filter((id) => id === 'k1')
-      .map((id) => ({ id, name: 'Relays', description: 'relay facts' })),
+      .map((id) => ({
+        id,
+        name: 'Relays',
+        description: 'relay facts',
+        migrationState: 'done',
+      })),
   );
   const knowledgeGateway = {
     findExistingByIds,
@@ -196,7 +201,12 @@ describe('FR-006 — a multi-base answer attributes each part', () => {
     } as unknown as ITemplateGateway;
     const knowledgeGateway = {
       findExistingByIds: jest.fn(async (ids: string[]) =>
-        ids.map((id) => ({ id, name: `Base ${id}`, description: null })),
+        ids.map((id) => ({
+          id,
+          name: `Base ${id}`,
+          description: null,
+          migrationState: 'done',
+        })),
       ),
     } as unknown as IKnowledgeGateway;
 
@@ -246,7 +256,12 @@ describe('FR-006 — a multi-base answer attributes each part', () => {
     } as unknown as ITemplateGateway;
     const knowledgeGateway = {
       findExistingByIds: jest.fn(async (ids: string[]) =>
-        ids.map((id) => ({ id, name: `Base ${id}`, description: null })),
+        ids.map((id) => ({
+          id,
+          name: `Base ${id}`,
+          description: null,
+          migrationState: 'done',
+        })),
       ),
     } as unknown as IKnowledgeGateway;
 
@@ -265,4 +280,61 @@ describe('FR-006 — a multi-base answer attributes each part', () => {
     expect(text).toContain('Base kb-two');
     expect(text).toContain('could not be reached');
   });
+
+  test('bases still on the shared pool are asked once, not once each', async () => {
+    // Pre-migration every base answers from the same index: N queries would
+    // return N copies of one answer and pay for N retrievals.
+    const queriedIds: string[] = [];
+    const knowledgeService = {
+      query: jest.fn((knowledgeId: string) => {
+        queriedIds.push(knowledgeId);
+        return Promise.resolve({
+          answer: 'shared answer',
+          knowledgeId,
+          complete: false,
+          references: [],
+        });
+      }),
+    } as unknown as KnowledgeService;
+    const agentGateway = {
+      findById: jest.fn(() =>
+        Promise.resolve({
+          id: 'agent-1',
+          knowledgeIds: ['k1', 'kb-two'],
+          templateId: 'tpl-1',
+        }),
+      ),
+    } as unknown as IAgentGateway;
+    const templateGateway = {
+      findById: jest.fn(() => Promise.resolve(null)),
+    } as unknown as ITemplateGateway;
+    const knowledgeGateway = {
+      findExistingByIds: jest.fn((ids: string[]) =>
+        Promise.resolve(
+          ids.map((id) => ({
+            id,
+            name: `Base ${id}`,
+            description: null,
+            migrationState: 'notStarted',
+          })),
+        ),
+      ),
+    } as unknown as IKnowledgeGateway;
+
+    const tool = new KnowledgeTool(
+      knowledgeService,
+      agentGateway,
+      templateGateway,
+      knowledgeGateway,
+    );
+    const result = await tool.query(
+      { query: 'q' },
+      null,
+      agentRequest('agent-1'),
+    );
+
+    expect(queriedIds).toEqual(['k1']);
+    const parsed = JSON.parse(textOf(result)) as { answer: string };
+    expect(parsed.answer).toBe('shared answer');
+  });
 });
diff --git a/api/src/slices/reins/knowledge/knowledge.tool.ts b/api/src/slices/reins/knowledge/knowledge.tool.ts
index 07164a8c..4433a35a 100644
--- a/api/src/slices/reins/knowledge/knowledge.tool.ts
+++ b/api/src/slices/reins/knowledge/knowledge.tool.ts
@@ -9,8 +9,13 @@ import { IDynamicallyDescribedTool } from '#/mcp/interfaces/dynamic-description.
 import { KnowledgeService } from './domain/knowledge.service';
 import { IKnowledgeGateway } from './domain/knowledge.gateway';
 
+// The batching sentence is not stylistic advice: one call spends several
+// seconds inside the knowledge service composing an answer, and the service
+// serves them concurrently. Measured on a ten-question request, asking one at
+// a time took 198s of retrieval where the same ten issued together took 35s.
+// Without saying so, models ask sequentially and the user waits for the sum.
 const BASE_DESCRIPTION =
-  'Search your bound knowledge bases for factual information. MUST be called FIRST, before drafting any response, when the user asks about a topic that could plausibly be covered by your bound knowledge bases (see the list below). Do NOT hedge with phrases like "isn\'t explicitly detailed" or "based on what I know" before calling this tool - drafting an answer first and then querying is a bug, it wastes the user\'s time and produces a confusing two-phase response. Prefer this over web_search for anything that could be in user-uploaded content. Returns matched content with citations. The knowledge_id parameter is optional - omit it to search across all your bound bases at once.';
+  'Search your bound knowledge bases for factual information. MUST be called FIRST, before drafting any response, when the user asks about a topic that could plausibly be covered by your bound knowledge bases (see the list below). Do NOT hedge with phrases like "isn\'t explicitly detailed" or "based on what I know" before calling this tool - drafting an answer first and then querying is a bug, it wastes the user\'s time and produces a confusing two-phase response. When the request contains several independent questions, issue all of those calls in the same turn rather than one after another: they are answered concurrently, so batching turns minutes of waiting into seconds. Prefer this over web_search for anything that could be in user-uploaded content. Returns matched content with citations. The knowledge_id parameter is optional and rarely worth setting: bases are not searched separately, so one call covers everything bound to you.';
 
 interface ToolResult {
   content: { type: 'text'; text: string }[];
@@ -120,11 +125,23 @@ export class KnowledgeTool implements IDynamicallyDescribedTool {
       const bases = await this.knowledgeGateway.findExistingByIds(targetIds);
       const nameOf = new Map(bases.map((b) => [b.id, b.name]));
 
+      // Bases still on the shared pool answer from one index: fanning out
+      // over them would return N copies of the same answer and pay for N
+      // retrievals — the exact defect the pre-isolation code collapsed. So
+      // fan out only across bases with their own instance, and ask the
+      // shared-pool group once through its first id.
+      const doneOf = new Map(
+        bases.map((b) => [b.id, b.migrationState === 'done']),
+      );
+      const migrated = targetIds.filter((id) => doneOf.get(id) === true);
+      const sharedPool = targetIds.filter((id) => doneOf.get(id) !== true);
+      const queryIds = [...migrated, ...sharedPool.slice(0, 1)];
+
       // One retrieval per bound base against that base's own instance; each
       // block names the base it came from (FR-006). A base that cannot be
       // reached is named rather than silently narrowing the answer.
       const results = await Promise.all(
-        targetIds.map(async (id) => {
+        queryIds.map(async (id) => {
           const knowledge_name = nameOf.get(id) ?? null;
           try {
             const r = await this.knowledgeService.query(id, query);
@@ -139,7 +156,7 @@ export class KnowledgeTool implements IDynamicallyDescribedTool {
           }
         }),
       );
-      return ok(targetIds.length === 1 ? results[0] : { results });
+      return ok(queryIds.length === 1 ? results[0] : { results });
     } catch (e) {
       const message = e instanceof Error ? e.message : 'Knowledge query failed';
       this.logger.warn(
diff --git a/api/src/slices/reins/lightrag/data/lightragHttp.client.ts b/api/src/slices/reins/lightrag/data/lightragHttp.client.ts
index a024e87d..edae4b62 100644
--- a/api/src/slices/reins/lightrag/data/lightragHttp.client.ts
+++ b/api/src/slices/reins/lightrag/data/lightragHttp.client.ts
@@ -14,6 +14,11 @@ import {
   ILightragGraphNode,
   ILightragGraphEdge,
   ITrackStatus,
+  IDocumentProcessingStatus,
+  DocumentProcessingStatusTypes,
+  ILightragRuntimeConfig,
+  IDocumentRecord,
+  IPipelineStatus,
   LightragClientError,
 } from '../domain/lightrag.types';
 
@@ -74,7 +79,8 @@ export class LightragHttpClient extends ILightragClient {
         signal: controller.signal,
       });
       await this.ensureOk(res, '/health');
-      return { ok: true };
+      const body: unknown = await res.json();
+      return { ok: true, configuration: extractRuntimeConfig(body) };
     } finally {
       clearTimeout(timer);
     }
@@ -225,11 +231,42 @@ export class LightragHttpClient extends ILightragClient {
     await this.ensureOk(res, '/documents/delete_document');
   }
 
+  /**
+   * Ingest only enqueues, so the track id it returns says nothing about
+   * whether the document is searchable yet. This reports where the pipeline
+   * actually got to. An unknown track id (404) yields no documents, which
+   * callers read as "LightRAG has nothing under this id". Routed with intent
+   * 'write': tracking follows the instance the ingest went to, which during
+   * migration is the base's own instance rather than the shared pool.
+   */
   async getTrackStatus(
     knowledgeId: string,
     trackId: string,
   ): Promise<ITrackStatus> {
     const cfg = await this.requireEnabled({ knowledgeId, intent: 'write' });
+    return this.fetchTrackStatus(cfg, trackId);
+  }
+
+  /**
+   * One snapshot of every document the base's instance holds. Callers index
+   * it by doc id or by filename: both are needed to reconcile a source whose
+   * upload was refused because the content or the filename is already stored.
+   */
+  async listDocuments(knowledgeId: string): Promise<IDocumentRecord[]> {
+    const cfg = await this.requireEnabled({ knowledgeId, intent: 'write' });
+    const res = await this.fetchImpl(`${cfg.baseUrl}/documents`, {
+      method: 'GET',
+      headers: this.headers(cfg.apiKey),
+    });
+    await this.ensureOk(res, '/documents');
+    const body: unknown = await res.json();
+    return extractDocuments(body);
+  }
+
+  private async fetchTrackStatus(
+    cfg: ResolvedRequestConfig,
+    trackId: string,
+  ): Promise<ITrackStatus> {
     const res = await this.fetchImpl(
       `${cfg.baseUrl}/documents/track_status/${encodeURIComponent(trackId)}`,
       {
@@ -237,7 +274,7 @@ export class LightragHttpClient extends ILightragClient {
         headers: this.headers(cfg.apiKey),
       },
     );
-    if (res.status === 404) return { status: 'pending', error: null };
+    if (res.status === 404) return { documents: [] };
     await this.ensureOk(res, `/documents/track_status/${trackId}`);
     const body: unknown = await res.json();
     return extractTrackStatus(body);
@@ -247,17 +284,8 @@ export class LightragHttpClient extends ILightragClient {
     cfg: ResolvedRequestConfig,
     trackId: string,
   ): Promise<string[]> {
-    const res = await this.fetchImpl(
-      `${cfg.baseUrl}/documents/track_status/${encodeURIComponent(trackId)}`,
-      {
-        method: 'GET',
-        headers: this.headers(cfg.apiKey),
-      },
-    );
-    if (res.status === 404) return [];
-    await this.ensureOk(res, `/documents/track_status/${trackId}`);
-    const body: unknown = await res.json();
-    return extractTrackStatusDocIds(body);
+    const status = await this.fetchTrackStatus(cfg, trackId);
+    return status.documents.map((d) => d.id);
   }
 
   async getGraphLabels(knowledgeId?: string): Promise<string[]> {
@@ -298,6 +326,44 @@ export class LightragHttpClient extends ILightragClient {
     return extractGraph(body);
   }
 
+  /**
+   * The pipeline belongs to one LightRAG instance. Without a knowledge id this
+   * asks the shared instance, which is every base while instance isolation is
+   * off; a base on its own instance is addressed by id, like getGraphLabels.
+   */
+  async getPipelineStatus(knowledgeId?: string): Promise<IPipelineStatus> {
+    const cfg = await this.requireEnabled(
+      knowledgeId ? { knowledgeId, intent: 'write' } : undefined,
+    );
+    const res = await this.fetchImpl(
+      `${cfg.baseUrl}/documents/pipeline_status`,
+      { method: 'GET', headers: this.headers(cfg.apiKey) },
+    );
+    await this.ensureOk(res, '/documents/pipeline_status');
+    const body: unknown = await res.json();
+    return extractPipelineStatus(body);
+  }
+
+  /**
+   * `reprocess_failed` is a misleading name: the handler hands
+   * `apipeline_process_enqueue_documents` no arguments, and that takes every
+   * document sitting in PENDING, PROCESSING or FAILED. So this is LightRAG's
+   * "pick the queue back up" button, and the only one it has - `/documents/scan`
+   * looks like the obvious candidate but only globs the top level of the input
+   * directory, and an enqueued file has already been moved into `__enqueued__`
+   * by then, so a scan finds nothing to do.
+   */
+  async restartPipeline(knowledgeId?: string): Promise<void> {
+    const cfg = await this.requireEnabled(
+      knowledgeId ? { knowledgeId, intent: 'write' } : undefined,
+    );
+    const res = await this.fetchImpl(
+      `${cfg.baseUrl}/documents/reprocess_failed`,
+      { method: 'POST', headers: this.headers(cfg.apiKey) },
+    );
+    await this.ensureOk(res, '/documents/reprocess_failed');
+  }
+
   private async requireEnabled(
     ctx?: ILightragCallContext,
   ): Promise<ResolvedRequestConfig> {
@@ -387,44 +453,87 @@ function extractLabels(body: unknown): string[] {
   return body.filter((x): x is string => typeof x === 'string');
 }
 
-// One track id can cover several documents (an archive upload); the source
-// is 'processed' only when every one of them is, 'failed' as soon as any is.
-export function extractTrackStatus(body: unknown): ITrackStatus {
-  if (!isRecord(body)) return { status: 'pending', error: null };
-  const docs = Array.isArray(body.documents) ? body.documents : [];
-  if (docs.length === 0) return { status: 'pending', error: null };
+function extractRuntimeConfig(body: unknown): ILightragRuntimeConfig | null {
+  if (!isRecord(body)) return null;
+  const config = body.configuration;
+  if (!isRecord(config)) return null;
 
-  let sawProcessing = false;
-  let sawPending = false;
-  for (const doc of docs) {
-    if (!isRecord(doc)) continue;
-    const status = typeof doc.status === 'string' ? doc.status : '';
-    if (status === 'failed') {
-      const error =
-        typeof doc.error_msg === 'string' && doc.error_msg.length > 0
-          ? doc.error_msg
-          : 'processing failed';
-      return { status: 'failed', error };
-    }
-    if (status === 'processing') sawProcessing = true;
-    if (status === 'pending' || status === 'enqueued') sawPending = true;
+  const read = (key: string): string | null => {
+    const value = config[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+  };
+
+  return {
+    llmBinding: read('llm_binding'),
+    llmModel: read('llm_model'),
+    embeddingBinding: read('embedding_binding'),
+    embeddingModel: read('embedding_model'),
+    embeddingBindingHost: read('embedding_binding_host'),
+  };
+}
+
+function extractPipelineStatus(body: unknown): IPipelineStatus {
+  if (!isRecord(body)) {
+    // A body we cannot read is reported as idle on purpose. The one caller uses
+    // this to decide whether to nudge a stalled pipeline, and a nudge is
+    // cheap - it ingests nothing - while a wrongly-assumed "busy" would leave
+    // a base stuck forever, which is the bug this exists to prevent.
+    return { busy: false, docs: 0, currentBatch: 0, latestMessage: '' };
   }
-  if (sawProcessing) return { status: 'processing', error: null };
-  if (sawPending) return { status: 'pending', error: null };
-  return { status: 'processed', error: null };
+  return {
+    busy: body.busy === true,
+    docs: isNumber(body.docs) ? body.docs : 0,
+    currentBatch: isNumber(body.cur_batch) ? body.cur_batch : 0,
+    latestMessage: isString(body.latest_message) ? body.latest_message : '',
+  };
 }
 
-function extractTrackStatusDocIds(body: unknown): string[] {
-  if (!isRecord(body)) return [];
+function extractTrackStatus(body: unknown): ITrackStatus {
+  if (!isRecord(body)) return { documents: [] };
   const docs = body.documents;
-  if (!Array.isArray(docs)) return [];
-  const ids: string[] = [];
+  if (!Array.isArray(docs)) return { documents: [] };
+  const documents: IDocumentProcessingStatus[] = [];
   for (const doc of docs) {
-    if (isRecord(doc) && typeof doc.id === 'string') {
-      ids.push(doc.id);
+    if (!isRecord(doc) || typeof doc.id !== 'string') continue;
+    documents.push({
+      id: doc.id,
+      status: toProcessingStatus(doc.status),
+      errorMessage: typeof doc.error_msg === 'string' ? doc.error_msg : null,
+    });
+  }
+  return { documents };
+}
+
+function extractDocuments(body: unknown): IDocumentRecord[] {
+  const out: IDocumentRecord[] = [];
+  if (!isRecord(body)) return out;
+  const statuses = body.statuses;
+  if (!isRecord(statuses)) return out;
+
+  for (const [statusName, docs] of Object.entries(statuses)) {
+    if (!Array.isArray(docs)) continue;
+    for (const doc of docs) {
+      if (!isRecord(doc) || typeof doc.id !== 'string') continue;
+      out.push({
+        id: doc.id,
+        // The per-document `status` field is authoritative when present; the
+        // bucket name is the fallback (they agree in practice).
+        status: toProcessingStatus(doc.status ?? statusName),
+        filePath: typeof doc.file_path === 'string' ? doc.file_path : null,
+      });
     }
   }
-  return ids;
+  return out;
+}
+
+function toProcessingStatus(value: unknown): DocumentProcessingStatusTypes {
+  if (value === 'processed' || value === 'failed' || value === 'pending') {
+    return value;
+  }
+  // Anything else - 'processing', or a state a newer LightRAG adds - counts as
+  // still in flight. Erring that way makes a poller wait rather than call a
+  // document searchable when it is not.
+  return 'processing';
 }
 
 function isString(value: unknown): value is string {
diff --git a/api/src/slices/reins/lightrag/data/workspace.ts b/api/src/slices/reins/lightrag/data/workspace.ts
index 7ae76559..dd7e6507 100644
--- a/api/src/slices/reins/lightrag/data/workspace.ts
+++ b/api/src/slices/reins/lightrag/data/workspace.ts
@@ -1,3 +1,20 @@
+/**
+ * Per-knowledge workspace name sent with every ingest.
+ *
+ * ⚠️ LightRAG currently ignores it. A workspace there is a property of the
+ * *instance*, set by the `WORKSPACE` env var or the `--workspace` flag at
+ * startup; there is no per-request equivalent on the document or query
+ * endpoints. Everything Ranch ingests therefore lands in the one workspace the
+ * container was started with (`default` for PostgreSQL storages), and a query
+ * searches across every knowledge base at once - an agent bound to base A can
+ * be answered from base B's documents.
+ *
+ * Real isolation needs one LightRAG instance per base, each with its own
+ * `WORKSPACE` over the shared Postgres, which is an infrastructure decision
+ * rather than something this function can fix. The value is kept because it
+ * costs nothing, is already what the ingest calls carry, and is exactly what
+ * those instances would be named. See api/src/slices/reins/README.md.
+ */
 export function workspaceOf(knowledgeId: string): string {
   return `knowledge_${knowledgeId.replace(/-/g, '')}`;
 }
diff --git a/api/src/slices/reins/lightrag/domain/lightrag.client.ts b/api/src/slices/reins/lightrag/domain/lightrag.client.ts
index f5de0d6f..56868ca5 100644
--- a/api/src/slices/reins/lightrag/domain/lightrag.client.ts
+++ b/api/src/slices/reins/lightrag/domain/lightrag.client.ts
@@ -9,6 +9,8 @@ import {
   IGetGraphInput,
   ILightragGraph,
   ITrackStatus,
+  IDocumentRecord,
+  IPipelineStatus,
 } from './lightrag.types';
 
 export abstract class ILightragClient {
@@ -25,6 +27,15 @@ export abstract class ILightragClient {
     knowledgeId: string,
     trackId: string,
   ): Promise<ITrackStatus>;
+  abstract listDocuments(knowledgeId: string): Promise<IDocumentRecord[]>;
   abstract getGraphLabels(knowledgeId?: string): Promise<string[]>;
   abstract getGraph(input: IGetGraphInput): Promise<ILightragGraph>;
+  abstract getPipelineStatus(knowledgeId?: string): Promise<IPipelineStatus>;
+  /**
+   * Put the whole backlog back on the pipeline: every document LightRAG holds
+   * in PENDING, PROCESSING or FAILED, not only the failed ones its endpoint is
+   * named after. Ingests nothing, so the only work it can start is work that
+   * was already paid for once and never finished.
+   */
+  abstract restartPipeline(knowledgeId?: string): Promise<void>;
 }
diff --git a/api/src/slices/reins/lightrag/domain/lightrag.types.ts b/api/src/slices/reins/lightrag/domain/lightrag.types.ts
index 1770e96c..668e7a8b 100644
--- a/api/src/slices/reins/lightrag/domain/lightrag.types.ts
+++ b/api/src/slices/reins/lightrag/domain/lightrag.types.ts
@@ -34,6 +34,36 @@ export interface IQueryInput {
   topK?: number;
 }
 
+// Ingest endpoints only enqueue: they return a track id and LightRAG builds
+// chunks, embeddings and the graph in a background pipeline afterwards. A
+// document is searchable only once it reaches 'processed'.
+export type DocumentProcessingStatusTypes =
+  | 'pending'
+  | 'processing'
+  | 'processed'
+  | 'failed';
+
+export interface IDocumentProcessingStatus {
+  id: string;
+  status: DocumentProcessingStatusTypes;
+  errorMessage: string | null;
+}
+
+export interface ITrackStatus {
+  documents: IDocumentProcessingStatus[];
+}
+
+/**
+ * A document as LightRAG stores it. `filePath` matters because LightRAG
+ * refuses an upload whose filename it already holds, and that refusal names
+ * only the file - resolving it back to a doc id needs this listing.
+ */
+export interface IDocumentRecord {
+  id: string;
+  status: DocumentProcessingStatusTypes;
+  filePath: string | null;
+}
+
 export interface IQueryReference {
   referenceId: string;
   filePath: string;
@@ -44,20 +74,23 @@ export interface IQueryResult {
   references: IQueryReference[];
 }
 
-export interface ILightragHealth {
-  ok: boolean;
+/**
+ * What the LightRAG process is actually running, as reported by /health. Its
+ * bindings come from the container env and are resolved once at startup, so
+ * this is the only honest answer to "which embedding model is in use". Picking
+ * a credential in the admin expresses intent; this is the effect.
+ */
+export interface ILightragRuntimeConfig {
+  llmBinding: string | null;
+  llmModel: string | null;
+  embeddingBinding: string | null;
+  embeddingModel: string | null;
+  embeddingBindingHost: string | null;
 }
 
-/** Where one submitted document is in its background processing. */
-export type TrackProcessingTypes =
-  | 'pending'
-  | 'processing'
-  | 'processed'
-  | 'failed';
-
-export interface ITrackStatus {
-  status: TrackProcessingTypes;
-  error: string | null;
+export interface ILightragHealth {
+  ok: boolean;
+  configuration: ILightragRuntimeConfig | null;
 }
 
 export interface IGetGraphInput {
@@ -91,6 +124,25 @@ export interface ILightragGraph {
   isTruncated: boolean;
 }
 
+/**
+ * What LightRAG's ingest pipeline is doing right now.
+ *
+ * `busy` is the only field that matters for recovery and it is the one that
+ * cannot be inferred from document status: a queue of PENDING documents looks
+ * identical whether the pipeline is chewing through them or has forgotten they
+ * exist. The queue itself lives in the LightRAG process, so it does not survive
+ * that process being replaced, while the PENDING rows in its database do.
+ */
+export interface IPipelineStatus {
+  busy: boolean;
+  /** Documents in the batch the current job is working through. */
+  docs: number;
+  /** How many of them are done. */
+  currentBatch: number;
+  /** Last line the pipeline logged, useful in our own logs when it stalls. */
+  latestMessage: string;
+}
+
 export class LightragClientError extends Error {
   constructor(
     message: string,
diff --git a/api/src/slices/reins/migration/domain/migration.service.spec.ts b/api/src/slices/reins/migration/domain/migration.service.spec.ts
index ddbb1561..9923e7a3 100644
--- a/api/src/slices/reins/migration/domain/migration.service.spec.ts
+++ b/api/src/slices/reins/migration/domain/migration.service.spec.ts
@@ -1,12 +1,13 @@
 import { MigrationService } from './migration.service';
 import { KnowledgeService } from '../../knowledge/domain/knowledge.service';
 import { IKnowledgeGateway } from '../../knowledge/domain/knowledge.gateway';
-import { IKnowledgeData } from '../../knowledge/domain/knowledge.types';
+import { IKnowledgeRecord } from '../../knowledge/domain/knowledge.types';
 import { SourceService } from '../../source/domain/source.service';
+import { ISourceData } from '../../source/domain/source.types';
 import { IInstanceGateway } from '../../instance/domain/instance.gateway';
 import { IKnowledgeConfigGateway } from '../../config/domain/knowledgeConfig.gateway';
 
-function record(id: string): IKnowledgeData {
+function record(id: string): IKnowledgeRecord {
   return {
     id,
     name: id,
@@ -54,7 +55,7 @@ describe('instance isolation opt-in gate', () => {
   });
 
   test('migration proceeds once the flag is on', async () => {
-    const findAll = jest.fn(() => Promise.resolve<IKnowledgeData[]>([]));
+    const findAll = jest.fn(() => Promise.resolve<IKnowledgeRecord[]>([]));
     const knowledgeGateway = { findAll } as unknown as IKnowledgeGateway;
     const service = new MigrationService(
       knowledgeGateway,
@@ -75,7 +76,9 @@ describe('instance isolation opt-in gate', () => {
       create: jest.fn(() => Promise.resolve(created)),
       findById: jest.fn(() => Promise.resolve(created)),
     } as unknown as IKnowledgeGateway;
-    const sources = {} as SourceService;
+    const sources = {
+      countByKnowledgeIds: jest.fn(() => Promise.resolve(new Map())),
+    } as unknown as SourceService;
     const ensureCapacityForNew = jest.fn();
     const provision = jest.fn();
     const instances = {
@@ -115,4 +118,50 @@ describe('instance isolation opt-in gate', () => {
     expect(list).not.toHaveBeenCalled();
     expect(provision).not.toHaveBeenCalled();
   });
+
+  test('an unmigrated base is queried even when its rows show nothing indexed', async () => {
+    // Pre-migration rows can lag behind the shared index (a stamp lost to an
+    // interrupted run). The emptiness veto must not silence a base LightRAG
+    // still answers for — that veto starts only once the base is isolated.
+    const base = record('k1');
+    const source: ISourceData = {
+      id: 'src-1',
+      knowledgeId: 'k1',
+      type: 'text',
+      name: 'notes.txt',
+      url: null,
+      mimeType: null,
+      content: 'text',
+      sizeBytes: null,
+      indexed: false,
+      indexStatus: 'pending',
+      indexState: 'queued',
+      indexError: null,
+      indexedAt: null,
+      createdAt: new Date(0),
+      updatedAt: new Date(0),
+    };
+    const searchKnowledge = jest.fn(() =>
+      Promise.resolve({ answer: 'from the shared pool', references: [] }),
+    );
+    const gateway = {
+      findById: jest.fn(() => Promise.resolve(base)),
+      searchKnowledge,
+    } as unknown as IKnowledgeGateway;
+    const sources = {
+      findByKnowledge: jest.fn(() => Promise.resolve([source])),
+      countByKnowledgeIds: jest.fn(() => Promise.resolve(new Map())),
+    } as unknown as SourceService;
+    const service = new KnowledgeService(
+      gateway,
+      sources,
+      {} as IInstanceGateway,
+      makeConfig(false),
+    );
+
+    const result = await service.query('k1', 'anything');
+
+    expect(searchKnowledge).toHaveBeenCalled();
+    expect(result.answer).toBe('from the shared pool');
+  });
 });
diff --git a/api/src/slices/reins/migration/domain/migration.service.ts b/api/src/slices/reins/migration/domain/migration.service.ts
index 58a233a5..678a07e0 100644
--- a/api/src/slices/reins/migration/domain/migration.service.ts
+++ b/api/src/slices/reins/migration/domain/migration.service.ts
@@ -1,7 +1,7 @@
 import { Injectable, Logger, OnApplicationBootstrap } from '@nestjs/common';
 import { IKnowledgeGateway } from '../../knowledge/domain/knowledge.gateway';
 import { KnowledgeService } from '../../knowledge/domain/knowledge.service';
-import { IKnowledgeData } from '../../knowledge/domain/knowledge.types';
+import { IKnowledgeRecord } from '../../knowledge/domain/knowledge.types';
 import { SourceService } from '../../source/domain/source.service';
 import { IInstanceGateway } from '../../instance/domain/instance.gateway';
 import { IKnowledgeConfigGateway } from '../../config/domain/knowledgeConfig.gateway';
@@ -92,7 +92,7 @@ export class MigrationService implements OnApplicationBootstrap {
     }
   }
 
-  private async migrateBase(base: IKnowledgeData): Promise<void> {
+  private async migrateBase(base: IKnowledgeRecord): Promise<void> {
     if (base.migrationState !== 'inProgress') {
       // Requeue BEFORE marking inProgress: a crash between the two leaves
       // the base notStarted with some sources queued, which a restart
diff --git a/api/src/slices/reins/source/data/source.gateway.spec.ts b/api/src/slices/reins/source/data/source.gateway.spec.ts
new file mode 100644
index 00000000..0110c3a5
--- /dev/null
+++ b/api/src/slices/reins/source/data/source.gateway.spec.ts
@@ -0,0 +1,482 @@
+import { SourceGateway } from './source.gateway';
+import { SourceMapper } from './source.mapper';
+import { ISourceData } from '../domain/source.types';
+import {
+  ITrackStatus,
+  IDocumentRecord,
+} from '../../lightrag/domain/lightrag.types';
+import { indexBudgetMs } from '../domain/indexBudget';
+
+const POLL_MS = 3000;
+// The wait now scales with the batch's content volume, so derive it rather
+// than hardcoding. These fixtures are text sources with no known size, which
+// leaves just the base plus the per-document term.
+const TIMEOUT_MS = indexBudgetMs([{ sizeBytes: null }]);
+
+function makeSource(overrides: Partial<ISourceData> = {}): ISourceData {
+  return {
+    id: 'src-1',
+    knowledgeId: 'knowledge-1',
+    type: 'text',
+    name: 'notes.txt',
+    url: null,
+    mimeType: null,
+    content: 'Mazda CX-5 has a naturally aspirated engine.',
+    sizeBytes: null,
+    indexed: false,
+    indexStatus: 'pending',
+    indexState: 'queued',
+    indexError: null,
+    indexedAt: null,
+    createdAt: new Date(0),
+    updatedAt: new Date(0),
+    ...overrides,
+  };
+}
+
+function processed(): ITrackStatus {
+  return {
+    documents: [{ id: 'doc-1', status: 'processed', errorMessage: null }],
+  };
+}
+
+function stillProcessing(): ITrackStatus {
+  return {
+    documents: [{ id: 'doc-1', status: 'processing', errorMessage: null }],
+  };
+}
+
+function failed(message: string): ITrackStatus {
+  return {
+    documents: [{ id: 'doc-1', status: 'failed', errorMessage: message }],
+  };
+}
+
+interface IRowPatch {
+  lightragDocId?: string | null;
+  indexError?: string | null;
+  indexedAt?: Date | null;
+}
+
+// Tracks the three columns indexSources writes, applying only the keys each
+// update actually sends - the way Prisma does - so a `{ indexError }` write
+// cannot be mistaken for clearing the doc id.
+function makePrismaStub(docIds: Record<string, string | null> = {}) {
+  const errors: Record<string, string | null> = {};
+  const indexedAt: Record<string, Date | null> = {};
+  return {
+    docIds,
+    errors,
+    indexedAt,
+    source: {
+      findUnique: jest.fn(({ where }: { where: { id: string } }) =>
+        Promise.resolve({ lightragDocId: docIds[where.id] ?? null }),
+      ),
+      update: jest.fn(
+        ({ where, data }: { where: { id: string }; data: IRowPatch }) => {
+          if ('lightragDocId' in data) docIds[where.id] = data.lightragDocId!;
+          if ('indexError' in data) errors[where.id] = data.indexError!;
+          if ('indexedAt' in data) indexedAt[where.id] = data.indexedAt!;
+          return Promise.resolve({ id: where.id });
+        },
+      ),
+    },
+  };
+}
+
+function inFlight(): ITrackStatus {
+  return {
+    documents: [{ id: 'doc-1', status: 'processing', errorMessage: null }],
+  };
+}
+
+function duplicateOf(docId: string, originalStatus: string): ITrackStatus {
+  return {
+    documents: [
+      {
+        id: 'dup-1',
+        status: 'failed',
+        errorMessage: `Identical content already exists under another filename. Original doc_id: ${docId}, Status: ${originalStatus}`,
+      },
+    ],
+  };
+}
+
+function makeLightragStub(
+  statuses: ITrackStatus[],
+  documents: IDocumentRecord[] = [],
+) {
+  const queue = [...statuses];
+  return {
+    ingestText: jest.fn(() => Promise.resolve({ docId: 'track-1' })),
+    ingestUrl: jest.fn(() => Promise.resolve({ docId: 'track-1' })),
+    ingestFile: jest.fn(() => Promise.resolve({ docId: 'track-1' })),
+    getTrackStatus: jest.fn(() =>
+      Promise.resolve(queue.length > 1 ? queue.shift()! : queue[0]),
+    ),
+    listDocuments: jest.fn(() => Promise.resolve(documents)),
+  };
+}
+
+type Prisma = ConstructorParameters<typeof SourceGateway>[0];
+type Lightrag = ConstructorParameters<typeof SourceGateway>[2];
+type S3 = ConstructorParameters<typeof SourceGateway>[3];
+type KnowledgeConfig = ConstructorParameters<typeof SourceGateway>[4];
+
+function makeGateway(
+  prisma: ReturnType<typeof makePrismaStub>,
+  lightrag: ReturnType<typeof makeLightragStub>,
+): SourceGateway {
+  // The gateway's constructor takes the full Prisma client and the S3/config
+  // deps, but indexSources only touches `source` and the LightRAG client, so
+  // structural stubs are enough. Same idiom as browser.gateway.spec.ts.
+  return new SourceGateway(
+    prisma as unknown as Prisma,
+    new SourceMapper(),
+    lightrag as unknown as Lightrag,
+    {} as unknown as S3,
+    {} as unknown as KnowledgeConfig,
+  );
+}
+
+describe('SourceGateway.indexSources', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('persists the doc id only once LightRAG reports the document processed', async () => {
+    const prisma = makePrismaStub();
+    const lightrag = makeLightragStub([stillProcessing(), processed()]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    const run = gateway.indexSources([makeSource()]);
+    await jest.advanceTimersByTimeAsync(POLL_MS * 2);
+    const outcomes = await run;
+
+    expect(outcomes).toEqual([
+      {
+        sourceId: 'src-1',
+        name: 'notes.txt',
+        status: 'indexed',
+        indexed: true,
+        error: null,
+      },
+    ]);
+    expect(prisma.docIds['src-1']).toBe('track-1');
+    // The row itself remembers when it became searchable and drops any error.
+    expect(prisma.indexedAt['src-1']).toBeInstanceOf(Date);
+    expect(prisma.errors['src-1']).toBeNull();
+  });
+
+  it('records the failure on the row so the sources table can show it', async () => {
+    const prisma = makePrismaStub();
+    const lightrag = makeLightragStub([failed('embedding request rejected')]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    const run = gateway.indexSources([makeSource()]);
+    await jest.advanceTimersByTimeAsync(POLL_MS);
+    await run;
+
+    expect(prisma.errors['src-1']).toBe('embedding request rejected');
+    // The resume handle from ingest stays put; it is what lets the next run
+    // ask LightRAG about this document instead of uploading it again.
+    expect(prisma.docIds['src-1']).toBe('track-1');
+    // Nothing was confirmed, so the row is not searchable.
+    expect(prisma.indexedAt['src-1']).toBeUndefined();
+  });
+
+  it('clears a leftover error once LightRAG confirms the document processed', async () => {
+    const prisma = makePrismaStub({ 'src-1': 'track-existing' });
+    const lightrag = makeLightragStub([processed()]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    await gateway.indexSources([
+      makeSource({
+        indexed: true,
+        indexStatus: 'indexed',
+        indexError: 'transient failure from an earlier run',
+      }),
+    ]);
+
+    // Otherwise a source that eventually converged stays red in the UI.
+    expect(prisma.errors['src-1']).toBeNull();
+    expect(prisma.docIds['src-1']).toBe('track-existing');
+  });
+
+  it('stamps a source the previous run stopped waiting for', async () => {
+    // The state a timed-out run leaves behind: a handle, no `indexedAt`, no
+    // error. Observed on a 1 MB manual that LightRAG finished 50 minutes after
+    // the run gave up - every later run recognised it as processed and wrote
+    // nothing, so the base sat at 2 of 3 forever.
+    const prisma = makePrismaStub({ 'src-1': 'track-existing' });
+    const lightrag = makeLightragStub([processed()]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    const outcomes = await gateway.indexSources([
+      makeSource({ indexed: false, indexStatus: 'pending', indexedAt: null }),
+    ]);
+
+    expect(outcomes[0].indexed).toBe(true);
+    expect(prisma.indexedAt['src-1']).toBeInstanceOf(Date);
+    expect(prisma.docIds['src-1']).toBe('track-existing');
+    // Confirming must not mean re-uploading: the copy is already in there.
+    expect(lightrag.ingestText).not.toHaveBeenCalled();
+    expect(lightrag.ingestFile).not.toHaveBeenCalled();
+  });
+
+  it('does not rewrite a row that is already stamped and clean', async () => {
+    // One pointless update per source per run is a few hundred writes on a
+    // real base, and it would also move `indexedAt` for content that has not
+    // been touched since.
+    const prisma = makePrismaStub({ 'src-1': 'track-existing' });
+    const lightrag = makeLightragStub([processed()]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    await gateway.indexSources([
+      makeSource({
+        indexed: true,
+        indexStatus: 'indexed',
+        indexedAt: new Date(1000),
+        indexError: null,
+      }),
+    ]);
+
+    expect(prisma.source.update).not.toHaveBeenCalled();
+  });
+
+  it('leaves the source unindexed and surfaces the reason when processing fails', async () => {
+    const prisma = makePrismaStub();
+    const lightrag = makeLightragStub([failed('embedding request rejected')]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    const run = gateway.indexSources([makeSource()]);
+    await jest.advanceTimersByTimeAsync(POLL_MS);
+    const outcomes = await run;
+
+    expect(outcomes).toEqual([
+      {
+        sourceId: 'src-1',
+        name: 'notes.txt',
+        status: 'failed',
+        indexed: false,
+        error: 'embedding request rejected',
+      },
+    ]);
+    // No confirmation timestamp, so `indexed` stays false and the next run
+    // retries after checking what LightRAG did with the handle.
+    expect(prisma.indexedAt['src-1']).toBeUndefined();
+  });
+
+  it('re-ingests a source that claims to be indexed when LightRAG has nothing for it', async () => {
+    const prisma = makePrismaStub({ 'src-1': 'stale-track' });
+    const lightrag = makeLightragStub([{ documents: [] }, processed()]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    const run = gateway.indexSources([makeSource({ indexed: true })]);
+    await jest.advanceTimersByTimeAsync(POLL_MS * 2);
+    const outcomes = await run;
+
+    expect(lightrag.ingestText).toHaveBeenCalledTimes(1);
+    expect(outcomes[0].indexed).toBe(true);
+    expect(prisma.docIds['src-1']).toBe('track-1');
+  });
+
+  it('does not re-ingest a source LightRAG still reports as processed', async () => {
+    const prisma = makePrismaStub({ 'src-1': 'track-existing' });
+    const lightrag = makeLightragStub([processed()]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    const outcomes = await gateway.indexSources([
+      makeSource({ indexed: true }),
+    ]);
+
+    expect(lightrag.ingestText).not.toHaveBeenCalled();
+    expect(outcomes).toEqual([
+      {
+        sourceId: 'src-1',
+        name: 'notes.txt',
+        status: 'indexed',
+        indexed: true,
+        error: null,
+      },
+    ]);
+    expect(prisma.docIds['src-1']).toBe('track-existing');
+  });
+
+  it('waits for a document still in the pipeline instead of re-uploading it', async () => {
+    const prisma = makePrismaStub({ 'src-1': 'track-existing' });
+    const lightrag = makeLightragStub([inFlight(), processed()]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    const run = gateway.indexSources([makeSource({ indexed: true })]);
+    await jest.advanceTimersByTimeAsync(POLL_MS * 2);
+    const outcomes = await run;
+
+    // Re-uploading here is what made LightRAG answer 409 "Document storage
+    // already contains ..." when an index run overlapped a reprocess.
+    expect(lightrag.ingestText).not.toHaveBeenCalled();
+    expect(outcomes[0].indexed).toBe(true);
+  });
+
+  it('adopts the original document when the upload is refused as a duplicate', async () => {
+    const prisma = makePrismaStub();
+    const lightrag = makeLightragStub([
+      duplicateOf('doc-c8d0423fb8bc5700de256d6cb7fe89c8', 'processed'),
+    ]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    const run = gateway.indexSources([makeSource()]);
+    await jest.advanceTimersByTimeAsync(POLL_MS);
+    const outcomes = await run;
+
+    expect(outcomes[0]).toEqual({
+      sourceId: 'src-1',
+      name: 'notes.txt',
+      status: 'indexed',
+      indexed: true,
+      error: null,
+    });
+    expect(prisma.docIds['src-1']).toBe('doc-c8d0423fb8bc5700de256d6cb7fe89c8');
+  });
+
+  it('does not adopt an original document that failed itself', async () => {
+    const prisma = makePrismaStub();
+    const lightrag = makeLightragStub([
+      duplicateOf('doc-c8d0423fb8bc5700de256d6cb7fe89c8', 'failed'),
+    ]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    const run = gateway.indexSources([makeSource()]);
+    await jest.advanceTimersByTimeAsync(POLL_MS);
+    const outcomes = await run;
+
+    expect(outcomes[0].status).toBe('failed');
+    expect(outcomes[0].error).toContain('Identical content already exists');
+    expect(prisma.indexedAt['src-1']).toBeUndefined();
+  });
+
+  it('resolves an adopted doc id through the document snapshot', async () => {
+    const prisma = makePrismaStub({
+      'src-1': 'doc-c8d0423fb8bc5700de256d6cb7fe89c8',
+    });
+    // An adopted doc id is not a track id, so track_status knows nothing about
+    // it. Without the snapshot fallback the source would be re-ingested and
+    // refused as a duplicate again, forever.
+    const lightrag = makeLightragStub(
+      [{ documents: [] }],
+      [
+        {
+          id: 'doc-c8d0423fb8bc5700de256d6cb7fe89c8',
+          status: 'processed',
+          filePath: 'notes.txt',
+        },
+      ],
+    );
+    const gateway = makeGateway(prisma, lightrag);
+
+    const outcomes = await gateway.indexSources([
+      makeSource({ indexed: true }),
+    ]);
+
+    expect(lightrag.ingestText).not.toHaveBeenCalled();
+    expect(outcomes[0].indexed).toBe(true);
+  });
+
+  it('claims the stored document when the upload is refused by filename', async () => {
+    const prisma = makePrismaStub();
+    const lightrag = makeLightragStub(
+      [processed()],
+      [{ id: 'doc-stored', status: 'processed', filePath: 'notes.txt' }],
+    );
+    // LightRAG names only the file in this refusal, never the doc id, so the
+    // id has to come from the listing. Ranch reaches this state whenever it
+    // lost the id for a document LightRAG still holds.
+    lightrag.ingestText.mockRejectedValueOnce(
+      new Error(
+        `LightRAG /documents/upload failed: 409 {"detail":"Document storage already contains 'notes.txt' (Status: processed). Delete the existing record before re-uploading."}`,
+      ),
+    );
+    const gateway = makeGateway(prisma, lightrag);
+
+    const outcomes = await gateway.indexSources([makeSource()]);
+
+    expect(outcomes[0]).toEqual({
+      sourceId: 'src-1',
+      name: 'notes.txt',
+      status: 'indexed',
+      indexed: true,
+      error: null,
+    });
+    expect(prisma.docIds['src-1']).toBe('doc-stored');
+  });
+
+  it('still fails when the stored document under that filename is not processed', async () => {
+    const prisma = makePrismaStub();
+    const lightrag = makeLightragStub(
+      [processed()],
+      [{ id: 'doc-stored', status: 'failed', filePath: 'notes.txt' }],
+    );
+    lightrag.ingestText.mockRejectedValueOnce(
+      new Error(
+        `LightRAG /documents/upload failed: 409 {"detail":"Document storage already contains 'notes.txt' (Status: failed)."}`,
+      ),
+    );
+    const gateway = makeGateway(prisma, lightrag);
+
+    const outcomes = await gateway.indexSources([makeSource()]);
+
+    // Claiming a failed document would hide a real problem behind a green
+    // badge.
+    expect(outcomes[0].indexed).toBe(false);
+    expect(prisma.docIds['src-1']).toBeUndefined();
+  });
+
+  it('reports a document still in the pipeline as pending, not failed', async () => {
+    const prisma = makePrismaStub();
+    const lightrag = makeLightragStub([stillProcessing()]);
+    const gateway = makeGateway(prisma, lightrag);
+
+    const run = gateway.indexSources([makeSource()]);
+    await jest.advanceTimersByTimeAsync(TIMEOUT_MS + POLL_MS);
+    const outcomes = await run;
+
+    // The run stopped waiting; LightRAG did not stop working. Calling this a
+    // failure is what painted a healthy re-index of a large base red.
+    expect(outcomes[0].status).toBe('pending');
+    expect(outcomes[0].indexed).toBe(false);
+    expect(outcomes[0].error).toContain('still processing');
+    // The handle is kept so the next run resumes the wait rather than
+    // uploading a second copy, and no error is left on the row.
+    expect(prisma.docIds['src-1']).toBe('track-1');
+    expect(prisma.errors['src-1']).toBeNull();
+    expect(prisma.indexedAt['src-1']).toBeUndefined();
+  });
+
+  it('waits for a stored document the refusal reports as still processing', async () => {
+    const prisma = makePrismaStub();
+    const lightrag = makeLightragStub(
+      [processed()],
+      [{ id: 'doc-stored', status: 'processing', filePath: 'notes.txt' }],
+    );
+    // Same 409 as the adopt-by-filename case, but the stored copy has not
+    // finished yet. Reporting a failure here made every overlapping run red
+    // even though the document was minutes away from being searchable.
+    lightrag.ingestText.mockRejectedValueOnce(
+      new Error(
+        `LightRAG /documents/upload failed: 409 {"detail":"Document storage already contains 'notes.txt' (Status: processing)."}`,
+      ),
+    );
+    const gateway = makeGateway(prisma, lightrag);
+
+    const run = gateway.indexSources([makeSource()]);
+    await jest.advanceTimersByTimeAsync(POLL_MS);
+    const outcomes = await run;
+
+    expect(outcomes[0].status).toBe('indexed');
+    expect(prisma.docIds['src-1']).toBe('doc-stored');
+  });
+});
diff --git a/api/src/slices/reins/source/data/source.gateway.ts b/api/src/slices/reins/source/data/source.gateway.ts
index 11ac513e..679c174c 100644
--- a/api/src/slices/reins/source/data/source.gateway.ts
+++ b/api/src/slices/reins/source/data/source.gateway.ts
@@ -5,31 +5,136 @@ import {
   NotFoundException,
   ServiceUnavailableException,
 } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import { Readable } from 'stream';
 import { PrismaService } from '#/setup/prisma/prisma.service';
 import { S3Repository } from '#/aws/s3';
 import { IKnowledgeConfigGateway } from '../../config/domain/knowledgeConfig.gateway';
 import { ILightragClient } from '../../lightrag/domain/lightrag.client';
+import {
+  DocumentProcessingStatusTypes,
+  IDocumentRecord,
+} from '../../lightrag/domain/lightrag.types';
 import { ISourceGateway } from '../domain/source.gateway';
 import {
   ISourceData,
   ICreateSourceData,
+  ISourceContent,
+  ISourceCounts,
+  ISourceFilter,
   ISourceIndexStatePatch,
+  ISourcePage,
+  ISourceSelection,
   IUploadSourceFileInput,
   IUploadSourceStreamInput,
   IUploadedSourceFile,
+  ISourceIndexOutcome,
 } from '../domain/source.types';
+import { indexBudgetMs, pollIntervalMs } from '../domain/indexBudget';
 import { SourceMapper } from './source.mapper';
 
+// LightRAG processes ingested documents in a background pipeline. How long one
+// index run waits for it comes from indexBudgetMs, which scales with the
+// batch's content volume: see the note there on why neither a constant nor a
+// per-document figure can work.
+// The per-source wait (waitForSourceIndexed) has no batch to size a budget
+// from, so it keeps a flat deadline. Generous: a large PDF through entity
+// extraction takes minutes, and an expired deadline marks the source failed
+// (retryable), never silently indexed.
 const TRACK_POLL_INTERVAL_MS = 3_000;
-// Generous: a large PDF through entity extraction takes minutes, and an
-// expired deadline marks the source failed (retryable), never silently
-// indexed.
 const TRACK_POLL_TIMEOUT_MS = 15 * 60 * 1000;
 
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+type IExistingIndexCheck =
+  // `docId` is the handle LightRAG confirmed as processed. The caller needs it
+  // to stamp rows that never got one: a run that stopped waiting leaves the
+  // row pending with a handle, and this is where it finally becomes indexed.
+  | { kind: 'indexed'; docId: string }
+  | { kind: 'inFlight'; trackId: string }
+  | { kind: 'stale' }
+  | { kind: 'unknown'; error: string };
+
+// "Identical content already exists under another filename. Original doc_id:
+// doc-abc123, Status: processed" - only worth adopting when that original is
+// itself processed; a failed original has nothing to offer.
+// Deliberately lenient about the id itself: a stricter pattern would silently
+// stop adopting the day LightRAG changes its id format, putting the duplicate
+// loop back.
+const DUPLICATE_OF = /Original doc_id:\s*(\S+?),?\s*Status:\s*(\w+)/i;
+
+// "Document storage already contains 'some-file.md' (Status: processed)" -
+// this refusal names the file but never the doc id, so the id has to come from
+// the document listing.
+const ALREADY_STORED = /Document storage already contains ['"]([^'"]+)['"]/i;
+
+interface IDocumentSnapshot {
+  byId: Map<string, DocumentProcessingStatusTypes>;
+  byName: Map<string, IDocumentRecord>;
+}
+
+function normalizeName(name: string): string {
+  return name.trim().toLowerCase();
+}
+
+function adoptableDocId(message: string | null): string | null {
+  if (message === null) return null;
+  const match = DUPLICATE_OF.exec(message);
+  if (match === null) return null;
+  return match[2].toLowerCase() === 'processed' ? match[1] : null;
+}
+
+/**
+ * Status filters in Prisma terms. `indexed` and `failed` are the two states
+ * with a recorded fact (confirmation timestamp / error); `pending` is
+ * everything else, including a document still moving through the pipeline.
+ * Kept in sync with deriveIndexStatus in the mapper.
+ */
+function whereForStatus(
+  status: ISourceFilter['status'],
+): Prisma.SourceWhereInput {
+  switch (status) {
+    case 'indexed':
+      return { indexedAt: { not: null } };
+    case 'failed':
+      return { indexedAt: null, indexError: { not: null } };
+    case 'pending':
+      return { indexedAt: null, indexError: null };
+    case undefined:
+      return {};
+    default: {
+      const exhaustive: never = status;
+      return exhaustive;
+    }
+  }
+}
+
+/**
+ * The list's filter as a Prisma clause. Shared by the paginated list and the
+ * export so "everything matching what I am looking at" means the same rows in
+ * both - the export is driven by the filter, not by 356 ids in a query string.
+ */
+function whereForFilter(
+  knowledgeId: string,
+  filter: Pick<ISourceFilter, 'search' | 'status' | 'type'>,
+): Prisma.SourceWhereInput {
+  const search = filter.search?.trim();
+  return {
+    knowledgeId,
+    ...whereForStatus(filter.status),
+    ...(filter.type ? { type: filter.type } : {}),
+    ...(search
+      ? { name: { contains: search, mode: 'insensitive' as const } }
+      : {}),
+  };
+}
+
 @Injectable()
 export class SourceGateway extends ISourceGateway {
   private readonly logger = new Logger(SourceGateway.name);
@@ -83,6 +188,89 @@ export class SourceGateway extends ISourceGateway {
     return records.map((r) => this.mapper.toEntity(r));
   }
 
+  async findPage(
+    knowledgeId: string,
+    filter: ISourceFilter,
+  ): Promise<ISourcePage> {
+    const where = whereForFilter(knowledgeId, filter);
+    // Oldest first, same as findByKnowledgeId: an import appends at the end,
+    // so page 1 keeps showing the same rows while a bulk import is running.
+    const [records, total] = await this.prisma.$transaction([
+      this.prisma.source.findMany({
+        where,
+        orderBy: { createdAt: 'asc' },
+        skip: (filter.page - 1) * filter.perPage,
+        take: filter.perPage,
+      }),
+      this.prisma.source.count({ where }),
+    ]);
+    return {
+      items: records.map((r) => this.mapper.toEntity(r)),
+      total,
+      page: filter.page,
+      perPage: filter.perPage,
+    };
+  }
+
+  async findForExport(
+    knowledgeId: string,
+    selection: ISourceSelection,
+  ): Promise<ISourceData[]> {
+    // An explicit id list wins over the filter: the caller ticked specific
+    // rows, and re-deriving them from a filter that has since changed would
+    // export something else.
+    const where: Prisma.SourceWhereInput =
+      selection.ids && selection.ids.length > 0
+        ? { knowledgeId, id: { in: selection.ids } }
+        : whereForFilter(knowledgeId, selection);
+    const records = await this.prisma.source.findMany({
+      where,
+      orderBy: { createdAt: 'asc' },
+    });
+    return records.map((r) => this.mapper.toEntity(r));
+  }
+
+  async countByKnowledgeIds(
+    knowledgeIds: string[],
+  ): Promise<Map<string, ISourceCounts>> {
+    const counts = new Map<string, ISourceCounts>();
+    if (knowledgeIds.length === 0) return counts;
+
+    const groupCount = async (
+      extra: Prisma.SourceWhereInput,
+    ): Promise<Map<string, number>> => {
+      const rows = await this.prisma.source.groupBy({
+        by: ['knowledgeId'],
+        where: { knowledgeId: { in: knowledgeIds }, ...extra },
+        _count: { _all: true },
+      });
+      return new Map(rows.map((r) => [r.knowledgeId, r._count._all]));
+    };
+
+    const [total, indexed, failed, processing] = await Promise.all([
+      groupCount({}),
+      groupCount(whereForStatus('indexed')),
+      groupCount(whereForStatus('failed')),
+      // A stored handle with no `indexedAt` yet is the one state that means
+      // "LightRAG has it and is working on it". Rows never submitted have no
+      // handle, so they stay plain pending.
+      groupCount({
+        ...whereForStatus('pending'),
+        lightragDocId: { not: null },
+      }),
+    ]);
+
+    for (const [knowledgeId, count] of total) {
+      counts.set(knowledgeId, {
+        total: count,
+        indexed: indexed.get(knowledgeId) ?? 0,
+        failed: failed.get(knowledgeId) ?? 0,
+        processing: processing.get(knowledgeId) ?? 0,
+      });
+    }
+    return counts;
+  }
+
   async findById(id: string): Promise<ISourceData | null> {
     const record = await this.prisma.source.findUnique({ where: { id } });
     return record ? this.mapper.toEntity(record) : null;
@@ -180,6 +368,277 @@ export class SourceGateway extends ISourceGateway {
     await this.s3.delete(location);
   }
 
+  async readContent(source: ISourceData): Promise<ISourceContent> {
+    if (source.type === 'text') {
+      const text = source.content ?? '';
+      const body = Buffer.from(text, 'utf8');
+      return {
+        filename: source.name.endsWith('.txt')
+          ? source.name
+          : `${source.name}.txt`,
+        contentType: 'text/plain; charset=utf-8',
+        contentLength: body.length,
+        body: Readable.from([body]),
+      };
+    }
+    if (source.type === 'file') {
+      if (!source.url) {
+        throw new NotFoundException(`Source ${source.id} has no stored file`);
+      }
+      const location = S3Repository.parseUri(source.url);
+      const object = await this.s3.getObjectStream(location);
+      return {
+        filename: source.name,
+        // The row's mime type was captured at upload time and is what the
+        // browser needs to pick a viewer; the S3 header is a fallback.
+        contentType:
+          source.mimeType ?? object.contentType ?? 'application/octet-stream',
+        contentLength: object.contentLength,
+        body: object.body,
+      };
+    }
+    if (source.type === 'url') {
+      throw new BadRequestException(
+        'url sources have no stored content; open the url directly',
+      );
+    }
+    const exhaustive: never = source.type;
+    throw new BadRequestException(`Unknown source type: ${String(exhaustive)}`);
+  }
+
+  /**
+   * Ingest only enqueues: LightRAG hands back a track id and builds chunks,
+   * embeddings and the graph in a background pipeline afterwards. Storing that
+   * track id as proof of indexing is what let a knowledge base report `ready`
+   * while its graph stayed empty and every query came back without context.
+   *
+   * So submit everything first, then wait for the pipeline to reach a terminal
+   * state, and persist a doc id only for documents LightRAG reports as
+   * processed. Anything that fails or never finishes keeps `lightragDocId`
+   * null, which leaves `indexed` false so the next run retries it. Re-ingest
+   * is safe: LightRAG addresses documents by content hash, so resubmitting the
+   * same source converges on the same document instead of duplicating it.
+   */
+  async indexSources(sources: ISourceData[]): Promise<ISourceIndexOutcome[]> {
+    const outcomes = new Map<string, ISourceIndexOutcome>();
+    const inFlight = new Map<string, ISourceData>();
+
+    // One snapshot per base of everything its instance holds, indexed both
+    // ways: a rejected upload names either the original doc id or just the
+    // filename, and both have to lead back to a document. A batch is one
+    // base's in practice, but the cache keeps mixed batches correct.
+    const snapshots = new Map<string, IDocumentSnapshot>();
+    const snapshotFor = async (
+      knowledgeId: string,
+    ): Promise<IDocumentSnapshot> => {
+      const cached = snapshots.get(knowledgeId);
+      if (cached) return cached;
+      const snapshot = await this.snapshotDocuments(knowledgeId);
+      snapshots.set(knowledgeId, snapshot);
+      return snapshot;
+    };
+
+    for (const source of sources) {
+      const known = await snapshotFor(source.knowledgeId);
+      const existing = await this.checkExistingIndex(source, known.byId);
+
+      if (existing.kind === 'indexed') {
+        // A row that never got its stamp is the whole reason this branch
+        // writes at all. When a run stops waiting it leaves the source pending
+        // with a handle; LightRAG finishes minutes later; and every run after
+        // that recognised the document as processed but recorded nothing, so
+        // the source sat at `pending` forever and the base never reached
+        // "N of N". Stamping here is what makes the count converge.
+        // A row that is already stamped and clean needs no write - on a base
+        // of a few hundred sources that would be a few hundred pointless
+        // updates per run.
+        const needsStamp =
+          source.indexedAt === null || source.indexError !== null;
+        outcomes.set(
+          source.id,
+          needsStamp
+            ? await this.succeed(source, existing.docId)
+            : this.indexed(source),
+        );
+        continue;
+      }
+      if (existing.kind === 'inFlight') {
+        // Already moving through the pipeline. Re-uploading here is what made
+        // LightRAG answer 409 "Document storage already contains ..." for
+        // every source when an index run overlapped a reprocess.
+        inFlight.set(existing.trackId, source);
+        continue;
+      }
+      if (existing.kind === 'unknown') {
+        // Could not reach LightRAG to verify a claim we still hold. The row
+        // keeps its doc id (it may well be fine), so writing an error here
+        // would be invisible behind an "indexed" status; report it for this
+        // run's summary only.
+        outcomes.set(source.id, this.failed(source, existing.error));
+        continue;
+      }
+
+      try {
+        const trackId = await this.ingestByType(source);
+        // Persist the handle before waiting on it. If this run dies (deploy,
+        // crash, budget) the next one resumes from here instead of uploading
+        // the same file again.
+        await this.rememberHandle(source.id, trackId);
+        inFlight.set(trackId, source);
+      } catch (err) {
+        const message = errorMessage(err);
+
+        // LightRAG refuses an upload whose filename it already stores, and
+        // says so with the filename only. Whether that is good news depends on
+        // the stored document: processed means the content is searchable and
+        // Ranch merely lost the id, still-moving means we should wait for it
+        // rather than call the source broken.
+        const stored = this.resolveStoredByName(message, known.byName);
+        if (stored?.status === 'processed') {
+          outcomes.set(source.id, await this.succeed(source, stored.id));
+          continue;
+        }
+        if (stored !== null && stored.status !== 'failed') {
+          inFlight.set(stored.id, source);
+          continue;
+        }
+
+        outcomes.set(source.id, await this.fail(source, message));
+      }
+    }
+
+    await this.awaitProcessing(inFlight, outcomes);
+
+    const results: ISourceIndexOutcome[] = [];
+    for (const s of sources) {
+      results.push(
+        outcomes.get(s.id) ??
+          (await this.fail(s, 'LightRAG reported no state for this document')),
+      );
+    }
+    return results;
+  }
+
+  async findUnconfirmed(): Promise<ISourceData[]> {
+    const records = await this.prisma.source.findMany({
+      where: {
+        lightragDocId: { not: null },
+        indexedAt: null,
+        indexError: null,
+      },
+      orderBy: { createdAt: 'asc' },
+    });
+    return records.map((r) => this.mapper.toEntity(r));
+  }
+
+  /**
+   * One pass over documents LightRAG already holds. Deliberately narrower than
+   * `indexSources`: it never uploads and never waits, so it is safe to run on a
+   * timer. Anything still moving is left for the next pass; anything LightRAG
+   * has lost keeps its row untouched and waits for a real index run to re-send
+   * it.
+   */
+  async confirmProcessed(
+    sources: ISourceData[],
+  ): Promise<ISourceIndexOutcome[]> {
+    if (sources.length === 0) return [];
+    // The reconcile pass sweeps across every knowledge, so snapshot each
+    // base's instance once and reuse it for that base's sources.
+    const snapshots = new Map<string, IDocumentSnapshot>();
+    const outcomes: ISourceIndexOutcome[] = [];
+
+    for (const source of sources) {
+      let known = snapshots.get(source.knowledgeId);
+      if (!known) {
+        known = await this.snapshotDocuments(source.knowledgeId);
+        snapshots.set(source.knowledgeId, known);
+      }
+      const existing = await this.checkExistingIndex(source, known.byId);
+      if (existing.kind === 'indexed') {
+        outcomes.push(await this.succeed(source, existing.docId));
+        continue;
+      }
+      if (existing.kind === 'inFlight') {
+        outcomes.push(
+          this.stillProcessing(source, 'still in LightRAG pipeline'),
+        );
+        continue;
+      }
+      // 'stale' or 'unknown'. Neither is this pass's business: re-sending a
+      // document is what the Index action is for, and an unreachable LightRAG
+      // resolves itself. Report without writing.
+      outcomes.push(
+        this.failed(
+          source,
+          existing.kind === 'unknown'
+            ? existing.error
+            : 'LightRAG no longer holds this document',
+        ),
+      );
+    }
+    return outcomes;
+  }
+
+  private failed(source: ISourceData, error: string): ISourceIndexOutcome {
+    return {
+      sourceId: source.id,
+      name: source.name,
+      status: 'failed',
+      indexed: false,
+      error,
+    };
+  }
+
+  private stillProcessing(
+    source: ISourceData,
+    reason: string,
+  ): ISourceIndexOutcome {
+    return {
+      sourceId: source.id,
+      name: source.name,
+      status: 'pending',
+      indexed: false,
+      error: reason,
+    };
+  }
+
+  private indexed(source: ISourceData): ISourceIndexOutcome {
+    return {
+      sourceId: source.id,
+      name: source.name,
+      status: 'indexed',
+      indexed: true,
+      error: null,
+    };
+  }
+
+  /**
+   * Records the outcome on the row so the sources table can show what
+   * happened to each document, then returns the outcome for the run summary.
+   * `succeed` also stores the doc id, which is what flips `indexed`.
+   */
+  private async succeed(
+    source: ISourceData,
+    docId: string,
+  ): Promise<ISourceIndexOutcome> {
+    await this.prisma.source.update({
+      where: { id: source.id },
+      data: {
+        lightragDocId: docId,
+        indexState: 'indexed',
+        indexedAt: new Date(),
+        indexError: null,
+      },
+    });
+    return this.indexed(source);
+  }
+
+  /**
+   * Hands one source to the retrieval service and marks it processing. The
+   * per-source path (migration, single-source retry); batch runs go through
+   * `indexSources`, which additionally reconciles duplicates and budgets its
+   * wait.
+   */
   async indexSource(source: ISourceData): Promise<void> {
     await this.updateIndexState(source.id, {
       indexState: 'processing',
@@ -191,14 +650,247 @@ export class SourceGateway extends ISourceGateway {
     } catch (err) {
       await this.updateIndexState(source.id, {
         indexState: 'failed',
-        indexError: err instanceof Error ? err.message : String(err),
+        indexError: errorMessage(err),
       });
       throw err;
     }
+    await this.rememberHandle(source.id, docId);
+  }
+
+  private async fail(
+    source: ISourceData,
+    error: string,
+  ): Promise<ISourceIndexOutcome> {
+    await this.prisma.source.update({
+      where: { id: source.id },
+      data: { indexState: 'failed', indexError: error },
+    });
+    return this.failed(source, error);
+  }
+
+  /**
+   * The document is in LightRAG's pipeline and this run stopped waiting for
+   * it. Storing the handle is what makes the next run resume the wait instead
+   * of re-uploading the file and colliding with the copy already in there; the
+   * row stays `pending` because `indexedAt` is untouched, and any error from
+   * an earlier attempt goes away since nothing is wrong with it right now.
+   */
+  private async markInFlight(
+    source: ISourceData,
+    handle: string,
+    reason: string,
+  ): Promise<ISourceIndexOutcome> {
     await this.prisma.source.update({
       where: { id: source.id },
-      data: { lightragDocId: docId },
+      data: {
+        lightragDocId: handle,
+        indexState: 'processing',
+        indexError: null,
+      },
     });
+    return this.stillProcessing(source, reason);
+  }
+
+  private async clearError(sourceId: string): Promise<void> {
+    await this.prisma.source.update({
+      where: { id: sourceId },
+      data: { indexError: null },
+    });
+  }
+
+  private async snapshotDocuments(
+    knowledgeId: string,
+  ): Promise<IDocumentSnapshot> {
+    const empty: IDocumentSnapshot = { byId: new Map(), byName: new Map() };
+    try {
+      const documents = await this.lightrag.listDocuments(knowledgeId);
+      const snapshot: IDocumentSnapshot = {
+        byId: new Map(),
+        byName: new Map(),
+      };
+      for (const doc of documents) {
+        snapshot.byId.set(doc.id, doc.status);
+        if (doc.filePath !== null) {
+          snapshot.byName.set(normalizeName(doc.filePath), doc);
+        }
+      }
+      return snapshot;
+    } catch (err) {
+      // Not fatal: the per-source track lookups still work, the snapshot only
+      // helps reconcile documents Ranch has lost the id for.
+      this.logger.warn(`listDocuments failed: ${errorMessage(err)}`);
+      return empty;
+    }
+  }
+
+  /**
+   * Pulls the filename out of LightRAG's refusal and returns the document it
+   * refers to, status included. The caller decides what that status is worth:
+   * a processed document can be adopted outright, one still in the pipeline is
+   * worth waiting for, and a failed one is left to be reported.
+   */
+  private resolveStoredByName(
+    message: string,
+    byName: Map<string, IDocumentRecord>,
+  ): IDocumentRecord | null {
+    const match = ALREADY_STORED.exec(message);
+    if (match === null) return null;
+    return byName.get(normalizeName(match[1])) ?? null;
+  }
+
+  /** Stores the resume handle without claiming the document is searchable. */
+  private async rememberHandle(
+    sourceId: string,
+    handle: string,
+  ): Promise<void> {
+    await this.prisma.source.update({
+      where: { id: sourceId },
+      data: { lightragDocId: handle, indexState: 'processing' },
+    });
+  }
+
+  /**
+   * Classifies what LightRAG currently knows about a source that claims to be
+   * indexed. The distinction that matters is between "gone or failed" (re-send
+   * it) and "still in the pipeline" (wait for it) - conflating the two made an
+   * index run fight an in-progress reprocess.
+   */
+  private async checkExistingIndex(
+    source: ISourceData,
+    known: Map<string, DocumentProcessingStatusTypes>,
+  ): Promise<IExistingIndexCheck> {
+    // Ask about any source that carries a handle, not only ones we call
+    // indexed: the handle is written at ingest time, so a source left pending
+    // by an earlier run has one too, and that is exactly the case where
+    // re-uploading would collide with the copy already in the pipeline.
+    const record = await this.prisma.source.findUnique({
+      where: { id: source.id },
+      select: { lightragDocId: true },
+    });
+    const storedId = record?.lightragDocId ?? null;
+    if (storedId === null) return { kind: 'stale' };
+
+    try {
+      const status = await this.lightrag.getTrackStatus(
+        source.knowledgeId,
+        storedId,
+      );
+      const statuses =
+        status.documents.length > 0
+          ? status.documents.map((d) => d.status)
+          : // Not a track id LightRAG knows. It may be a doc id adopted from a
+            // duplicate rejection, so fall back to the snapshot.
+            this.statusesFromSnapshot(storedId, known);
+
+      if (statuses.length === 0) {
+        await this.forgetDocId(source.id);
+        return { kind: 'stale' };
+      }
+      if (statuses.every((s) => s === 'processed')) {
+        return { kind: 'indexed', docId: storedId };
+      }
+      if (statuses.some((s) => s === 'pending' || s === 'processing')) {
+        return { kind: 'inFlight', trackId: storedId };
+      }
+    } catch (err) {
+      // Cannot tell either way, so keep the existing claim and report the
+      // source as unverified for this run rather than re-ingesting blindly.
+      return { kind: 'unknown', error: errorMessage(err) };
+    }
+
+    // Failed, or a state we do not treat as in flight: drop the claim so this
+    // run re-sends it.
+    await this.forgetDocId(source.id);
+    return { kind: 'stale' };
+  }
+
+  private statusesFromSnapshot(
+    docId: string,
+    known: Map<string, DocumentProcessingStatusTypes>,
+  ): DocumentProcessingStatusTypes[] {
+    const status = known.get(docId);
+    return status ? [status] : [];
+  }
+
+  private async forgetDocId(sourceId: string): Promise<void> {
+    await this.prisma.source.update({
+      where: { id: sourceId },
+      data: { lightragDocId: null },
+    });
+  }
+
+  private async awaitProcessing(
+    inFlight: Map<string, ISourceData>,
+    outcomes: Map<string, ISourceIndexOutcome>,
+  ): Promise<void> {
+    if (inFlight.size === 0) return;
+
+    const budgetMs = indexBudgetMs([...inFlight.values()]);
+    const deadline = Date.now() + budgetMs;
+
+    while (inFlight.size > 0 && Date.now() < deadline) {
+      // Recomputed each tick: the batch shrinks as documents land, so a run
+      // speeds back up towards the 3 s floor as it nears the end.
+      await sleep(pollIntervalMs(inFlight.size));
+
+      for (const [trackId, source] of [...inFlight]) {
+        try {
+          const status = await this.lightrag.getTrackStatus(
+            source.knowledgeId,
+            trackId,
+          );
+          if (status.documents.length === 0) continue;
+
+          const failure = status.documents.find((d) => d.status === 'failed');
+          if (failure) {
+            inFlight.delete(trackId);
+
+            // LightRAG deduplicates by content hash. When the same text is
+            // already stored under another filename it refuses the upload and
+            // names the original. If that original is processed the content is
+            // searchable, so adopt its id rather than reporting a failure the
+            // next run would only reproduce.
+            const adopted = adoptableDocId(failure.errorMessage);
+            if (adopted !== null) {
+              outcomes.set(source.id, await this.succeed(source, adopted));
+              continue;
+            }
+
+            outcomes.set(
+              source.id,
+              await this.fail(
+                source,
+                failure.errorMessage ?? 'LightRAG failed to process it',
+              ),
+            );
+            continue;
+          }
+
+          if (status.documents.every((d) => d.status === 'processed')) {
+            inFlight.delete(trackId);
+            outcomes.set(source.id, await this.succeed(source, trackId));
+          }
+        } catch (err) {
+          // Transient read failure. Leave it in flight and retry next tick;
+          // the deadline is what stops an endlessly unreachable LightRAG.
+          this.logger.warn(
+            `track_status(${trackId}) failed: ${errorMessage(err)}`,
+          );
+        }
+      }
+    }
+
+    const waitedMinutes = Math.round(budgetMs / 60000);
+    for (const [handle, source] of inFlight) {
+      outcomes.set(
+        source.id,
+        await this.markInFlight(
+          source,
+          handle,
+          `still processing after ${waitedMinutes} min - the next index run will pick it up`,
+        ),
+      );
+    }
   }
 
   async waitForSourceIndexed(sourceId: string): Promise<ISourceData> {
@@ -216,18 +908,26 @@ export class SourceGateway extends ISourceGateway {
         record.knowledgeId,
         record.lightragDocId,
       );
-      if (track.status === 'processed') {
+      // One track id can cover several documents (an archive upload); the
+      // source is indexed only when every one of them is processed, failed as
+      // soon as any is. An empty answer means LightRAG has not registered the
+      // track yet - keep waiting.
+      const failure = track.documents.find((d) => d.status === 'failed');
+      if (failure) {
         await this.updateIndexState(sourceId, {
-          indexState: 'indexed',
-          indexError: null,
-          indexedAt: new Date(),
+          indexState: 'failed',
+          indexError: failure.errorMessage ?? 'processing failed',
         });
         return this.requireEntity(sourceId);
       }
-      if (track.status === 'failed') {
+      if (
+        track.documents.length > 0 &&
+        track.documents.every((d) => d.status === 'processed')
+      ) {
         await this.updateIndexState(sourceId, {
-          indexState: 'failed',
-          indexError: track.error ?? 'processing failed',
+          indexState: 'indexed',
+          indexError: null,
+          indexedAt: new Date(),
         });
         return this.requireEntity(sourceId);
       }
diff --git a/api/src/slices/reins/source/data/source.mapper.spec.ts b/api/src/slices/reins/source/data/source.mapper.spec.ts
new file mode 100644
index 00000000..b396c0b4
--- /dev/null
+++ b/api/src/slices/reins/source/data/source.mapper.spec.ts
@@ -0,0 +1,32 @@
+import { deriveIndexStatus } from './source.mapper';
+
+describe('deriveIndexStatus', () => {
+  it('is indexed once processing was confirmed, even with a stale error', () => {
+    // LightRAG confirmed the content is searchable; an older error must not
+    // paint the row red.
+    expect(
+      deriveIndexStatus({ indexedAt: new Date(), indexError: 'old' }),
+    ).toBe('indexed');
+  });
+
+  it('is failed when the last run recorded an error and nothing succeeded', () => {
+    expect(
+      deriveIndexStatus({ indexedAt: null, indexError: 'rejected' }),
+    ).toBe('failed');
+  });
+
+  it('is pending when nothing has been confirmed and nothing failed', () => {
+    expect(deriveIndexStatus({ indexedAt: null, indexError: null })).toBe(
+      'pending',
+    );
+  });
+
+  it('stays pending while a document sits in the pipeline with a handle', () => {
+    // The row carries lightragDocId as a resume handle from ingest time, which
+    // deriveIndexStatus deliberately ignores: only indexedAt proves the
+    // document is searchable.
+    expect(deriveIndexStatus({ indexedAt: null, indexError: null })).toBe(
+      'pending',
+    );
+  });
+});
diff --git a/api/src/slices/reins/source/data/source.mapper.ts b/api/src/slices/reins/source/data/source.mapper.ts
index 24b41145..6e31ddec 100644
--- a/api/src/slices/reins/source/data/source.mapper.ts
+++ b/api/src/slices/reins/source/data/source.mapper.ts
@@ -3,6 +3,7 @@ import type { Source as PrismaSource, Prisma } from '@prisma/client';
 import {
   ISourceData,
   ICreateSourceData,
+  SourceIndexStatusTypes,
   SourceIndexStateTypes,
   SourceTypes,
 } from '../domain/source.types';
@@ -24,6 +25,23 @@ function parseSourceType(value: string): SourceTypes {
   return isSourceType(value) ? value : 'text';
 }
 
+/**
+ * `indexedAt` is the only proof that LightRAG finished the document, and it
+ * wins over any leftover error from an earlier run. `lightragDocId` is
+ * deliberately NOT consulted: it is written as soon as ingest is accepted so a
+ * later run can resume the wait instead of re-uploading, which means a row can
+ * hold an id while the pipeline is still chewing. Treating that id as proof is
+ * what showed a base as fully indexed while its graph was still being built.
+ */
+export function deriveIndexStatus(record: {
+  indexedAt: Date | null;
+  indexError: string | null;
+}): SourceIndexStatusTypes {
+  if (record.indexedAt !== null) return 'indexed';
+  if (record.indexError !== null) return 'failed';
+  return 'pending';
+}
+
 function parseIndexState(value: string): SourceIndexStateTypes {
   return (INDEX_STATES as readonly string[]).includes(value)
     ? (value as SourceIndexStateTypes)
@@ -33,6 +51,7 @@ function parseIndexState(value: string): SourceIndexStateTypes {
 @Injectable()
 export class SourceMapper {
   toEntity(record: PrismaSource): ISourceData {
+    const indexStatus = deriveIndexStatus(record);
     return {
       id: record.id,
       knowledgeId: record.knowledgeId,
@@ -42,6 +61,8 @@ export class SourceMapper {
       mimeType: record.mimeType ?? null,
       content: record.content ?? null,
       sizeBytes: record.sizeBytes ?? null,
+      indexed: indexStatus === 'indexed',
+      indexStatus,
       indexState: parseIndexState(record.indexState),
       indexError: record.indexError ?? null,
       indexedAt: record.indexedAt ?? null,
diff --git a/api/src/slices/reins/source/data/sourceArchive.writer.spec.ts b/api/src/slices/reins/source/data/sourceArchive.writer.spec.ts
new file mode 100644
index 00000000..d8f3a2d7
--- /dev/null
+++ b/api/src/slices/reins/source/data/sourceArchive.writer.spec.ts
@@ -0,0 +1,153 @@
+import { Writable } from 'stream';
+import * as unzipper from 'unzipper';
+import { parse } from 'yaml';
+import {
+  EXPORT_MANIFEST_NAME,
+  entryNameFor,
+  writeSourceArchive,
+} from './sourceArchive.writer';
+import { isIngestableEntry } from './archive.extractor';
+import { ISourceData } from '../domain/source.types';
+
+function makeSource(over: Partial<ISourceData> = {}): ISourceData {
+  return {
+    id: 'source-1',
+    knowledgeId: 'knowledge-1',
+    type: 'file',
+    name: 'manual.md',
+    url: 's3://bucket/key',
+    mimeType: 'text/markdown',
+    content: null,
+    sizeBytes: 10,
+    indexed: true,
+    indexStatus: 'indexed',
+    indexState: 'indexed',
+    indexError: null,
+    indexedAt: new Date(0),
+    createdAt: new Date(0),
+    updatedAt: new Date(0),
+    ...over,
+  };
+}
+
+function collect(): { out: Writable; done: Promise<Buffer> } {
+  const chunks: Buffer[] = [];
+  let resolve!: (b: Buffer) => void;
+  const done = new Promise<Buffer>((r) => {
+    resolve = r;
+  });
+  const out = new Writable({
+    write(chunk: Buffer, _enc, cb) {
+      chunks.push(chunk);
+      cb();
+    },
+    final(cb) {
+      resolve(Buffer.concat(chunks));
+      cb();
+    },
+  });
+  return { out, done };
+}
+
+async function zipEntries(zip: Buffer): Promise<Record<string, string>> {
+  const dir = await unzipper.Open.buffer(zip);
+  const out: Record<string, string> = {};
+  for (const file of dir.files) {
+    out[file.path] = (await file.buffer()).toString('utf8');
+  }
+  return out;
+}
+
+const readBytes = (s: ISourceData) =>
+  Promise.resolve({ body: Buffer.from(`bytes of ${s.id}`) });
+
+describe('entryNameFor', () => {
+  it('suffixes a repeated name instead of losing one of them', () => {
+    const taken = new Set<string>();
+    expect(entryNameFor({ type: 'file', name: 'manual.md' }, taken)).toBe(
+      'manual.md',
+    );
+    // Nothing enforces unique source names, so this is a real collision, not a
+    // hypothetical one - and a zip cannot hold two entries with one name.
+    expect(entryNameFor({ type: 'file', name: 'manual.md' }, taken)).toBe(
+      'manual (2).md',
+    );
+    expect(entryNameFor({ type: 'file', name: 'manual.md' }, taken)).toBe(
+      'manual (3).md',
+    );
+  });
+
+  it('gives a text source a markdown extension, but does not double one', () => {
+    const taken = new Set<string>();
+    expect(entryNameFor({ type: 'text', name: 'notes' }, taken)).toBe(
+      'notes.md',
+    );
+    expect(entryNameFor({ type: 'text', name: 'other.md' }, taken)).toBe(
+      'other.md',
+    );
+  });
+});
+
+describe('writeSourceArchive', () => {
+  it('writes file and text sources as entries and lists them in the manifest', async () => {
+    const { out, done } = collect();
+    await writeSourceArchive(
+      'knowledge-1',
+      [
+        makeSource({ id: 'a', name: 'manual.md' }),
+        makeSource({ id: 'b', type: 'text', name: 'notes', content: 'hi' }),
+      ],
+      readBytes,
+      out,
+    );
+
+    const entries = await zipEntries(await done);
+    expect(Object.keys(entries).sort()).toEqual([
+      EXPORT_MANIFEST_NAME,
+      'manual.md',
+      'notes.md',
+    ]);
+    expect(entries['manual.md']).toBe('bytes of a');
+
+    const manifest = parse(entries[EXPORT_MANIFEST_NAME]) as {
+      knowledgeId: string;
+      sources: { name: string; type: string; entry?: string }[];
+    };
+    expect(manifest.knowledgeId).toBe('knowledge-1');
+    expect(manifest.sources).toEqual([
+      { name: 'manual.md', type: 'file', entry: 'manual.md' },
+      { name: 'notes', type: 'text', entry: 'notes.md' },
+    ]);
+  });
+
+  it('records url sources in the manifest without inventing a file for them', async () => {
+    const { out, done } = collect();
+    await writeSourceArchive(
+      'knowledge-1',
+      [
+        makeSource({
+          id: 'u',
+          type: 'url',
+          name: 'Pricing page',
+          url: 'https://example.com/pricing',
+        }),
+      ],
+      () => Promise.reject(new Error('url sources must not be read')),
+      out,
+    );
+
+    const entries = await zipEntries(await done);
+    expect(Object.keys(entries)).toEqual([EXPORT_MANIFEST_NAME]);
+    const manifest = parse(entries[EXPORT_MANIFEST_NAME]) as {
+      sources: { url?: string }[];
+    };
+    expect(manifest.sources[0].url).toBe('https://example.com/pricing');
+  });
+
+  it('names the manifest so re-importing the zip skips it', () => {
+    // Checked against the importer's own predicate, not a copy of its
+    // extension list: the round trip only holds while these two agree, and a
+    // duplicated list would drift silently.
+    expect(isIngestableEntry(EXPORT_MANIFEST_NAME, 1024)).toBe(false);
+  });
+});
diff --git a/api/src/slices/reins/source/data/sourceArchive.writer.ts b/api/src/slices/reins/source/data/sourceArchive.writer.ts
new file mode 100644
index 00000000..9757ebfc
--- /dev/null
+++ b/api/src/slices/reins/source/data/sourceArchive.writer.ts
@@ -0,0 +1,131 @@
+// @scope:api
+// @slice:reins/source
+// @layer:data
+// @type:utility
+
+import * as archiver from 'archiver';
+import * as path from 'path';
+import { Readable, Writable } from 'stream';
+import { stringify } from 'yaml';
+import { ISourceData } from '../domain/source.types';
+
+/**
+ * Sits at the zip root and describes what was exported. The extension is load
+ * bearing: `.yaml` is not in the importer's supported list, so re-uploading an
+ * exported zip through `from-archive` skips this file instead of turning the
+ * manifest into a source. `sourceArchive.writer.spec.ts` pins that against
+ * `isIngestableEntry` itself rather than a copy of the list.
+ */
+export const EXPORT_MANIFEST_NAME = '_ranch-export.yaml';
+
+/** Text sources have no extension of their own; they land as markdown. */
+const TEXT_EXTENSION = '.md';
+
+export interface ISourceBytes {
+  /** Consumed exactly once by the archiver. */
+  body: Readable | Buffer;
+}
+
+export type SourceReader = (source: ISourceData) => Promise<ISourceBytes>;
+
+/**
+ * The name a source takes inside the zip, made unique against everything
+ * already placed. Two sources can legitimately share a name - nothing enforces
+ * uniqueness on create - and a zip cannot hold both, so the later one gets a
+ * ` (2)` before its extension the way a file manager would.
+ */
+export function entryNameFor(
+  source: Pick<ISourceData, 'type' | 'name'>,
+  taken: Set<string>,
+): string {
+  const base =
+    source.type === 'text' && path.extname(source.name) === ''
+      ? `${source.name}${TEXT_EXTENSION}`
+      : source.name;
+
+  if (!taken.has(base)) {
+    taken.add(base);
+    return base;
+  }
+
+  const ext = path.extname(base);
+  const stem = ext ? base.slice(0, -ext.length) : base;
+  for (let n = 2; ; n += 1) {
+    const candidate = `${stem} (${n})${ext}`;
+    if (!taken.has(candidate)) {
+      taken.add(candidate);
+      return candidate;
+    }
+  }
+}
+
+interface IManifestEntry {
+  name: string;
+  type: string;
+  entry?: string;
+  url?: string;
+}
+
+export function buildManifest(
+  knowledgeId: string,
+  entries: readonly IManifestEntry[],
+): string {
+  return stringify({
+    knowledgeId,
+    exportedSources: entries.length,
+    // No timestamp on purpose: it would make two exports of the same base
+    // differ byte for byte, which breaks the "did anything change" check
+    // people reach for when a migration looks wrong.
+    sources: entries,
+  });
+}
+
+/**
+ * Streams the selected sources into `out` as a zip.
+ *
+ * One source is read at a time and handed straight to the archiver, so peak
+ * memory is one source rather than the whole base - the same discipline the
+ * archive *importer* follows. `url` sources have no bytes and appear only in
+ * the manifest.
+ */
+export async function writeSourceArchive(
+  knowledgeId: string,
+  sources: readonly ISourceData[],
+  read: SourceReader,
+  out: Writable,
+): Promise<void> {
+  const archive = archiver('zip', { zlib: { level: 9 } });
+  const finished = new Promise<void>((resolve, reject) => {
+    archive.on('error', reject);
+    out.on('error', reject);
+    out.on('close', resolve);
+    out.on('finish', resolve);
+  });
+  archive.pipe(out);
+
+  const taken = new Set<string>();
+  const manifest: IManifestEntry[] = [];
+
+  for (const source of sources) {
+    if (source.type === 'url') {
+      manifest.push({
+        name: source.name,
+        type: source.type,
+        url: source.url ?? '',
+      });
+      continue;
+    }
+
+    const entry = entryNameFor(source, taken);
+    const { body } = await read(source);
+    archive.append(body, { name: entry });
+    manifest.push({ name: source.name, type: source.type, entry });
+  }
+
+  archive.append(buildManifest(knowledgeId, manifest), {
+    name: EXPORT_MANIFEST_NAME,
+  });
+
+  await archive.finalize();
+  await finished;
+}
diff --git a/api/src/slices/reins/source/domain/archiveLimit.ts b/api/src/slices/reins/source/domain/archiveLimit.ts
new file mode 100644
index 00000000..7e6fdf6e
--- /dev/null
+++ b/api/src/slices/reins/source/domain/archiveLimit.ts
@@ -0,0 +1,15 @@
+// Ceiling for one uploaded zip. The archive streams to disk, never to memory,
+// so this guards ephemeral storage on the API pod rather than RAM; 4 GiB is
+// comfortably above any documentation set seen so far while still refusing
+// an accidental multi-terabyte upload.
+const DEFAULT_ARCHIVE_MAX_BYTES = 4 * 1024 * 1024 * 1024;
+
+export function archiveMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env.KNOWLEDGE_ARCHIVE_MAX_BYTES;
+  if (raw === undefined || raw.trim() === '') return DEFAULT_ARCHIVE_MAX_BYTES;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_ARCHIVE_MAX_BYTES;
+  }
+  return Math.floor(parsed);
+}
diff --git a/api/src/slices/reins/source/domain/importJob.registry.spec.ts b/api/src/slices/reins/source/domain/importJob.registry.spec.ts
new file mode 100644
index 00000000..a8c11056
--- /dev/null
+++ b/api/src/slices/reins/source/domain/importJob.registry.spec.ts
@@ -0,0 +1,93 @@
+import { ImportJobRegistry } from './importJob.registry';
+
+const HOUR_MS = 60 * 60 * 1000;
+
+describe('ImportJobRegistry', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.setSystemTime(new Date('2026-08-17T10:00:00Z'));
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('accumulates counters and caps the recorded errors', () => {
+    const registry = new ImportJobRegistry();
+    const job = registry.create('k-1', 'archive', 30);
+
+    registry.progress(job.id, { added: 5 });
+    registry.progress(job.id, { added: 2, skipped: 1 });
+    for (let i = 0; i < 25; i += 1) {
+      registry.progress(job.id, { failed: 1, error: `f${i}: boom` });
+    }
+
+    const stored = registry.get(job.id);
+    expect(stored).toMatchObject({
+      status: 'running',
+      detected: 30,
+      added: 7,
+      skipped: 1,
+      failed: 25,
+      finishedAt: null,
+    });
+    // The UI shows the first few reasons; the rest is only a count.
+    expect(stored?.errors).toHaveLength(20);
+    expect(stored?.errors[0]).toBe('f0: boom');
+  });
+
+  it('lists jobs of one knowledge oldest first', () => {
+    const registry = new ImportJobRegistry();
+    const first = registry.create('k-1', 'archive', 1);
+    jest.setSystemTime(new Date('2026-08-17T10:00:01Z'));
+    const second = registry.create('k-1', 'archive', 2);
+    registry.create('k-2', 'archive', 3);
+
+    expect(registry.listByKnowledge('k-1').map((j) => j.id)).toEqual([
+      first.id,
+      second.id,
+    ]);
+  });
+
+  it('forgets finished jobs after an hour but keeps running ones', () => {
+    const registry = new ImportJobRegistry();
+    const done = registry.create('k-1', 'archive', 1);
+    const running = registry.create('k-1', 'archive', 1);
+    registry.finish(done.id, 'done');
+
+    jest.setSystemTime(new Date(Date.now() + HOUR_MS + 1000));
+
+    // Pruning happens on the next read/create, no timers to leak.
+    expect(registry.listByKnowledge('k-1').map((j) => j.id)).toEqual([
+      running.id,
+    ]);
+    expect(registry.get(done.id)).toBeNull();
+  });
+
+  it('records the terminal reason when an import crashes', () => {
+    const registry = new ImportJobRegistry();
+    const job = registry.create('k-1', 'archive', 4);
+
+    registry.finish(job.id, 'failed', 'archive import crashed: disk full');
+
+    expect(registry.get(job.id)).toMatchObject({
+      status: 'failed',
+      errors: ['archive import crashed: disk full'],
+    });
+    expect(registry.get(job.id)?.finishedAt).toBeInstanceOf(Date);
+  });
+
+  it('keeps the terminal reason even when the per-entry error cap is full', () => {
+    const registry = new ImportJobRegistry();
+    const job = registry.create('k-1', 'archive', 40);
+    for (let i = 0; i < 30; i += 1) {
+      registry.progress(job.id, { failed: 1, error: `f${i}: boom` });
+    }
+
+    registry.finish(job.id, 'failed', 'archive import crashed: disk full');
+
+    const errors = registry.get(job.id)?.errors ?? [];
+    expect(errors).toHaveLength(21);
+    expect(errors.at(-1)).toBe('archive import crashed: disk full');
+  });
+});
diff --git a/api/src/slices/reins/source/domain/importJob.registry.ts b/api/src/slices/reins/source/domain/importJob.registry.ts
new file mode 100644
index 00000000..ddb7d287
--- /dev/null
+++ b/api/src/slices/reins/source/domain/importJob.registry.ts
@@ -0,0 +1,92 @@
+import { Injectable } from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import { IImportJob } from './source.types';
+
+// Finished jobs linger long enough for whoever started the import to come
+// back and read the totals, then go. Nothing else references them.
+const RETAIN_FINISHED_MS = 60 * 60 * 1000;
+const MAX_ERRORS = 20;
+
+export interface IImportJobProgress {
+  added?: number;
+  skipped?: number;
+  failed?: number;
+  /** Appended, not replaced; capped at MAX_ERRORS. */
+  error?: string;
+}
+
+/**
+ * In-memory ledger of background bulk imports so the sources page can show
+ * "120 / 447 added" instead of asking the user to refresh and guess. Not
+ * persisted on purpose: an import runs inside this process and dies with it,
+ * so a stored job would only ever describe work that is no longer happening.
+ */
+@Injectable()
+export class ImportJobRegistry {
+  private readonly jobs = new Map<string, IImportJob>();
+
+  create(
+    knowledgeId: string,
+    kind: IImportJob['kind'],
+    detected: number,
+  ): IImportJob {
+    this.prune();
+    const job: IImportJob = {
+      id: `import-${randomUUID()}`,
+      knowledgeId,
+      kind,
+      status: 'running',
+      detected,
+      added: 0,
+      skipped: 0,
+      failed: 0,
+      errors: [],
+      startedAt: new Date(),
+      finishedAt: null,
+    };
+    this.jobs.set(job.id, job);
+    return job;
+  }
+
+  progress(jobId: string, patch: IImportJobProgress): void {
+    const job = this.jobs.get(jobId);
+    if (!job) return;
+    if (patch.added !== undefined) job.added += patch.added;
+    if (patch.skipped !== undefined) job.skipped += patch.skipped;
+    if (patch.failed !== undefined) job.failed += patch.failed;
+    if (patch.error !== undefined && job.errors.length < MAX_ERRORS) {
+      job.errors.push(patch.error);
+    }
+  }
+
+  finish(jobId: string, status: 'done' | 'failed', error?: string): void {
+    const job = this.jobs.get(jobId);
+    if (!job) return;
+    job.status = status;
+    job.finishedAt = new Date();
+    // The terminal reason always lands, even when per-entry errors already
+    // filled the cap: a job that shows "failed" with no explanation is worse
+    // than one line over.
+    if (error !== undefined) job.errors.push(error);
+  }
+
+  get(jobId: string): IImportJob | null {
+    return this.jobs.get(jobId) ?? null;
+  }
+
+  listByKnowledge(knowledgeId: string): IImportJob[] {
+    this.prune();
+    return [...this.jobs.values()]
+      .filter((j) => j.knowledgeId === knowledgeId)
+      .sort((a, b) => a.startedAt.getTime() - b.startedAt.getTime());
+  }
+
+  private prune(): void {
+    const cutoff = Date.now() - RETAIN_FINISHED_MS;
+    for (const [id, job] of this.jobs) {
+      if (job.finishedAt !== null && job.finishedAt.getTime() < cutoff) {
+        this.jobs.delete(id);
+      }
+    }
+  }
+}
diff --git a/api/src/slices/reins/source/domain/indexBudget.spec.ts b/api/src/slices/reins/source/domain/indexBudget.spec.ts
new file mode 100644
index 00000000..7b90e945
--- /dev/null
+++ b/api/src/slices/reins/source/domain/indexBudget.spec.ts
@@ -0,0 +1,97 @@
+import {
+  indexBudgetMs,
+  pollIntervalMs,
+  staleIndexAfterMs,
+} from './indexBudget';
+
+const MINUTE = 60 * 1000;
+const MB = 1024 * 1024;
+
+// Array(n).fill(x) types as any[], which the lint rules reject on spread.
+const sized = (count: number, bytes: number): number[] =>
+  Array.from({ length: count }, () => bytes);
+
+const docs = (...sizes: (number | null)[]): { sizeBytes: number | null }[] =>
+  sizes.map((sizeBytes) => ({ sizeBytes }));
+
+describe('indexBudgetMs', () => {
+  it('gives a small document enough time without waiting for hours', () => {
+    // 5 min base + 30 s for the document + ~0 for 3 KB of text.
+    expect(indexBudgetMs(docs(3 * 1024))).toBeGreaterThan(5 * MINUTE);
+    expect(indexBudgetMs(docs(3 * 1024))).toBeLessThan(6 * MINUTE);
+  });
+
+  it('scales with content volume, not just document count', () => {
+    // The measurement this replaces: one 1 MB owner's manual is 217 chunks and
+    // roughly 45 minutes of extraction plus merging. Counting documents gave
+    // it 30 seconds.
+    const oneBigFile = indexBudgetMs(docs(1 * MB));
+    const manySmallFiles = indexBudgetMs(docs(...sized(20, 1024)));
+    expect(oneBigFile).toBeGreaterThan(45 * MINUTE);
+    expect(oneBigFile).toBeGreaterThan(manySmallFiles);
+  });
+
+  it('still pays a per-document cost, so many tiny files are not free', () => {
+    expect(indexBudgetMs(docs(...sized(20, 1024)))).toBeGreaterThan(
+      indexBudgetMs(docs(1024)),
+    );
+  });
+
+  it('falls back to the per-document term when a size is unknown', () => {
+    expect(indexBudgetMs(docs(null))).toBe(5 * MINUTE + 30 * 1000);
+  });
+
+  it('caps the wait so a runaway batch cannot block a run forever', () => {
+    expect(indexBudgetMs(docs(...sized(500, 10 * MB)))).toBe(4 * 60 * MINUTE);
+  });
+
+  it('handles an empty batch and negative sizes without going negative', () => {
+    expect(indexBudgetMs([])).toBe(5 * MINUTE);
+    expect(indexBudgetMs(docs(-5))).toBe(5 * MINUTE + 30 * 1000);
+  });
+});
+
+describe('staleIndexAfterMs', () => {
+  it('always trails the run budget, so a restart is never offered mid-run', () => {
+    const batches = [
+      [],
+      docs(1024),
+      docs(1 * MB),
+      docs(...sized(50, 512 * 1024)),
+      docs(...sized(500, 10 * MB)),
+    ];
+    for (const batch of batches) {
+      expect(staleIndexAfterMs(batch)).toBeGreaterThan(indexBudgetMs(batch));
+    }
+  });
+});
+
+describe('pollIntervalMs', () => {
+  it('polls at the floor for a batch small enough not to matter', () => {
+    expect(pollIntervalMs(0)).toBe(3000);
+    expect(pollIntervalMs(1)).toBe(3000);
+    expect(pollIntervalMs(30)).toBe(3000);
+  });
+
+  it('holds the request rate roughly flat as the batch grows', () => {
+    // The point of the pacing: requests per second, not ticks per second.
+    for (const inFlight of [50, 120, 355, 600]) {
+      const ratePerSec = inFlight / (pollIntervalMs(inFlight) / 1000);
+      expect(ratePerSec).toBeLessThanOrEqual(11);
+    }
+  });
+
+  it('backs a 355-document run off from three seconds to tens of seconds', () => {
+    // The batch that produced ~118 requests a second on prod.
+    expect(pollIntervalMs(355)).toBeGreaterThan(30_000);
+  });
+
+  it('never waits longer than a minute, however large the batch', () => {
+    expect(pollIntervalMs(10_000)).toBe(60_000);
+  });
+
+  it('speeds back up as documents land', () => {
+    expect(pollIntervalMs(355)).toBeGreaterThan(pollIntervalMs(100));
+    expect(pollIntervalMs(100)).toBeGreaterThan(pollIntervalMs(10));
+  });
+});
diff --git a/api/src/slices/reins/source/domain/indexBudget.ts b/api/src/slices/reins/source/domain/indexBudget.ts
new file mode 100644
index 00000000..6618e476
--- /dev/null
+++ b/api/src/slices/reins/source/domain/indexBudget.ts
@@ -0,0 +1,101 @@
+// How long an index run may wait for LightRAG's background pipeline. Neither a
+// flat timeout nor a per-document one survives contact with real documents:
+// the pipeline runs an LLM over every *chunk*, and chunk count follows the
+// length of the text, not the number of files. Measured against the dev
+// cluster (Haiku on Bedrock, 4-way LLM concurrency): a 1 MB markdown owner's
+// manual splits into 217 chunks and spends about 20 minutes in extraction
+// alone, while a 3 KB order form is a single chunk and lands in under a
+// minute. A per-document constant sized for the second calls the first stalled
+// after 30 seconds, which is exactly what a 145-file documentation set hit -
+// the run reported "still processing" on documents that were merely large.
+const BASE_BUDGET_MS = 5 * 60 * 1000;
+
+// Per-document overhead that does not scale with length: the upload, the queue
+// wait behind other documents, and the merge pass LightRAG runs once per
+// document however short it is.
+const PER_DOCUMENT_BUDGET_MS = 30 * 1000;
+
+// The volume term. Measured end to end on one 1 MB manual: ~20 minutes of
+// chunk extraction plus a merge pass over the entities it produced that ran
+// just as long again. Both scale with chunk count, so both belong here.
+// Calibrated at 4-way LLM concurrency, which is what the dev instance actually
+// runs; raising that concurrency should lower this number.
+const PER_MEGABYTE_BUDGET_MS = 45 * 60 * 1000;
+
+const MAX_BUDGET_MS = 4 * 60 * 60 * 1000;
+const BYTES_PER_MEGABYTE = 1024 * 1024;
+
+// The watchdog that lets an operator restart a run stuck in `indexing` must
+// always trail the run's own budget, or the UI would offer a restart while the
+// first run is still legitimately waiting, and two runs would fight.
+const WATCHDOG_MARGIN_MS = 5 * 60 * 1000;
+
+/**
+ * A document as the budget sees it. `ISourceData` satisfies this structurally,
+ * so callers pass their sources straight through.
+ */
+export interface IIndexBudgetDocument {
+  /**
+   * Uncompressed length. Null for sources whose size is not known before
+   * ingest (url sources fetch their text at index time); those fall back to
+   * the per-document term alone.
+   */
+  sizeBytes: number | null;
+}
+
+/**
+ * Time to allow LightRAG for `documents` before giving up and reporting them
+ * retryable.
+ */
+export function indexBudgetMs(
+  documents: readonly IIndexBudgetDocument[],
+): number {
+  const totalBytes = documents.reduce(
+    (sum, doc) => sum + Math.max(0, doc.sizeBytes ?? 0),
+    0,
+  );
+  const budget =
+    BASE_BUDGET_MS +
+    documents.length * PER_DOCUMENT_BUDGET_MS +
+    (totalBytes / BYTES_PER_MEGABYTE) * PER_MEGABYTE_BUDGET_MS;
+  return Math.min(Math.round(budget), MAX_BUDGET_MS);
+}
+
+/**
+ * Age at which an `indexing` state is treated as abandoned rather than slow.
+ */
+export function staleIndexAfterMs(
+  documents: readonly IIndexBudgetDocument[],
+): number {
+  return indexBudgetMs(documents) + WATCHDOG_MARGIN_MS;
+}
+
+// Floor: below this a run would poll faster than the pipeline can plausibly
+// change its mind, and the extra requests buy nothing.
+const MIN_POLL_INTERVAL_MS = 3000;
+// Ceiling: past this the run stops feeling like it is watching anything, and
+// the budget above is spent waiting rather than confirming.
+const MAX_POLL_INTERVAL_MS = 60_000;
+// A poll tick asks LightRAG about every document still in flight, one request
+// each, so the interval is what sets the request *rate*. Holding the rate here
+// is the point; the interval is derived from it.
+const POLL_REQUESTS_PER_SEC = 10;
+
+/**
+ * How long to wait before asking LightRAG about the batch again.
+ *
+ * Paced by batch size rather than fixed, because a fixed 3 s tick over 355
+ * in-flight documents is ~118 requests a second sustained for hours. That run
+ * saturated the API pod - a browser saw the resulting gateway errors as CORS
+ * failures on unrelated requests - and buried LightRAG's own logs, where
+ * 34 523 of 34 533 lines were these polls, rotating away the record of why the
+ * pipeline had stopped. A small batch is unaffected and still polls at the
+ * floor.
+ */
+export function pollIntervalMs(inFlight: number): number {
+  const paced = (Math.max(0, inFlight) / POLL_REQUESTS_PER_SEC) * 1000;
+  return Math.min(
+    MAX_POLL_INTERVAL_MS,
+    Math.max(MIN_POLL_INTERVAL_MS, Math.round(paced)),
+  );
+}
diff --git a/api/src/slices/reins/source/domain/source.gateway.ts b/api/src/slices/reins/source/domain/source.gateway.ts
index 83221164..32b62d20 100644
--- a/api/src/slices/reins/source/domain/source.gateway.ts
+++ b/api/src/slices/reins/source/domain/source.gateway.ts
@@ -1,14 +1,36 @@
 import {
   ISourceData,
   ICreateSourceData,
+  ISourceContent,
+  ISourceCounts,
+  ISourceFilter,
   ISourceIndexStatePatch,
+  ISourcePage,
+  ISourceSelection,
   IUploadSourceFileInput,
   IUploadSourceStreamInput,
   IUploadedSourceFile,
+  ISourceIndexOutcome,
 } from './source.types';
 
 export abstract class ISourceGateway {
   abstract findByKnowledgeId(knowledgeId: string): Promise<ISourceData[]>;
+  abstract findPage(
+    knowledgeId: string,
+    filter: ISourceFilter,
+  ): Promise<ISourcePage>;
+  /**
+   * Index progress per knowledge. Knowledges with no sources are absent from
+   * the map; callers treat that as all zeros.
+   */
+  abstract countByKnowledgeIds(
+    knowledgeIds: string[],
+  ): Promise<Map<string, ISourceCounts>>;
+  /** Every source matching an explicit id list or the list's own filter. */
+  abstract findForExport(
+    knowledgeId: string,
+    selection: ISourceSelection,
+  ): Promise<ISourceData[]>;
   abstract findById(id: string): Promise<ISourceData | null>;
   abstract create(data: ICreateSourceData): Promise<ISourceData>;
   abstract createMany(data: ICreateSourceData[]): Promise<ISourceData[]>;
@@ -21,7 +43,23 @@ export abstract class ISourceGateway {
     input: IUploadSourceStreamInput,
   ): Promise<IUploadedSourceFile>;
   abstract deleteFile(url: string): Promise<void>;
+  /** Bytes of a file or text source. Throws for url sources. */
+  abstract readContent(source: ISourceData): Promise<ISourceContent>;
 
+  abstract indexSources(sources: ISourceData[]): Promise<ISourceIndexOutcome[]>;
+  /**
+   * Sources handed to LightRAG that nothing has confirmed yet, across every
+   * knowledge. These are what a reconcile pass has to look at.
+   */
+  abstract findUnconfirmed(): Promise<ISourceData[]>;
+  /**
+   * Ask LightRAG about each source's stored handle once and write down what it
+   * says. Unlike `indexSources` this never uploads and never waits: a document
+   * still in the pipeline is simply left for the next pass.
+   */
+  abstract confirmProcessed(
+    sources: ISourceData[],
+  ): Promise<ISourceIndexOutcome[]>;
   /** Hands the source to the retrieval service and marks it processing. */
   abstract indexSource(source: ISourceData): Promise<void>;
   /**
diff --git a/api/src/slices/reins/source/domain/source.service.ts b/api/src/slices/reins/source/domain/source.service.ts
index 956eb959..af920acf 100644
--- a/api/src/slices/reins/source/domain/source.service.ts
+++ b/api/src/slices/reins/source/domain/source.service.ts
@@ -5,13 +5,23 @@ import {
   NotFoundException,
 } from '@nestjs/common';
 import { promises as fs } from 'fs';
+import { Writable } from 'stream';
 import { ISourceGateway } from './source.gateway';
+import { ImportJobRegistry } from './importJob.registry';
 import {
   IArchiveImportResult,
   IFilesImportResult,
+  IImportJob,
+  ISourceContent,
+  ISourceCounts,
   ISourceData,
+  ISourceFilter,
+  ISourceIndexOutcome,
+  ISourcePage,
+  ISourceSelection,
 } from './source.types';
 import { fetchSitemapUrls, SitemapError } from '../data/sitemap.fetcher';
+import { writeSourceArchive } from '../data/sourceArchive.writer';
 import {
   ArchiveEntry,
   contentTypeForEntry,
@@ -31,6 +41,11 @@ export interface IUploadedFile {
   size: number;
 }
 
+// A base this size is a migration, not a click. Refuse instead of streaming
+// something nobody will wait for; the filter is there to narrow it.
+const MAX_EXPORT_SOURCES = 2000;
+const MAX_EXPORT_BYTES = 2 * 1024 * 1024 * 1024;
+
 function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
@@ -39,12 +54,40 @@ function errorMessage(err: unknown): string {
 export class SourceService {
   private readonly logger = new Logger(SourceService.name);
 
-  constructor(private readonly gateway: ISourceGateway) {}
+  constructor(
+    private readonly gateway: ISourceGateway,
+    private readonly imports: ImportJobRegistry,
+  ) {}
 
   findByKnowledge(knowledgeId: string): Promise<ISourceData[]> {
     return this.gateway.findByKnowledgeId(knowledgeId);
   }
 
+  findPage(knowledgeId: string, filter: ISourceFilter): Promise<ISourcePage> {
+    return this.gateway.findPage(knowledgeId, filter);
+  }
+
+  countByKnowledgeIds(
+    knowledgeIds: string[],
+  ): Promise<Map<string, ISourceCounts>> {
+    return this.gateway.countByKnowledgeIds(knowledgeIds);
+  }
+
+  async readContent(
+    knowledgeId: string,
+    sourceId: string,
+  ): Promise<ISourceContent> {
+    const source = await this.gateway.findById(sourceId);
+    if (!source || source.knowledgeId !== knowledgeId) {
+      throw new NotFoundException(`Source ${sourceId} not found`);
+    }
+    return this.gateway.readContent(source);
+  }
+
+  listImports(knowledgeId: string): IImportJob[] {
+    return this.imports.listByKnowledge(knowledgeId);
+  }
+
   async addFile(
     knowledgeId: string,
     file: IUploadedFile,
@@ -161,11 +204,11 @@ export class SourceService {
   /**
    * Accepts an already-saved zip on disk, lists its ingestable entries, and
    * kicks off a background import (one file-source per entry, streamed to
-   * S3). Returns immediately with the detected count so the HTTP request
-   * doesn't hang for the minutes a large archive takes. The caller-owned
-   * zip at zipPath is deleted once the background pass finishes. Indexing
-   * into LightRAG is NOT triggered here - that stays the explicit Index
-   * action.
+   * S3). Returns immediately with the detected count and a job id so the
+   * HTTP request doesn't hang for the minutes a large archive takes; the
+   * sources page polls the job for progress. The caller-owned zip at zipPath
+   * is deleted once the background pass finishes. Indexing into LightRAG is
+   * NOT triggered here - that stays the explicit Index action.
    */
   async addFromArchive(
     knowledgeId: string,
@@ -186,11 +229,13 @@ export class SourceService {
         'Archive contains no ingestable files (pdf, docx, xlsx, txt, html, ...).',
       );
     }
-    void this.runArchiveImport(knowledgeId, zipPath, entries);
-    return { detected: entries.length, started: true };
+    const job = this.imports.create(knowledgeId, 'archive', entries.length);
+    void this.runArchiveImport(job.id, knowledgeId, zipPath, entries);
+    return { detected: entries.length, started: true, jobId: job.id };
   }
 
   private async runArchiveImport(
+    jobId: string,
     knowledgeId: string,
     zipPath: string,
     entries: ArchiveEntry[],
@@ -198,6 +243,7 @@ export class SourceService {
     let added = 0;
     let skipped = 0;
     let failed = 0;
+    let crashed: string | null = null;
     try {
       const existing = await this.gateway.findByKnowledgeId(knowledgeId);
       const existingNames = new Set(
@@ -209,6 +255,7 @@ export class SourceService {
         const name = displayNameForEntry(entry.path);
         if (seenPaths.has(entry.path) || existingNames.has(name)) {
           skipped += 1;
+          this.imports.progress(jobId, { skipped: 1 });
           continue;
         }
         seenPaths.add(entry.path);
@@ -229,8 +276,13 @@ export class SourceService {
             sizeBytes: entry.size,
           });
           added += 1;
+          this.imports.progress(jobId, { added: 1 });
         } catch (err) {
           failed += 1;
+          this.imports.progress(jobId, {
+            failed: 1,
+            error: `${name}: ${errorMessage(err)}`,
+          });
           this.logger.warn(
             `archive entry failed ${entry.path}: ${errorMessage(err)}`,
           );
@@ -240,11 +292,21 @@ export class SourceService {
         `archive import for ${knowledgeId}: added=${added} skipped=${skipped} failed=${failed}`,
       );
     } catch (err) {
+      crashed = errorMessage(err);
       this.logger.error(
-        `archive import crashed for ${knowledgeId}: ${errorMessage(err)}`,
+        `archive import crashed for ${knowledgeId}: ${crashed}`,
       );
     } finally {
       await this.safeUnlink(zipPath);
+      if (crashed === null) {
+        this.imports.finish(jobId, 'done');
+      } else {
+        this.imports.finish(
+          jobId,
+          'failed',
+          `archive import crashed: ${crashed}`,
+        );
+      }
     }
   }
 
@@ -258,8 +320,64 @@ export class SourceService {
     }
   }
 
-  indexSource(source: ISourceData): Promise<void> {
-    return this.gateway.indexSource(source);
+  /**
+   * Resolve what an export request selected, and refuse rather than truncate
+   * when it is too big. Separate from the writing step so a rejection is a
+   * clean 400 - once the first zip byte is on the wire the status line is
+   * already sent and the client gets a corrupt download instead of an error.
+   */
+  async prepareExport(
+    knowledgeId: string,
+    selection: ISourceSelection,
+  ): Promise<ISourceData[]> {
+    const sources = await this.gateway.findForExport(knowledgeId, selection);
+    if (sources.length === 0) {
+      throw new BadRequestException('No sources matched the selection.');
+    }
+    if (sources.length > MAX_EXPORT_SOURCES) {
+      throw new BadRequestException(
+        `Selection is ${sources.length} sources; the export is capped at ${MAX_EXPORT_SOURCES}. Narrow it with the filter.`,
+      );
+    }
+    const bytes = sources.reduce((sum, s) => sum + (s.sizeBytes ?? 0), 0);
+    if (bytes > MAX_EXPORT_BYTES) {
+      throw new BadRequestException(
+        `Selection is ${Math.round(bytes / 1024 / 1024)} MB; the export is capped at ${Math.round(MAX_EXPORT_BYTES / 1024 / 1024)} MB.`,
+      );
+    }
+    return sources;
+  }
+
+  /**
+   * Stream the selected sources into `out` as a zip, one source at a time.
+   * `url` sources have no bytes and are recorded in the manifest instead, so
+   * they never reach the reader.
+   */
+  writeExport(
+    knowledgeId: string,
+    sources: ISourceData[],
+    out: Writable,
+  ): Promise<void> {
+    return writeSourceArchive(
+      knowledgeId,
+      sources,
+      async (source) => ({
+        body: (await this.gateway.readContent(source)).body,
+      }),
+      out,
+    );
+  }
+
+  indexSources(sources: ISourceData[]): Promise<ISourceIndexOutcome[]> {
+    return this.gateway.indexSources(sources);
+  }
+
+  findUnconfirmed(): Promise<ISourceData[]> {
+    return this.gateway.findUnconfirmed();
+  }
+
+  confirmProcessed(sources: ISourceData[]): Promise<ISourceIndexOutcome[]> {
+    return this.gateway.confirmProcessed(sources);
   }
 
   /**
diff --git a/api/src/slices/reins/source/domain/source.types.ts b/api/src/slices/reins/source/domain/source.types.ts
index 7b3118e0..58892478 100644
--- a/api/src/slices/reins/source/domain/source.types.ts
+++ b/api/src/slices/reins/source/domain/source.types.ts
@@ -3,6 +3,15 @@ import { Readable } from 'stream';
 export type SourceTypes = 'file' | 'url' | 'text';
 
 /**
+ * Per-source view of the last index run. `indexed` = LightRAG confirmed the
+ * document as processed; `failed` = the last run reported an error for it and
+ * nothing has succeeded since; `pending` = never sent, or sent and still
+ * waiting for a verdict.
+ */
+export type SourceIndexStatusTypes = 'indexed' | 'pending' | 'failed';
+
+/**
+ * Stored per-source ingestion state, the migration's resume marker:
  * queued -> processing -> indexed | failed; failed -> queued on retry.
  * "indexed" means the retrieval service reports the document processed and
  * searchable — not merely handed over.
@@ -22,6 +31,9 @@ export interface ISourceData {
   mimeType: string | null;
   content: string | null;
   sizeBytes: number | null;
+  /** Kept for callers that only care about searchable-or-not. */
+  indexed: boolean;
+  indexStatus: SourceIndexStatusTypes;
   indexState: SourceIndexStateTypes;
   indexError: string | null;
   indexedAt: Date | null;
@@ -35,6 +47,80 @@ export interface ISourceIndexStatePatch {
   indexedAt?: Date | null;
 }
 
+export interface ISourceFilter {
+  page: number;
+  perPage: number;
+  search?: string;
+  status?: SourceIndexStatusTypes;
+  type?: SourceTypes;
+}
+
+/**
+ * What to export. `ids` is an explicit tick-list; without it the same filter
+ * the list uses selects the rows, so "select all" can travel as three query
+ * params instead of every id the user can see.
+ */
+export interface ISourceSelection {
+  ids?: string[];
+  search?: string;
+  status?: SourceIndexStatusTypes;
+  type?: SourceTypes;
+}
+
+export interface ISourcePage {
+  items: ISourceData[];
+  total: number;
+  page: number;
+  perPage: number;
+}
+
+export interface ISourceCounts {
+  total: number;
+  indexed: number;
+  failed: number;
+  /**
+   * Handed to LightRAG and still moving through its pipeline: the run that
+   * submitted them stopped waiting, but nothing is wrong with them. Counted
+   * apart from the rest of `pending` so a base cannot report itself finished
+   * while a document is still being chunked.
+   */
+  processing: number;
+}
+
+/**
+ * Bytes of a source ready to stream to an HTTP response. `body` is consumed
+ * exactly once by the caller.
+ */
+export interface ISourceContent {
+  filename: string;
+  contentType: string;
+  contentLength: number | null;
+  body: Readable;
+}
+
+/**
+ * Result of pushing one source through LightRAG's ingest-then-process
+ * pipeline.
+ *
+ * Three states, not two. `failed` means LightRAG rejected the document or the
+ * pipeline gave up on it, and a human should look. `pending` means the run
+ * stopped waiting before LightRAG finished - the document is still being
+ * processed and the next run will pick it up. Collapsing the two is what
+ * painted a healthy re-index of a large base red: on a base of 200 documents
+ * the wait budget expires long before the pipeline does.
+ */
+export type SourceIndexOutcomeStatus = 'indexed' | 'pending' | 'failed';
+
+export interface ISourceIndexOutcome {
+  sourceId: string;
+  name: string;
+  status: SourceIndexOutcomeStatus;
+  /** Kept for callers that only care about searchable-or-not. */
+  indexed: boolean;
+  /** Set for `failed`, and for `pending` as the reason the wait ended. */
+  error: string | null;
+}
+
 export interface ICreateSourceData {
   knowledgeId: string;
   type: SourceTypes;
@@ -63,9 +149,32 @@ export interface IUploadedSourceFile {
   url: string;
 }
 
+export type ImportJobStatusTypes = 'running' | 'done' | 'failed';
+
+/**
+ * Progress of one background bulk import (archive today). Lives in memory
+ * only: an import cannot outlive the process anyway, so there is nothing to
+ * persist that would still be true after a restart.
+ */
+export interface IImportJob {
+  id: string;
+  knowledgeId: string;
+  kind: 'archive';
+  status: ImportJobStatusTypes;
+  detected: number;
+  added: number;
+  skipped: number;
+  failed: number;
+  /** First N `"<name>: <reason>"` lines, capped by the registry. */
+  errors: string[];
+  startedAt: Date;
+  finishedAt: Date | null;
+}
+
 export interface IArchiveImportResult {
   detected: number;
   started: boolean;
+  jobId: string;
 }
 
 export interface IFilesImportResult {
diff --git a/api/src/slices/reins/source/dtos/addFromArchive.dto.ts b/api/src/slices/reins/source/dtos/addFromArchive.dto.ts
index aa042ee8..55f6df11 100644
--- a/api/src/slices/reins/source/dtos/addFromArchive.dto.ts
+++ b/api/src/slices/reins/source/dtos/addFromArchive.dto.ts
@@ -1,13 +1,20 @@
 import { ApiProperty } from '@nestjs/swagger';
+import { IArchiveImportResult } from '../domain/source.types';
 
-export class AddFromArchiveResultDto {
+export class AddFromArchiveResultDto implements IArchiveImportResult {
   @ApiProperty({
     example: 288,
     description:
-      'Number of ingestable files detected in the archive. Import runs in the background; refresh the sources list to watch them appear.',
+      'Number of ingestable files detected in the archive. Import runs in the background; poll GET .../sources/imports for progress.',
   })
   detected: number;
 
   @ApiProperty({ example: true })
   started: boolean;
+
+  @ApiProperty({
+    description:
+      'Id of the background import job (see GET .../sources/imports)',
+  })
+  jobId: string;
 }
diff --git a/api/src/slices/reins/source/dtos/exportSources.dto.ts b/api/src/slices/reins/source/dtos/exportSources.dto.ts
new file mode 100644
index 00000000..067d8cb0
--- /dev/null
+++ b/api/src/slices/reins/source/dtos/exportSources.dto.ts
@@ -0,0 +1,39 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsIn, IsOptional, IsString } from 'class-validator';
+import { SourceIndexStatusTypes, SourceTypes } from '../domain/source.types';
+import { SOURCE_INDEX_STATUSES } from './source.dto';
+
+const SOURCE_TYPES: readonly SourceTypes[] = ['file', 'url', 'text'];
+
+/**
+ * Mirrors the list's filter so "export everything I am looking at" needs no
+ * second definition of what that means. `ids` is the tick-list; when it is
+ * present the filter is ignored, because the caller picked rows rather than a
+ * query and the two can disagree by the time the request lands.
+ */
+export class ExportSourcesDto {
+  @ApiPropertyOptional({
+    description:
+      'Comma-separated source ids. When present the filter fields are ignored.',
+  })
+  @IsOptional()
+  @IsString()
+  ids?: string;
+
+  @ApiPropertyOptional({
+    description: 'Case-insensitive substring match on the source name',
+  })
+  @IsOptional()
+  @IsString()
+  search?: string;
+
+  @ApiPropertyOptional({ enum: SOURCE_INDEX_STATUSES })
+  @IsOptional()
+  @IsIn(SOURCE_INDEX_STATUSES)
+  status?: SourceIndexStatusTypes;
+
+  @ApiPropertyOptional({ enum: SOURCE_TYPES })
+  @IsOptional()
+  @IsIn(SOURCE_TYPES)
+  type?: SourceTypes;
+}
diff --git a/api/src/slices/reins/source/dtos/filterSources.dto.ts b/api/src/slices/reins/source/dtos/filterSources.dto.ts
new file mode 100644
index 00000000..68d83bb3
--- /dev/null
+++ b/api/src/slices/reins/source/dtos/filterSources.dto.ts
@@ -0,0 +1,41 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsIn, IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
+import { SourceIndexStatusTypes, SourceTypes } from '../domain/source.types';
+import { SOURCE_INDEX_STATUSES } from './source.dto';
+
+const SOURCE_TYPES: readonly SourceTypes[] = ['file', 'url', 'text'];
+
+export class FilterSourcesDto {
+  @ApiPropertyOptional({
+    description: 'Case-insensitive substring match on the source name',
+  })
+  @IsOptional()
+  @IsString()
+  search?: string;
+
+  @ApiPropertyOptional({ enum: SOURCE_INDEX_STATUSES })
+  @IsOptional()
+  @IsIn(SOURCE_INDEX_STATUSES)
+  status?: SourceIndexStatusTypes;
+
+  @ApiPropertyOptional({ enum: SOURCE_TYPES })
+  @IsOptional()
+  @IsIn(SOURCE_TYPES)
+  type?: SourceTypes;
+
+  @ApiPropertyOptional({ minimum: 1, default: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number;
+
+  @ApiPropertyOptional({ minimum: 1, maximum: 200, default: 50 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(200)
+  perPage?: number;
+}
diff --git a/api/src/slices/reins/source/dtos/importJob.dto.ts b/api/src/slices/reins/source/dtos/importJob.dto.ts
new file mode 100644
index 00000000..01b4d873
--- /dev/null
+++ b/api/src/slices/reins/source/dtos/importJob.dto.ts
@@ -0,0 +1,25 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IImportJob, ImportJobStatusTypes } from '../domain/source.types';
+
+export class ImportJobDto implements IImportJob {
+  @ApiProperty() id: string;
+  @ApiProperty() knowledgeId: string;
+  @ApiProperty({ enum: ['archive'] }) kind: 'archive';
+  @ApiProperty({ enum: ['running', 'done', 'failed'] })
+  status: ImportJobStatusTypes;
+  @ApiProperty({ description: 'Ingestable entries found up front' })
+  detected: number;
+  @ApiProperty() added: number;
+  @ApiProperty({
+    description: 'Entries skipped because a source with that name exists',
+  })
+  skipped: number;
+  @ApiProperty() failed: number;
+  @ApiProperty({
+    type: [String],
+    description: 'First failures as "<name>: <reason>", capped',
+  })
+  errors: string[];
+  @ApiProperty() startedAt: Date;
+  @ApiProperty({ type: String, nullable: true }) finishedAt: Date | null;
+}
diff --git a/api/src/slices/reins/source/dtos/index.ts b/api/src/slices/reins/source/dtos/index.ts
index 7f6909e1..c50c2788 100644
--- a/api/src/slices/reins/source/dtos/index.ts
+++ b/api/src/slices/reins/source/dtos/index.ts
@@ -3,3 +3,8 @@ export * from './createSource.dto';
 export * from './addFromSitemap.dto';
 export * from './addFromArchive.dto';
 export * from './addFiles.dto';
+export * from './filterSources.dto';
+export * from './sourcePage.dto';
+export * from './importJob.dto';
+export * from './sourceContent.query.dto';
+export * from './exportSources.dto';
diff --git a/api/src/slices/reins/source/dtos/source.dto.ts b/api/src/slices/reins/source/dtos/source.dto.ts
index dfad5b2b..5d72e92b 100644
--- a/api/src/slices/reins/source/dtos/source.dto.ts
+++ b/api/src/slices/reins/source/dtos/source.dto.ts
@@ -1,10 +1,17 @@
 import { ApiProperty } from '@nestjs/swagger';
 import {
   ISourceData,
+  SourceIndexStatusTypes,
   SourceIndexStateTypes,
   SourceTypes,
 } from '../domain/source.types';
 
+export const SOURCE_INDEX_STATUSES: readonly SourceIndexStatusTypes[] = [
+  'indexed',
+  'pending',
+  'failed',
+];
+
 export class SourceDto implements ISourceData {
   @ApiProperty() id: string;
   @ApiProperty() knowledgeId: string;
@@ -14,12 +21,20 @@ export class SourceDto implements ISourceData {
   @ApiProperty({ type: String, nullable: true }) mimeType: string | null;
   @ApiProperty({ type: String, nullable: true }) content: string | null;
   @ApiProperty({ type: Number, nullable: true }) sizeBytes: number | null;
-  // The old `indexed` boolean meant "handed over", not "searchable" —
-  // keeping a truthful state next to a misleading boolean is how the
-  // misleading one survives, so it is gone rather than deprecated.
+  @ApiProperty({
+    description: 'True when indexStatus is "indexed". Kept for older callers.',
+  })
+  indexed: boolean;
+  @ApiProperty({ enum: SOURCE_INDEX_STATUSES })
+  indexStatus: SourceIndexStatusTypes;
   @ApiProperty({ enum: ['queued', 'processing', 'indexed', 'failed'] })
   indexState: SourceIndexStateTypes;
-  @ApiProperty({ type: String, nullable: true }) indexError: string | null;
+  @ApiProperty({
+    type: String,
+    nullable: true,
+    description: 'Error from the last index run, null once the source indexes.',
+  })
+  indexError: string | null;
   @ApiProperty({ type: String, nullable: true }) indexedAt: Date | null;
   @ApiProperty() createdAt: Date;
   @ApiProperty() updatedAt: Date;
diff --git a/api/src/slices/reins/source/dtos/sourceContent.query.dto.ts b/api/src/slices/reins/source/dtos/sourceContent.query.dto.ts
new file mode 100644
index 00000000..a3341216
--- /dev/null
+++ b/api/src/slices/reins/source/dtos/sourceContent.query.dto.ts
@@ -0,0 +1,21 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsIn, IsOptional } from 'class-validator';
+
+export type ContentDispositionTypes = 'inline' | 'attachment';
+
+const DISPOSITIONS: readonly ContentDispositionTypes[] = [
+  'inline',
+  'attachment',
+];
+
+export class SourceContentQueryDto {
+  @ApiPropertyOptional({
+    enum: DISPOSITIONS,
+    default: 'inline',
+    description:
+      '"inline" lets the browser render what it can (pdf, images, text); "attachment" forces a download.',
+  })
+  @IsOptional()
+  @IsIn(DISPOSITIONS)
+  disposition?: ContentDispositionTypes;
+}
diff --git a/api/src/slices/reins/source/dtos/sourcePage.dto.ts b/api/src/slices/reins/source/dtos/sourcePage.dto.ts
new file mode 100644
index 00000000..5822cfe2
--- /dev/null
+++ b/api/src/slices/reins/source/dtos/sourcePage.dto.ts
@@ -0,0 +1,11 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { ISourcePage } from '../domain/source.types';
+import { SourceDto } from './source.dto';
+
+export class SourcePageDto implements ISourcePage {
+  @ApiProperty({ type: [SourceDto] }) items: SourceDto[];
+  @ApiProperty({ description: 'Rows matching the filter across all pages' })
+  total: number;
+  @ApiProperty() page: number;
+  @ApiProperty() perPage: number;
+}
diff --git a/api/src/slices/reins/source/source.controller.ts b/api/src/slices/reins/source/source.controller.ts
index 50e47352..d9ed2bde 100644
--- a/api/src/slices/reins/source/source.controller.ts
+++ b/api/src/slices/reins/source/source.controller.ts
@@ -5,6 +5,8 @@ import {
   Delete,
   Body,
   Param,
+  Query,
+  Res,
   HttpCode,
   UploadedFile,
   UploadedFiles,
@@ -17,12 +19,16 @@ import {
   ApiOperation,
   ApiConsumes,
   ApiResponse,
+  ApiOkResponse,
+  ApiProduces,
 } from '@nestjs/swagger';
-import { promises as fs } from 'fs';
+import type { Response } from 'express';
+import { diskStorage } from 'multer';
 import * as os from 'os';
-import * as path from 'path';
 import { randomUUID } from 'crypto';
+import { pipeline } from 'stream/promises';
 import { SourceService } from './domain/source.service';
+import { archiveMaxBytes } from './domain/archiveLimit';
 import { UploadLimitInterceptor } from './uploadLimit.interceptor';
 import {
   AddFilesResultDto,
@@ -30,22 +36,24 @@ import {
   AddFromSitemapDto,
   AddFromSitemapResultDto,
   CreateSourceDto,
+  ExportSourcesDto,
+  FilterSourcesDto,
+  ImportJobDto,
+  SourceContentQueryDto,
+  SourcePageDto,
 } from './dtos';
 
-// Cap archive uploads at 1 GiB. The upload is buffered in memory (multer's
-// default storage) and then written to a temp file for extraction. We can't
-// use multer's diskStorage here: under the Bun workspace `multer` is a phantom
-// dependency of @nestjs/platform-express, so `import { diskStorage } from
-// 'multer'` does not resolve at runtime.
-const ONE_GIB = 1024 * 1024 * 1024;
-
-// Multi-file uploads are buffered in memory the same way, so the batch is
-// capped. Sized for whole documentation sets (a few hundred markdown/office
-// files), not for bulk media: the ceiling is file *count*, so N very large
-// files still peak at their combined size. Beyond this, the from-archive
-// route is the right tool - it streams zip entries one at a time.
+// Multi-file uploads are buffered in memory (multer's default storage), so
+// the batch is capped. Sized for whole documentation sets (a few hundred
+// markdown/office files), not for bulk media: the ceiling is file *count*, so
+// N very large files still peak at their combined size. Beyond this, the
+// from-archive route is the right tool - it streams the zip to disk and then
+// its entries to S3 one at a time.
 const MAX_FILES_PER_BATCH = 250;
 
+const DEFAULT_PAGE = 1;
+const DEFAULT_PER_PAGE = 50;
+
 interface UploadedFileLike {
   originalname: string;
   mimetype: string;
@@ -53,6 +61,32 @@ interface UploadedFileLike {
   buffer: Buffer;
 }
 
+// What multer's diskStorage hands the handler: the bytes are already on disk,
+// `buffer` is absent.
+interface UploadedDiskFileLike {
+  originalname: string;
+  size: number;
+  path: string;
+}
+
+/**
+ * RFC 6266 / 5987: an ASCII-only `filename` for old clients plus a UTF-8
+ * `filename*` for everyone else, so a Cyrillic or Japanese document name
+ * survives the round trip to the browser's download prompt.
+ */
+function contentDisposition(
+  disposition: 'inline' | 'attachment',
+  filename: string,
+): string {
+  const fallback =
+    filename.replace(/[^\x20-\x7E]/g, '_').replace(/["\\]/g, '_') || 'download';
+  const encoded = encodeURIComponent(filename).replace(
+    /['()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+  return `${disposition}; filename="${fallback}"; filename*=UTF-8''${encoded}`;
+}
+
 @ApiTags('knowledge-sources')
 @Controller('knowledges/:knowledgeId/sources')
 export class SourceController {
@@ -60,11 +94,108 @@ export class SourceController {
 
   @Get()
   @ApiOperation({
-    summary: 'List sources',
+    summary: 'List sources (paginated)',
     operationId: 'getKnowledgeSources',
   })
-  list(@Param('knowledgeId') knowledgeId: string) {
-    return this.service.findByKnowledge(knowledgeId);
+  @ApiOkResponse({ type: SourcePageDto })
+  list(
+    @Param('knowledgeId') knowledgeId: string,
+    @Query() filter: FilterSourcesDto,
+  ): Promise<SourcePageDto> {
+    return this.service.findPage(knowledgeId, {
+      page: filter.page ?? DEFAULT_PAGE,
+      perPage: filter.perPage ?? DEFAULT_PER_PAGE,
+      search: filter.search,
+      status: filter.status,
+      type: filter.type,
+    });
+  }
+
+  // Declared ahead of ':sourceId/content' so Nest never reads "imports" as an id.
+  @Get('imports')
+  @ApiOperation({
+    summary: 'Background imports for this knowledge (running and recent)',
+    operationId: 'getKnowledgeSourceImports',
+    description:
+      'Progress of archive imports started through from-archive. Jobs are kept in memory for an hour after they finish.',
+  })
+  @ApiOkResponse({ type: [ImportJobDto] })
+  imports(@Param('knowledgeId') knowledgeId: string): ImportJobDto[] {
+    return this.service.listImports(knowledgeId);
+  }
+
+  // Declared ahead of ':sourceId/content' for the same reason as 'imports'.
+  @Get('export')
+  @ApiOperation({
+    summary: 'Download selected sources as one zip',
+    operationId: 'exportKnowledgeSources',
+    description:
+      'Selection is either an explicit `ids` list or the same filter the list takes, so "select all" travels as a filter rather than every id. File and text sources become entries; url sources are recorded in the `_ranch-export.yaml` manifest, whose extension the archive importer skips so the zip round-trips through from-archive.',
+  })
+  @ApiProduces('application/zip')
+  async exportSources(
+    @Param('knowledgeId') knowledgeId: string,
+    @Query() query: ExportSourcesDto,
+    @Res() res: Response,
+  ): Promise<void> {
+    // Resolve and validate before a single byte goes out: once the status line
+    // is sent, a rejection can only arrive as a truncated zip.
+    const sources = await this.service.prepareExport(knowledgeId, {
+      ids: query.ids
+        ?.split(',')
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0),
+      search: query.search,
+      status: query.status,
+      type: query.type,
+    });
+
+    res.setHeader('Content-Type', 'application/zip');
+    res.setHeader(
+      'Content-Disposition',
+      contentDisposition('attachment', `${knowledgeId}-sources.zip`),
+    );
+    res.setHeader('Access-Control-Expose-Headers', 'Content-Disposition');
+    await this.service.writeExport(knowledgeId, sources, res);
+  }
+
+  // @Res() bypasses the global ResponseInterceptor envelope so the browser
+  // gets raw bytes it can render or save (same pattern as agent file export).
+  @Get(':sourceId/content')
+  @ApiOperation({
+    summary: 'Stream the stored bytes of a file or text source',
+    operationId: 'getKnowledgeSourceContent',
+    description:
+      'Streams the file straight from S3 (or the text body from the row). Not available for url sources - open the url itself.',
+  })
+  @ApiProduces('application/octet-stream')
+  async content(
+    @Param('knowledgeId') knowledgeId: string,
+    @Param('sourceId') sourceId: string,
+    @Query() query: SourceContentQueryDto,
+    @Res() res: Response,
+  ): Promise<void> {
+    const content = await this.service.readContent(knowledgeId, sourceId);
+    res.setHeader('Content-Type', content.contentType);
+    res.setHeader(
+      'Content-Disposition',
+      contentDisposition(query.disposition ?? 'inline', content.filename),
+    );
+    if (content.contentLength !== null) {
+      res.setHeader('Content-Length', content.contentLength.toString());
+    }
+    // Let the admin read the filename back off the blob response.
+    res.setHeader('Access-Control-Expose-Headers', 'Content-Disposition');
+    // pipeline() (unlike .pipe()) tears down the S3 stream when the client
+    // aborts, so a cancelled preview does not leak an SDK socket. Once headers
+    // are out an error can only cut the response short, which is what we want:
+    // a truncated download rather than a "complete" one.
+    try {
+      await pipeline(content.body, res);
+    } catch (err) {
+      if (!res.headersSent) throw err;
+      res.destroy();
+    }
   }
 
   @Post(':sourceId/reindex')
@@ -177,31 +308,44 @@ export class SourceController {
     );
   }
 
+  // The zip streams to a temp file as it arrives - it never sits in memory.
+  // With multer's default memory storage a 1 GiB archive was 1 GiB of heap
+  // on a pod with a 512Mi limit, i.e. an OOM kill before extraction began.
   @Post('from-archive')
   @ApiOperation({
     summary: 'Bulk-import sources from a zip archive',
     operationId: 'addKnowledgeSourcesFromArchive',
     description:
-      'Accepts a .zip, extracts every ingestable file (pdf, docx, xlsx, txt, html, ...), and creates one file-type source per entry. Upload runs in the background and streams each entry to S3; the response returns immediately with the detected file count. Indexing into LightRAG happens through the normal reindex flow.',
+      'Accepts a .zip, extracts every ingestable file (pdf, docx, xlsx, txt, html, ...), and creates one file-type source per entry. Upload runs in the background and streams each entry to S3; the response returns immediately with the detected file count and a job id to poll via GET .../sources/imports. Indexing into LightRAG happens through the normal reindex flow. Max size: KNOWLEDGE_ARCHIVE_MAX_BYTES (default 4 GiB).',
   })
   @ApiConsumes('multipart/form-data')
   @ApiResponse({ status: 201, type: AddFromArchiveResultDto })
-  @UseInterceptors(FileInterceptor('file', { limits: { fileSize: ONE_GIB } }))
+  @UseInterceptors(
+    FileInterceptor('file', {
+      storage: diskStorage({
+        destination: os.tmpdir(),
+        filename: (_req, _file, cb) =>
+          cb(null, `ranch-knowledge-archive-${randomUUID()}.zip`),
+      }),
+      // A getter, not a value: this decorator runs at import time, before
+      // ConfigModule has loaded .env.dev into process.env. busboy reads the
+      // limit per request, so resolving lazily picks up the configured value.
+      limits: {
+        get fileSize(): number {
+          return archiveMaxBytes();
+        },
+      },
+    }),
+  )
   async addFromArchive(
     @Param('knowledgeId') knowledgeId: string,
-    @UploadedFile() file?: UploadedFileLike,
+    @UploadedFile() file?: UploadedDiskFileLike,
   ): Promise<AddFromArchiveResultDto> {
     if (!file) {
       throw new BadRequestException('zip file is required (field "file")');
     }
-    // The service consumes and then deletes a zip already saved on disk (see
-    // its doc comment), so persist the in-memory upload to a temp file first.
-    const zipPath = path.join(
-      os.tmpdir(),
-      `ranch-knowledge-archive-${randomUUID()}.zip`,
-    );
-    await fs.writeFile(zipPath, file.buffer);
-    return this.service.addFromArchive(knowledgeId, zipPath);
+    // The service consumes and then deletes the zip at file.path.
+    return this.service.addFromArchive(knowledgeId, file.path);
   }
 
   @Delete(':sourceId')
diff --git a/api/src/slices/reins/source/source.module.ts b/api/src/slices/reins/source/source.module.ts
index d7e205ea..ba02d7a4 100644
--- a/api/src/slices/reins/source/source.module.ts
+++ b/api/src/slices/reins/source/source.module.ts
@@ -6,6 +6,7 @@ import { LightragModule } from '../lightrag/lightrag.module';
 import { SourceController } from './source.controller';
 import { SourceService } from './domain/source.service';
 import { ISourceGateway } from './domain/source.gateway';
+import { ImportJobRegistry } from './domain/importJob.registry';
 import { SourceGateway } from './data/source.gateway';
 import { SourceMapper } from './data/source.mapper';
 
@@ -15,6 +16,7 @@ import { SourceMapper } from './data/source.mapper';
   providers: [
     SourceMapper,
     SourceService,
+    ImportJobRegistry,
     { provide: ISourceGateway, useClass: SourceGateway },
   ],
   exports: [SourceService, ISourceGateway],
diff --git a/api/src/slices/reins/source/source.prisma b/api/src/slices/reins/source/source.prisma
index 0d90cbad..d93e1ccc 100644
--- a/api/src/slices/reins/source/source.prisma
+++ b/api/src/slices/reins/source/source.prisma
@@ -20,6 +20,7 @@ model Source {
   updatedAt     DateTime  @updatedAt
 
   @@index([knowledgeId])
+  @@index([knowledgeId, createdAt])
   @@index([lightragDocId])
   @@index([indexState])
 }
diff --git a/bun.lock b/bun.lock
index aab06eb9..2de80ed1 100644
--- a/bun.lock
+++ b/bun.lock
@@ -79,6 +79,7 @@
         "bcrypt": "^6.0.0",
         "class-transformer": "^0.5",
         "class-validator": "^0.14",
+        "multer": "2.1.1",
         "path-to-regexp": "^8.2.0",
         "reflect-metadata": "^0.2.2",
         "rxjs": "^7.8.1",
@@ -99,6 +100,7 @@
         "@types/bcrypt": "^6.0.0",
         "@types/express": "^5.0.0",
         "@types/jest": "^29.5.14",
+        "@types/multer": "^2",
         "@types/node": "^22.10.7",
         "@types/supertest": "^6.0.2",
         "dotenv-cli": "^11.0.0",
@@ -1397,6 +1399,8 @@
 
     "@types/ms": ["@types/ms@2.1.0", "", {}, "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA=="],
 
+    "@types/multer": ["@types/multer@2.2.0", "", { "dependencies": { "@types/express": "*" } }, "sha512-3U1troeqGV8Ntp7Q3klwf4zr23VEoqYVocYXaswm9+8z3O9UHDYAqLxjJ/h550iRADTjKdOdhhasXw6gD6kYtg=="],
+
     "@types/node": ["@types/node@22.19.17", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-wGdMcf+vPYM6jikpS/qhg6WiqSV/OhG+jeeHT/KlVqxYfD40iYJf9/AE1uQxVWFvU7MipKRkRv8NSHiCGgPr8Q=="],
 
     "@types/node-fetch": ["@types/node-fetch@2.6.13", "", { "dependencies": { "@types/node": "*", "form-data": "^4.0.4" } }, "sha512-QGpRVpzSaUs30JBSGPjOg4Uveu384erbHBoT1zeONvyCfwQxIkUshLAOqN/k9EjGviPRmWTTe6aH2qySWKTVSw=="],
@@ -2757,7 +2761,7 @@
 
     "mdn-data": ["mdn-data@2.27.1", "", {}, "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ=="],
 
-    "media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],
+    "media-typer": ["media-typer@0.3.0", "", {}, "sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ=="],
 
     "memfs": ["memfs@3.6.0", "", { "dependencies": { "fs-monkey": "^1.0.4" } }, "sha512-EGowvkkgbMcIChjMTMkESFDbZeSh8xZ7kNSF0hAiAN4Jh6jgHCRS0Ga/+C8y6Au+oqpezRHCfPsmJ2+DwAgiwQ=="],
 
@@ -3489,7 +3493,7 @@
 
     "type-fest": ["type-fest@4.41.0", "", {}, "sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA=="],
 
-    "type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
+    "type-is": ["type-is@1.6.18", "", { "dependencies": { "media-typer": "0.3.0", "mime-types": "~2.1.24" } }, "sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g=="],
 
     "type-level-regexp": ["type-level-regexp@0.1.17", "", {}, "sha512-wTk4DH3cxwk196uGLK/E9pE45aLfeKJacKmcEgEOA/q5dnPGNxXt0cfYdFxb57L+sEpf1oJH4Dnx/pnRcku9jg=="],
 
@@ -4089,6 +4093,8 @@
 
     "anymatch/picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="],
 
+    "api/yaml": ["yaml@2.9.0", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="],
+
     "archiver-utils/glob": ["glob@10.5.0", "", { "dependencies": { "foreground-child": "^3.1.0", "jackspeak": "^3.1.2", "minimatch": "^9.0.4", "minipass": "^7.1.2", "package-json-from-dist": "^1.0.0", "path-scurry": "^1.11.1" }, "bin": { "glob": "dist/esm/bin.mjs" } }, "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg=="],
 
     "archiver-utils/lodash": ["lodash@4.18.1", "", {}, "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q=="],
@@ -4115,6 +4121,8 @@
 
     "bl/readable-stream": ["readable-stream@3.6.2", "", { "dependencies": { "inherits": "^2.0.3", "string_decoder": "^1.1.1", "util-deprecate": "^1.0.1" } }, "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA=="],
 
+    "body-parser/type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
+
     "browserslist/caniuse-lite": ["caniuse-lite@1.0.30001786", "", {}, "sha512-4oxTZEvqmLLrERwxO76yfKM7acZo310U+v4kqexI2TL1DkkUEMT8UijrxxcnVdxR3qkVf5awGRX+4Z6aPHVKrA=="],
 
     "c12/chokidar": ["chokidar@4.0.3", "", { "dependencies": { "readdirp": "^4.0.1" } }, "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA=="],
@@ -4205,6 +4213,8 @@
 
     "express/mime-types": ["mime-types@3.0.2", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
 
+    "express/type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
+
     "ext-list/mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
 
     "fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
@@ -4311,8 +4321,6 @@
 
     "mlly/ufo": ["ufo@1.6.3", "", {}, "sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q=="],
 
-    "multer/type-is": ["type-is@1.6.18", "", { "dependencies": { "media-typer": "0.3.0", "mime-types": "~2.1.24" } }, "sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g=="],
-
     "nitropack/c12": ["c12@3.3.4", "", { "dependencies": { "chokidar": "^5.0.0", "confbox": "^0.2.4", "defu": "^6.1.6", "dotenv": "^17.3.1", "exsolve": "^1.0.8", "giget": "^3.2.0", "jiti": "^2.6.1", "ohash": "^2.0.11", "pathe": "^2.0.3", "perfect-debounce": "^2.1.0", "pkg-types": "^2.3.0", "rc9": "^3.0.1" }, "peerDependencies": { "magicast": "*" }, "optionalPeers": ["magicast"] }, "sha512-cM0ApFQSBXuourJejzwv/AuPRvAxordTyParRVcHjjtXirtkzM0uK2L9TTn9s0cXZbG7E55jCivRQzoxYmRAlA=="],
 
     "nitropack/cookie-es": ["cookie-es@2.0.1", "", {}, "sha512-aVf4A4hI2w70LnF7GG+7xDQUkliwiXWXFvTjkip4+b64ygDQ2sJPRSKFDHbxn8o0xu9QzPkMuuiWIXyFSE2slA=="],
@@ -4473,8 +4481,6 @@
 
     "tsc-alias/commander": ["commander@9.5.0", "", {}, "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ=="],
 
-    "type-is/mime-types": ["mime-types@3.0.2", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
-
     "unbzip2-stream/buffer": ["buffer@5.7.1", "", { "dependencies": { "base64-js": "^1.3.1", "ieee754": "^1.1.13" } }, "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ=="],
 
     "unimport/acorn": ["acorn@8.18.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-lGq+9yr1/GuAWaVYIHRjvvySG5/4VfKIvC8EWxStPdcDh/Ka7FG3twP6v4d5BkravUilhIAsG4Qj83t02LWUPQ=="],
@@ -4969,6 +4975,10 @@
 
     "bin-version/execa/strip-final-newline": ["strip-final-newline@2.0.0", "", {}, "sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA=="],
 
+    "body-parser/type-is/media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],
+
+    "body-parser/type-is/mime-types": ["mime-types@3.0.2", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
+
     "c12/chokidar/readdirp": ["readdirp@4.1.2", "", {}, "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg=="],
 
     "c12/giget/citty": ["citty@0.1.6", "", { "dependencies": { "consola": "^3.2.3" } }, "sha512-tskPPKEs8D2KPafUypv2gxwJP8h/OaJmC82QQGGDQcHvXX43xF2VDACcJVmZ0EuSxkpO9Kc4MlrA3q0+FG58AQ=="],
@@ -5015,6 +5025,8 @@
 
     "express/mime-types/mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
 
+    "express/type-is/media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],
+
     "fork-ts-checker-webpack-plugin/chokidar/readdirp": ["readdirp@4.1.2", "", {}, "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg=="],
 
     "fs-jetpack/minimatch/brace-expansion": ["brace-expansion@2.0.3", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-MCV/fYJEbqx68aE58kv2cA/kiky1G8vux3OR6/jbS+jIMe/6fJWa0DTzJU7dqijOWYwHi1t29FlfYI9uytqlpA=="],
@@ -5057,8 +5069,6 @@
 
     "mlly/pkg-types/confbox": ["confbox@0.1.8", "", {}, "sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w=="],
 
-    "multer/type-is/media-typer": ["media-typer@0.3.0", "", {}, "sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ=="],
-
     "nitropack/c12/exsolve": ["exsolve@1.0.8", "", {}, "sha512-LmDxfWXwcTArk8fUEnOfSZpHOJ6zOMUJKOtFLFqJLoKJetuQG874Uc7/Kki7zFLzYybmZhp1M7+98pfMqeX8yA=="],
 
     "nitropack/c12/giget": ["giget@3.2.0", "", { "bin": { "giget": "dist/cli.mjs" } }, "sha512-GvHTWcykIR/fP8cj8dMpuMMkvaeJfPvYnhq0oW+chSeIr+ldX21ifU2Ms6KBoyKZQZmVaUAAhQ2EZ68KJF8a7A=="],
@@ -5377,8 +5387,6 @@
 
     "tsc-alias/chokidar/readdirp": ["readdirp@3.6.0", "", { "dependencies": { "picomatch": "^2.2.1" } }, "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA=="],
 
-    "type-is/mime-types/mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
-
     "vite-node/vite/lightningcss": ["lightningcss@1.33.0", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.33.0", "lightningcss-darwin-arm64": "1.33.0", "lightningcss-darwin-x64": "1.33.0", "lightningcss-freebsd-x64": "1.33.0", "lightningcss-linux-arm-gnueabihf": "1.33.0", "lightningcss-linux-arm64-gnu": "1.33.0", "lightningcss-linux-arm64-musl": "1.33.0", "lightningcss-linux-x64-gnu": "1.33.0", "lightningcss-linux-x64-musl": "1.33.0", "lightningcss-win32-arm64-msvc": "1.33.0", "lightningcss-win32-x64-msvc": "1.33.0" } }, "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA=="],
 
     "vite-plugin-checker/@babel/code-frame/@babel/helper-validator-identifier": ["@babel/helper-validator-identifier@7.29.7", "", {}, "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg=="],
@@ -5569,6 +5577,8 @@
 
     "bin-version/execa/onetime/mimic-fn": ["mimic-fn@2.1.0", "", {}, "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg=="],
 
+    "body-parser/type-is/mime-types/mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
+
     "c12/giget/nypm/tinyexec": ["tinyexec@0.3.2", "", {}, "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA=="],
 
     "c12/giget/nypm/ufo": ["ufo@1.6.3", "", {}, "sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q=="],

From d9cb119daefc6663ac74c1e69d2ebe5fd7b481bc Mon Sep 17 00:00:00 2001
From: "Maksym Hryzodub [DREAM]" <maksym.hryzodub@dreamvention.com>
Date: Thu, 3 Sep 2026 16:26:00 +0300
Subject: [PATCH 2/2] chore: update .gitignore, increment package version to
 0.3.42, and enhance API schemas

- Added 'worktrees/' to .gitignore to exclude worktree files.
- Bumped package version from 0.3.41 to 0.3.42.
- Extended KnowledgeListItemDtoSchema and related types with new properties: sourceCount, indexedCount, failedCount, and processingCount.
- Introduced SourceDtoSchema, SourcePageDtoSchema, and ImportJobDtoSchema to enhance API data structures.
- Updated KnowledgeSourcesService with new methods for handling source imports and exports.
---
 .gitignore                                    |   1 +
 .../api/data/repositories/api/schemas.gen.ts  | 198 +++++++++++++++++-
 .../api/data/repositories/api/sdk.gen.ts      |  62 +++++-
 .../api/data/repositories/api/types.gen.ts    | 154 +++++++++++++-
 package.json                                  |   2 +-
 5 files changed, 408 insertions(+), 9 deletions(-)

diff --git a/.gitignore b/.gitignore
index ba59b57e..21023dc5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,6 +11,7 @@ api/docker/
 !.env.example
 .envrc
 swagger-spec.json
+worktrees/
 
 # Claude Code subagent scratch
 .claude/
diff --git a/app/slices/setup/api/data/repositories/api/schemas.gen.ts b/app/slices/setup/api/data/repositories/api/schemas.gen.ts
index aac95b51..ed59a1c2 100644
--- a/app/slices/setup/api/data/repositories/api/schemas.gen.ts
+++ b/app/slices/setup/api/data/repositories/api/schemas.gen.ts
@@ -419,6 +419,23 @@ export const KnowledgeListItemDtoSchema = {
       type: "string",
       nullable: true,
     },
+    sourceCount: {
+      type: "number",
+      description: "Sources attached to this knowledge",
+    },
+    indexedCount: {
+      type: "number",
+      description: "Sources LightRAG confirmed as processed",
+    },
+    failedCount: {
+      type: "number",
+      description: "Sources whose last index run recorded an error",
+    },
+    processingCount: {
+      type: "number",
+      description:
+        "Sources handed to LightRAG that it has not finished processing. A ready knowledge with a non-zero count is searchable but not complete yet; run Index again once the pipeline drains.",
+    },
     instanceState: {
       type: "string",
       enum: ["absent", "starting", "ready", "failed", "stopping"],
@@ -454,6 +471,10 @@ export const KnowledgeListItemDtoSchema = {
     "indexError",
     "indexedAt",
     "indexStartedAt",
+    "sourceCount",
+    "indexedCount",
+    "failedCount",
+    "processingCount",
     "instanceState",
     "instanceError",
     "migrationState",
@@ -668,6 +689,174 @@ export const KnowledgeQueryResultDtoSchema = {
   required: ["answer", "knowledgeId", "complete", "references"],
 } as const;
 
+export const SourceDtoSchema = {
+  type: "object",
+  properties: {
+    id: {
+      type: "string",
+    },
+    knowledgeId: {
+      type: "string",
+    },
+    type: {
+      type: "string",
+      enum: ["file", "url", "text"],
+    },
+    name: {
+      type: "string",
+    },
+    url: {
+      type: "string",
+      nullable: true,
+    },
+    mimeType: {
+      type: "string",
+      nullable: true,
+    },
+    content: {
+      type: "string",
+      nullable: true,
+    },
+    sizeBytes: {
+      type: "number",
+      nullable: true,
+    },
+    indexed: {
+      type: "boolean",
+      description:
+        'True when indexStatus is "indexed". Kept for older callers.',
+    },
+    indexStatus: {
+      type: "string",
+      enum: ["indexed", "pending", "failed"],
+    },
+    indexState: {
+      type: "string",
+      enum: ["queued", "processing", "indexed", "failed"],
+    },
+    indexError: {
+      type: "string",
+      nullable: true,
+      description:
+        "Error from the last index run, null once the source indexes.",
+    },
+    indexedAt: {
+      type: "string",
+      nullable: true,
+    },
+    createdAt: {
+      format: "date-time",
+      type: "string",
+    },
+    updatedAt: {
+      format: "date-time",
+      type: "string",
+    },
+  },
+  required: [
+    "id",
+    "knowledgeId",
+    "type",
+    "name",
+    "url",
+    "mimeType",
+    "content",
+    "sizeBytes",
+    "indexed",
+    "indexStatus",
+    "indexState",
+    "indexError",
+    "indexedAt",
+    "createdAt",
+    "updatedAt",
+  ],
+} as const;
+
+export const SourcePageDtoSchema = {
+  type: "object",
+  properties: {
+    items: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/SourceDto",
+      },
+    },
+    total: {
+      type: "number",
+      description: "Rows matching the filter across all pages",
+    },
+    page: {
+      type: "number",
+    },
+    perPage: {
+      type: "number",
+    },
+  },
+  required: ["items", "total", "page", "perPage"],
+} as const;
+
+export const ImportJobDtoSchema = {
+  type: "object",
+  properties: {
+    id: {
+      type: "string",
+    },
+    knowledgeId: {
+      type: "string",
+    },
+    kind: {
+      type: "string",
+      enum: ["archive"],
+    },
+    status: {
+      type: "string",
+      enum: ["running", "done", "failed"],
+    },
+    detected: {
+      type: "number",
+      description: "Ingestable entries found up front",
+    },
+    added: {
+      type: "number",
+    },
+    skipped: {
+      type: "number",
+      description: "Entries skipped because a source with that name exists",
+    },
+    failed: {
+      type: "number",
+    },
+    errors: {
+      description: 'First failures as "<name>: <reason>", capped',
+      type: "array",
+      items: {
+        type: "string",
+      },
+    },
+    startedAt: {
+      format: "date-time",
+      type: "string",
+    },
+    finishedAt: {
+      type: "string",
+      nullable: true,
+    },
+  },
+  required: [
+    "id",
+    "knowledgeId",
+    "kind",
+    "status",
+    "detected",
+    "added",
+    "skipped",
+    "failed",
+    "errors",
+    "startedAt",
+    "finishedAt",
+  ],
+} as const;
+
 export const CreateSourceDtoSchema = {
   type: "object",
   properties: {
@@ -756,14 +945,19 @@ export const AddFromArchiveResultDtoSchema = {
       type: "number",
       example: 288,
       description:
-        "Number of ingestable files detected in the archive. Import runs in the background; refresh the sources list to watch them appear.",
+        "Number of ingestable files detected in the archive. Import runs in the background; poll GET .../sources/imports for progress.",
     },
     started: {
       type: "boolean",
       example: true,
     },
+    jobId: {
+      type: "string",
+      description:
+        "Id of the background import job (see GET .../sources/imports)",
+    },
   },
-  required: ["detected", "started"],
+  required: ["detected", "started", "jobId"],
 } as const;
 
 export const AgentDtoSchema = {
diff --git a/app/slices/setup/api/data/repositories/api/sdk.gen.ts b/app/slices/setup/api/data/repositories/api/sdk.gen.ts
index c43cb65c..ee3e0255 100644
--- a/app/slices/setup/api/data/repositories/api/sdk.gen.ts
+++ b/app/slices/setup/api/data/repositories/api/sdk.gen.ts
@@ -58,7 +58,12 @@ import type {
   QueryKnowledgeData,
   QueryKnowledgeResponse,
   GetKnowledgeSourcesData,
+  GetKnowledgeSourcesResponse,
   AddKnowledgeSourceData,
+  GetKnowledgeSourceImportsData,
+  GetKnowledgeSourceImportsResponse,
+  ExportKnowledgeSourcesData,
+  GetKnowledgeSourceContentData,
   ReindexKnowledgeSourceData,
   AddKnowledgeFileSourcesData,
   AddKnowledgeFileSourcesResponse,
@@ -1164,13 +1169,13 @@ export class KnowledgesService {
 
 export class KnowledgeSourcesService {
   /**
-   * List sources
+   * List sources (paginated)
    */
   public static getKnowledgeSources<ThrowOnError extends boolean = false>(
     options: Options<GetKnowledgeSourcesData, ThrowOnError>,
   ) {
     return (options.client ?? _heyApiClient).get<
-      unknown,
+      GetKnowledgeSourcesResponse,
       unknown,
       ThrowOnError
     >({
@@ -1200,6 +1205,57 @@ export class KnowledgeSourcesService {
     });
   }
 
+  /**
+   * Background imports for this knowledge (running and recent)
+   * Progress of archive imports started through from-archive. Jobs are kept in memory for an hour after they finish.
+   */
+  public static getKnowledgeSourceImports<ThrowOnError extends boolean = false>(
+    options: Options<GetKnowledgeSourceImportsData, ThrowOnError>,
+  ) {
+    return (options.client ?? _heyApiClient).get<
+      GetKnowledgeSourceImportsResponse,
+      unknown,
+      ThrowOnError
+    >({
+      url: "/knowledges/{knowledgeId}/sources/imports",
+      ...options,
+    });
+  }
+
+  /**
+   * Download selected sources as one zip
+   * Selection is either an explicit `ids` list or the same filter the list takes, so "select all" travels as a filter rather than every id. File and text sources become entries; url sources are recorded in the `_ranch-export.yaml` manifest, whose extension the archive importer skips so the zip round-trips through from-archive.
+   */
+  public static exportKnowledgeSources<ThrowOnError extends boolean = false>(
+    options: Options<ExportKnowledgeSourcesData, ThrowOnError>,
+  ) {
+    return (options.client ?? _heyApiClient).get<
+      unknown,
+      unknown,
+      ThrowOnError
+    >({
+      url: "/knowledges/{knowledgeId}/sources/export",
+      ...options,
+    });
+  }
+
+  /**
+   * Stream the stored bytes of a file or text source
+   * Streams the file straight from S3 (or the text body from the row). Not available for url sources - open the url itself.
+   */
+  public static getKnowledgeSourceContent<ThrowOnError extends boolean = false>(
+    options: Options<GetKnowledgeSourceContentData, ThrowOnError>,
+  ) {
+    return (options.client ?? _heyApiClient).get<
+      unknown,
+      unknown,
+      ThrowOnError
+    >({
+      url: "/knowledges/{knowledgeId}/sources/{sourceId}/content",
+      ...options,
+    });
+  }
+
   /**
    * Retry indexing a single source
    * Requeues one source and re-ingests it without touching the rest of the batch. Progress is reported through the source own indexState.
@@ -1257,7 +1313,7 @@ export class KnowledgeSourcesService {
 
   /**
    * Bulk-import sources from a zip archive
-   * Accepts a .zip, extracts every ingestable file (pdf, docx, xlsx, txt, html, ...), and creates one file-type source per entry. Upload runs in the background and streams each entry to S3; the response returns immediately with the detected file count. Indexing into LightRAG happens through the normal reindex flow.
+   * Accepts a .zip, extracts every ingestable file (pdf, docx, xlsx, txt, html, ...), and creates one file-type source per entry. Upload runs in the background and streams each entry to S3; the response returns immediately with the detected file count and a job id to poll via GET .../sources/imports. Indexing into LightRAG happens through the normal reindex flow. Max size: KNOWLEDGE_ARCHIVE_MAX_BYTES (default 4 GiB).
    */
   public static addKnowledgeSourcesFromArchive<
     ThrowOnError extends boolean = false,
diff --git a/app/slices/setup/api/data/repositories/api/types.gen.ts b/app/slices/setup/api/data/repositories/api/types.gen.ts
index 8338a3dc..a8ea27fe 100644
--- a/app/slices/setup/api/data/repositories/api/types.gen.ts
+++ b/app/slices/setup/api/data/repositories/api/types.gen.ts
@@ -183,6 +183,22 @@ export type KnowledgeListItemDto = {
   indexError: string | null;
   indexedAt: string | null;
   indexStartedAt: string | null;
+  /**
+   * Sources attached to this knowledge
+   */
+  sourceCount: number;
+  /**
+   * Sources LightRAG confirmed as processed
+   */
+  indexedCount: number;
+  /**
+   * Sources whose last index run recorded an error
+   */
+  failedCount: number;
+  /**
+   * Sources handed to LightRAG that it has not finished processing. A ready knowledge with a non-zero count is searchable but not complete yet; run Index again once the pipeline drains.
+   */
+  processingCount: number;
   instanceState: "absent" | "starting" | "ready" | "failed" | "stopping";
   instanceError: string | null;
   migrationState: "notStarted" | "inProgress" | "done" | "failed";
@@ -264,6 +280,63 @@ export type KnowledgeQueryResultDto = {
   references: Array<KnowledgeQueryReferenceDto>;
 };
 
+export type SourceDto = {
+  id: string;
+  knowledgeId: string;
+  type: "file" | "url" | "text";
+  name: string;
+  url: string | null;
+  mimeType: string | null;
+  content: string | null;
+  sizeBytes: number | null;
+  /**
+   * True when indexStatus is "indexed". Kept for older callers.
+   */
+  indexed: boolean;
+  indexStatus: "indexed" | "pending" | "failed";
+  indexState: "queued" | "processing" | "indexed" | "failed";
+  /**
+   * Error from the last index run, null once the source indexes.
+   */
+  indexError: string | null;
+  indexedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type SourcePageDto = {
+  items: Array<SourceDto>;
+  /**
+   * Rows matching the filter across all pages
+   */
+  total: number;
+  page: number;
+  perPage: number;
+};
+
+export type ImportJobDto = {
+  id: string;
+  knowledgeId: string;
+  kind: "archive";
+  status: "running" | "done" | "failed";
+  /**
+   * Ingestable entries found up front
+   */
+  detected: number;
+  added: number;
+  /**
+   * Entries skipped because a source with that name exists
+   */
+  skipped: number;
+  failed: number;
+  /**
+   * First failures as "<name>: <reason>", capped
+   */
+  errors: Array<string>;
+  startedAt: string;
+  finishedAt: string | null;
+};
+
 export type CreateSourceDto = {
   type: "file" | "url" | "text";
   name: string;
@@ -302,10 +375,14 @@ export type AddFromSitemapResultDto = {
 
 export type AddFromArchiveResultDto = {
   /**
-   * Number of ingestable files detected in the archive. Import runs in the background; refresh the sources list to watch them appear.
+   * Number of ingestable files detected in the archive. Import runs in the background; poll GET .../sources/imports for progress.
    */
   detected: number;
   started: boolean;
+  /**
+   * Id of the background import job (see GET .../sources/imports)
+   */
+  jobId: string;
 };
 
 export type AgentDto = {
@@ -2127,14 +2204,26 @@ export type GetKnowledgeSourcesData = {
   path: {
     knowledgeId: string;
   };
-  query?: never;
+  query?: {
+    /**
+     * Case-insensitive substring match on the source name
+     */
+    search?: string;
+    status?: "indexed" | "pending" | "failed";
+    type?: "file" | "url" | "text";
+    page?: number;
+    perPage?: number;
+  };
   url: "/knowledges/{knowledgeId}/sources";
 };
 
 export type GetKnowledgeSourcesResponses = {
-  200: unknown;
+  200: SourcePageDto;
 };
 
+export type GetKnowledgeSourcesResponse =
+  GetKnowledgeSourcesResponses[keyof GetKnowledgeSourcesResponses];
+
 export type AddKnowledgeSourceData = {
   body: CreateSourceDto;
   path: {
@@ -2148,6 +2237,65 @@ export type AddKnowledgeSourceResponses = {
   201: unknown;
 };
 
+export type GetKnowledgeSourceImportsData = {
+  body?: never;
+  path: {
+    knowledgeId: string;
+  };
+  query?: never;
+  url: "/knowledges/{knowledgeId}/sources/imports";
+};
+
+export type GetKnowledgeSourceImportsResponses = {
+  200: Array<ImportJobDto>;
+};
+
+export type GetKnowledgeSourceImportsResponse =
+  GetKnowledgeSourceImportsResponses[keyof GetKnowledgeSourceImportsResponses];
+
+export type ExportKnowledgeSourcesData = {
+  body?: never;
+  path: {
+    knowledgeId: string;
+  };
+  query?: {
+    /**
+     * Comma-separated source ids. When present the filter fields are ignored.
+     */
+    ids?: string;
+    /**
+     * Case-insensitive substring match on the source name
+     */
+    search?: string;
+    status?: "indexed" | "pending" | "failed";
+    type?: "file" | "url" | "text";
+  };
+  url: "/knowledges/{knowledgeId}/sources/export";
+};
+
+export type ExportKnowledgeSourcesResponses = {
+  200: unknown;
+};
+
+export type GetKnowledgeSourceContentData = {
+  body?: never;
+  path: {
+    knowledgeId: string;
+    sourceId: string;
+  };
+  query?: {
+    /**
+     * "inline" lets the browser render what it can (pdf, images, text); "attachment" forces a download.
+     */
+    disposition?: "inline" | "attachment";
+  };
+  url: "/knowledges/{knowledgeId}/sources/{sourceId}/content";
+};
+
+export type GetKnowledgeSourceContentResponses = {
+  200: unknown;
+};
+
 export type ReindexKnowledgeSourceData = {
   body?: never;
   path: {
diff --git a/package.json b/package.json
index 4075345e..0995b3c6 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ranch",
-  "version": "0.3.41",
+  "version": "0.3.42",
   "private": true,
   "packageManager": "bun@1.2.12",
   "workspaces": [