diff --git a/drizzle/0019_large_invaders.sql b/drizzle/0019_large_invaders.sql
new file mode 100644
index 0000000..0580b65
--- /dev/null
+++ b/drizzle/0019_large_invaders.sql
@@ -0,0 +1,18 @@
+CREATE TABLE "folders" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"workspace_id" uuid NOT NULL,
+	"parent_id" uuid,
+	"name" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"deleted_at" timestamp with time zone
+);
+--> statement-breakpoint
+ALTER TABLE "sources" ADD COLUMN "folder_id" uuid;--> statement-breakpoint
+ALTER TABLE "folders" ADD CONSTRAINT "folders_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "folders" ADD CONSTRAINT "folders_parent_id_folders_id_fk" FOREIGN KEY ("parent_id") REFERENCES "public"."folders"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "folders_workspace_parent_idx" ON "folders" USING btree ("workspace_id","parent_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "folders_workspace_parent_name_idx" ON "folders" USING btree ("workspace_id","parent_id","name") WHERE deleted_at IS NULL AND parent_id IS NOT NULL;--> statement-breakpoint
+CREATE UNIQUE INDEX "folders_workspace_root_name_idx" ON "folders" USING btree ("workspace_id","name") WHERE deleted_at IS NULL AND parent_id IS NULL;--> statement-breakpoint
+ALTER TABLE "sources" ADD CONSTRAINT "sources_folder_id_folders_id_fk" FOREIGN KEY ("folder_id") REFERENCES "public"."folders"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "sources_workspace_folder_idx" ON "sources" USING btree ("workspace_id","folder_id") WHERE deleted_at IS NULL;
\ No newline at end of file
diff --git a/drizzle/meta/0019_snapshot.json b/drizzle/meta/0019_snapshot.json
new file mode 100644
index 0000000..3c97a48
--- /dev/null
+++ b/drizzle/meta/0019_snapshot.json
@@ -0,0 +1,1136 @@
+{
+  "id": "325d2bfd-d4cf-4c41-baf2-b93fc91afa5e",
+  "prevId": "01b8a746-ca75-4e79-adab-098a03a39e0e",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.chat_messages": {
+      "name": "chat_messages",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "citations": {
+          "name": "citations",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "artifacts": {
+          "name": "artifacts",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "chat_messages_thread_created_idx": {
+          "name": "chat_messages_thread_created_idx",
+          "columns": [
+            {
+              "expression": "thread_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "chat_messages_thread_id_chat_threads_id_fk": {
+          "name": "chat_messages_thread_id_chat_threads_id_fk",
+          "tableFrom": "chat_messages",
+          "tableTo": "chat_threads",
+          "columnsFrom": [
+            "thread_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.chat_threads": {
+      "name": "chat_threads",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "demo_key": {
+          "name": "demo_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "chat_threads_workspace_updated_idx": {
+          "name": "chat_threads_workspace_updated_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": false,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "deleted_at IS NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "chat_threads_workspace_demo_key_idx": {
+          "name": "chat_threads_workspace_demo_key_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "demo_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "chat_threads_workspace_id_workspaces_id_fk": {
+          "name": "chat_threads_workspace_id_workspaces_id_fk",
+          "tableFrom": "chat_threads",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.demo_source_visibilities": {
+      "name": "demo_source_visibilities",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "demo_source_id": {
+          "name": "demo_source_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "hidden_at": {
+          "name": "hidden_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "demo_source_visibilities_workspace_source_idx": {
+          "name": "demo_source_visibilities_workspace_source_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "demo_source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "demo_source_visibilities_workspace_idx": {
+          "name": "demo_source_visibilities_workspace_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "demo_source_visibilities_workspace_id_workspaces_id_fk": {
+          "name": "demo_source_visibilities_workspace_id_workspaces_id_fk",
+          "tableFrom": "demo_source_visibilities",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.folders": {
+      "name": "folders",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "parent_id": {
+          "name": "parent_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "folders_workspace_parent_idx": {
+          "name": "folders_workspace_parent_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "parent_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "folders_workspace_parent_name_idx": {
+          "name": "folders_workspace_parent_name_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "parent_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "deleted_at IS NULL AND parent_id IS NOT NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "folders_workspace_root_name_idx": {
+          "name": "folders_workspace_root_name_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "deleted_at IS NULL AND parent_id IS NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "folders_workspace_id_workspaces_id_fk": {
+          "name": "folders_workspace_id_workspaces_id_fk",
+          "tableFrom": "folders",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "folders_parent_id_folders_id_fk": {
+          "name": "folders_parent_id_folders_id_fk",
+          "tableFrom": "folders",
+          "tableTo": "folders",
+          "columnsFrom": [
+            "parent_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "restrict",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.parsed_document_sync_leases": {
+      "name": "parsed_document_sync_leases",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "document_id": {
+          "name": "document_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "revision_key": {
+          "name": "revision_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "lease_token": {
+          "name": "lease_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "acquired_at": {
+          "name": "acquired_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "released_at": {
+          "name": "released_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "release_reason": {
+          "name": "release_reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "parsed_document_sync_leases_token_idx": {
+          "name": "parsed_document_sync_leases_token_idx",
+          "columns": [
+            {
+              "expression": "lease_token",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "parsed_document_sync_leases_active_idx": {
+          "name": "parsed_document_sync_leases_active_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "released_at IS NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "parsed_document_sync_leases_workspace_active_idx": {
+          "name": "parsed_document_sync_leases_workspace_active_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "released_at IS NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "parsed_document_sync_leases_document_active_idx": {
+          "name": "parsed_document_sync_leases_document_active_idx",
+          "columns": [
+            {
+              "expression": "document_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "released_at IS NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "parsed_document_sync_leases_workspace_id_workspaces_id_fk": {
+          "name": "parsed_document_sync_leases_workspace_id_workspaces_id_fk",
+          "tableFrom": "parsed_document_sync_leases",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "parsed_document_sync_leases_source_id_sources_id_fk": {
+          "name": "parsed_document_sync_leases_source_id_sources_id_fk",
+          "tableFrom": "parsed_document_sync_leases",
+          "tableTo": "sources",
+          "columnsFrom": [
+            "source_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.source_parse_results": {
+      "name": "source_parse_results",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "result_blob_url": {
+          "name": "result_blob_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "snapshot_manifest_url": {
+          "name": "snapshot_manifest_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "snapshot_manifest_key": {
+          "name": "snapshot_manifest_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "revision_key": {
+          "name": "revision_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_status": {
+          "name": "sync_status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_error": {
+          "name": "sync_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "asset_urls": {
+          "name": "asset_urls",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "source_parse_results_source_id_idx": {
+          "name": "source_parse_results_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "source_parse_results_source_id_sources_id_fk": {
+          "name": "source_parse_results_source_id_sources_id_fk",
+          "tableFrom": "source_parse_results",
+          "tableTo": "sources",
+          "columnsFrom": [
+            "source_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "source_parse_results_source_id_unique": {
+          "name": "source_parse_results_source_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "source_id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.sources": {
+      "name": "sources",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "mime_type": {
+          "name": "mime_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "failure_reason": {
+          "name": "failure_reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "failure_stage": {
+          "name": "failure_stage",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "knowhere_job_id": {
+          "name": "knowhere_job_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "knowhere_document_id": {
+          "name": "knowhere_document_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "staged_blob_pathname": {
+          "name": "staged_blob_pathname",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "staged_blob_url": {
+          "name": "staged_blob_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "original_blob_pathname": {
+          "name": "original_blob_pathname",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "original_blob_url": {
+          "name": "original_blob_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "demo_key": {
+          "name": "demo_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chunk_count": {
+          "name": "chunk_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "folder_id": {
+          "name": "folder_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "sources_workspace_created_idx": {
+          "name": "sources_workspace_created_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": false,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "deleted_at IS NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "sources_workspace_status_idx": {
+          "name": "sources_workspace_status_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "sources_workspace_demo_key_idx": {
+          "name": "sources_workspace_demo_key_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "demo_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "sources_workspace_document_idx": {
+          "name": "sources_workspace_document_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "knowhere_document_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "knowhere_document_id IS NOT NULL AND deleted_at IS NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "sources_workspace_folder_idx": {
+          "name": "sources_workspace_folder_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "deleted_at IS NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "sources_workspace_id_workspaces_id_fk": {
+          "name": "sources_workspace_id_workspaces_id_fk",
+          "tableFrom": "sources",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "sources_folder_id_folders_id_fk": {
+          "name": "sources_folder_id_folders_id_fk",
+          "tableFrom": "sources",
+          "tableTo": "folders",
+          "columnsFrom": [
+            "folder_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.workspaces": {
+      "name": "workspaces",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "namespace": {
+          "name": "namespace",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspaces_user_id_idx": {
+          "name": "workspaces_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "workspaces_user_id_unique": {
+          "name": "workspaces_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "user_id"
+          ]
+        },
+        "workspaces_namespace_unique": {
+          "name": "workspaces_namespace_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "namespace"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}
\ No newline at end of file
diff --git a/drizzle/meta/_journal.json b/drizzle/meta/_journal.json
index 8439023..a3a4315 100644
--- a/drizzle/meta/_journal.json
+++ b/drizzle/meta/_journal.json
@@ -134,6 +134,13 @@
       "when": 1789118032723,
       "tag": "0018_source_chunk_count",
       "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1789124024330,
+      "tag": "0019_large_invaders",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/src/agent-harness/answer-context.test.ts b/src/agent-harness/answer-context.test.ts
new file mode 100644
index 0000000..acc5053
--- /dev/null
+++ b/src/agent-harness/answer-context.test.ts
@@ -0,0 +1,203 @@
+import { describe, expect, it, vi } from "vitest"
+
+import { composeAnswerContext } from "./answer-context"
+import type { EvidenceLedgerSnapshot } from "./types"
+
+describe("composeAnswerContext", () => {
+  it("composes retained chunks, full table HTML, images, memory, and the original question", async () => {
+    const readTableHtml = vi.fn().mockResolvedValue(
+      "<table><tr><td>Q4</td><td>24.9</td></tr></table>",
+    )
+    const message = await composeAnswerContext({
+      ledger: makeLedger(),
+      memoryItems: [
+        {
+          ref: "mem:1",
+          itemId: "memory_1",
+          kind: "stance",
+          abstractL0: "关注毛利率",
+          overviewL1: "用户把毛利率当作核心指标。",
+        },
+      ],
+      userText: "Q4 的收入是多少？",
+      readTableHtml,
+    })
+
+    expect(readTableHtml).toHaveBeenCalledWith(
+      "https://assets.example/tables/revenue.html?signature=valid",
+    )
+    expect(message).toEqual({
+      role: "user",
+      content: [
+        {
+          type: "text",
+          text: [
+            "## Evidence from Knowledge Base",
+            "",
+            "[pick 1] report.pdf › Summary",
+            '[artifact type="table" ref="asset:r1:result:1:table_chunk"]',
+            "Revenue increased in Q4.",
+            "<table><tr><td>Q4</td><td>24.9</td></tr></table>",
+            "",
+            '[image ref="asset:r1:result:1:image_chunk_1"]',
+          ].join("\n"),
+        },
+        {
+          type: "image",
+          image: new URL("https://assets.example/images/revenue.png?signature=valid"),
+        },
+        {
+          type: "text",
+          text: '[image ref="asset:r1:result:1:image_chunk_2"]',
+        },
+        {
+          type: "image",
+          image: new URL("https://assets.example/images/margin.png?signature=valid"),
+        },
+        {
+          type: "text",
+          text: [
+            "## Fluid Memory",
+            "",
+            '[memory ref="mem:1" itemId="memory_1" kind="stance"]',
+            "关注毛利率",
+            "用户把毛利率当作核心指标。",
+            "",
+            "## User's Question",
+            "Q4 的收入是多少？",
+          ].join("\n"),
+        },
+      ],
+    })
+  })
+
+  it("omits knowledge and memory sections when neither search ran", async () => {
+    const message = await composeAnswerContext({
+      ledger: { ...makeLedger(), retrievalCount: 0, retainedPicks: [] },
+      memoryItems: [],
+      userText: "直接回答。",
+    })
+
+    expect(message).toEqual({
+      role: "user",
+      content: [{ type: "text", text: "## User's Question\n直接回答。" }],
+    })
+  })
+
+  it("notes when knowledge base search ran but found nothing to retain", async () => {
+    const message = await composeAnswerContext({
+      ledger: { ...makeLedger(), retainedPicks: [] },
+      memoryItems: [],
+      userText: "直接回答。",
+    })
+
+    expect(message).toEqual({
+      role: "user",
+      content: [
+        {
+          type: "text",
+          text: [
+            "## Evidence from Knowledge Base",
+            "No knowledge base results were found for this search. Answer using your own knowledge only, and say so if relevant.",
+            "",
+            "## User's Question",
+            "直接回答。",
+          ].join("\n"),
+        },
+      ],
+    })
+  })
+
+  it("notes when memory search ran but found nothing", async () => {
+    const message = await composeAnswerContext({
+      ledger: { ...makeLedger(), retrievalCount: 0, retainedPicks: [] },
+      memoryItems: [],
+      memorySearchAttempted: true,
+      userText: "直接回答。",
+    })
+
+    expect(message).toEqual({
+      role: "user",
+      content: [
+        {
+          type: "text",
+          text: [
+            "## Fluid Memory",
+            "No fluid memory results were found for this search.",
+            "",
+            "## User's Question",
+            "直接回答。",
+          ].join("\n"),
+        },
+      ],
+    })
+  })
+})
+
+function makeLedger(): EvidenceLedgerSnapshot {
+  return {
+    retrievalCount: 1,
+    chunks: [
+      {
+        ref: "r1:result:1",
+        kind: "result",
+        content: "Revenue increased in Q4.\n[Table: tables/revenue.html]",
+        contentPreview: "Revenue increased in Q4. [Table: tables/revenue.html]",
+        chunkType: "text",
+        score: 0.9,
+        source: {
+          documentId: "doc_1",
+          sourceFileName: "report.pdf",
+          sectionPath: "Summary",
+        },
+      },
+    ],
+    assets: [
+      {
+        ref: "asset:r1:result:1:table_chunk",
+        chunkRef: "r1:result:1",
+        type: "table",
+        assetUrl: "https://assets.example/tables/revenue.html?signature=valid",
+        sourcePath: "tables/revenue.html",
+        source: {
+          documentId: "doc_1",
+          sourceFileName: "report.pdf",
+          sectionPath: "Summary",
+        },
+        label: "report.pdf / Summary / tables/revenue.html / table",
+      },
+      {
+        ref: "asset:r1:result:1:image_chunk_1",
+        chunkRef: "r1:result:1",
+        type: "image",
+        assetUrl: "https://assets.example/images/revenue.png?signature=valid",
+        sourcePath: "images/revenue.png",
+        source: {
+          documentId: "doc_1",
+          sourceFileName: "report.pdf",
+          sectionPath: "Summary",
+        },
+        label: "report.pdf / Summary / images/revenue.png / image",
+      },
+      {
+        ref: "asset:r1:result:1:image_chunk_2",
+        chunkRef: "r1:result:1",
+        type: "image",
+        assetUrl: "https://assets.example/images/margin.png?signature=valid",
+        sourcePath: "images/margin.png",
+        source: {
+          documentId: "doc_1",
+          sourceFileName: "report.pdf",
+          sectionPath: "Summary",
+        },
+        label: "report.pdf / Summary / images/margin.png / image",
+      },
+    ],
+    evidenceText: [],
+    stopReasons: [],
+    failureReasons: [],
+    decisionTraces: [],
+    retainedPicks: [1],
+    pendingRetention: null,
+  }
+}
diff --git a/src/agent-harness/answer-context.ts b/src/agent-harness/answer-context.ts
new file mode 100644
index 0000000..3a6ff8e
--- /dev/null
+++ b/src/agent-harness/answer-context.ts
@@ -0,0 +1,205 @@
+import type { ModelMessage } from "ai"
+
+import type {
+  EvidenceAsset,
+  EvidenceChunk,
+  EvidenceLedgerSnapshot,
+  MemorySearchItem,
+} from "./types"
+
+export type ReadTableHtml = (assetUrl: string) => Promise<string>
+type UserContentParts = Exclude<
+  Extract<ModelMessage, { role: "user" }>["content"],
+  string
+>
+
+export async function composeAnswerContext(input: {
+  readonly ledger: EvidenceLedgerSnapshot
+  readonly memoryItems: readonly MemorySearchItem[]
+  readonly memorySearchAttempted?: boolean
+  readonly userText: string
+  readonly readTableHtml?: ReadTableHtml
+}): Promise<ModelMessage> {
+  const content: UserContentParts = []
+  const retainedPicks = new Set(input.ledger.retainedPicks)
+  const assetsByChunkRef = groupAssetsByChunkRef(input.ledger.assets)
+
+  const retainedChunks = input.ledger.chunks.flatMap((chunk, index) => {
+    const pick = index + 1
+    return retainedPicks.has(pick) ? [{ chunk, pick }] : []
+  })
+
+  if (retainedChunks.length === 0 && input.ledger.retrievalCount > 0) {
+    appendText(
+      content,
+      "## Evidence from Knowledge Base\nNo knowledge base results were found for this search. Answer using your own knowledge only, and say so if relevant.",
+    )
+  }
+
+  if (retainedChunks.length > 0) {
+    appendText(content, "## Evidence from Knowledge Base")
+    for (const { chunk, pick } of retainedChunks) {
+      const assets = assetsByChunkRef.get(chunk.ref) ?? []
+      let chunkText = chunk.content
+      for (const table of assets.filter((asset) => asset.type === "table")) {
+        chunkText = await replaceTableWithHtml({
+          chunk: { ...chunk, content: chunkText },
+          asset: table,
+          readTableHtml: input.readTableHtml,
+        })
+      }
+
+      appendText(
+        content,
+        [
+          formatChunkLabel(pick, chunk),
+          formatTableArtifactRefs(assets),
+          chunkText.trim(),
+        ]
+          .filter((part) => part.length > 0)
+          .join("\n"),
+      )
+
+      for (const image of assets.filter((asset) => asset.type === "image")) {
+        if (!image.assetUrl) {
+          throw new Error(`Retained image asset ${image.ref} has no signed URL.`)
+        }
+        appendText(content, `[image ref="${image.ref}"]`)
+        content.push({
+          type: "image",
+          image: new URL(image.assetUrl),
+        })
+      }
+    }
+  }
+
+  if (input.memoryItems.length > 0) {
+    appendText(content, [
+      "## Fluid Memory",
+      ...input.memoryItems.map(formatMemoryItem),
+    ].join("\n\n"))
+  } else if (input.memorySearchAttempted) {
+    appendText(
+      content,
+      "## Fluid Memory\nNo fluid memory results were found for this search.",
+    )
+  }
+
+  const userText = input.userText.trim()
+  if (userText) {
+    appendText(content, `## User's Question\n${userText}`)
+  }
+
+  return { role: "user", content }
+}
+
+function groupAssetsByChunkRef(
+  assets: readonly EvidenceAsset[],
+): Map<string, EvidenceAsset[]> {
+  const grouped = new Map<string, EvidenceAsset[]>()
+  for (const asset of assets) {
+    const chunkAssets = grouped.get(asset.chunkRef) ?? []
+    chunkAssets.push(asset)
+    grouped.set(asset.chunkRef, chunkAssets)
+  }
+  return grouped
+}
+
+function formatTableArtifactRefs(assets: readonly EvidenceAsset[]): string {
+  return assets
+    .filter((asset) => asset.type === "table")
+    .map((asset) => `[artifact type="${asset.type}" ref="${asset.ref}"]`)
+    .join("\n")
+}
+
+function appendText(
+  content: UserContentParts,
+  text: string,
+): void {
+  const trimmed = text.trim()
+  if (!trimmed) return
+  const previous = content.at(-1)
+  if (previous?.type === "text") {
+    previous.text = `${previous.text}\n\n${trimmed}`
+    return
+  }
+  content.push({ type: "text", text: trimmed })
+}
+
+function formatChunkLabel(pick: number, chunk: EvidenceChunk): string {
+  const location = [chunk.source.sourceFileName, chunk.source.sectionPath]
+    .map((part) => part?.trim())
+    .filter((part): part is string => Boolean(part))
+    .join(" › ")
+  return location ? `[pick ${pick}] ${location}` : `[pick ${pick}]`
+}
+
+function formatMemoryItem(item: MemorySearchItem): string {
+  return [
+    `[memory ref="${item.ref}" itemId="${item.itemId}" kind="${item.kind}"]`,
+    item.abstractL0.trim(),
+    item.overviewL1.trim(),
+  ]
+    .filter((part) => part.length > 0)
+    .join("\n")
+}
+
+async function replaceTableWithHtml(input: {
+  readonly chunk: EvidenceChunk
+  readonly asset: EvidenceAsset
+  readonly readTableHtml?: ReadTableHtml
+}): Promise<string> {
+  if (!input.asset.assetUrl) {
+    throw new Error(`Retained table asset ${input.asset.ref} has no signed URL.`)
+  }
+  if (!input.readTableHtml) {
+    throw new Error("No table HTML reader was provided for retained table evidence.")
+  }
+
+  const html = await input.readTableHtml(input.asset.assetUrl)
+  const content = input.chunk.content
+  if (!content.trim()) return html
+
+  const placeholders = getTablePlaceholderCandidates(input.chunk, input.asset)
+  const placeholderPattern = placeholders
+    .map(escapeRegExp)
+    .sort((left, right) => right.length - left.length)
+    .map((placeholder) =>
+      `\\[(?:Table\\s*:\\s*)?${placeholder}\\]|${placeholder}`,
+    )
+    .join("|")
+  const replaced = content.replace(
+    new RegExp(placeholderPattern, "gi"),
+    () => html,
+  )
+
+  if (replaced === content) {
+    throw new Error(
+      `Table placeholder for ${input.asset.ref} was not found in its chunk content.`,
+    )
+  }
+  return replaced
+}
+
+function getTablePlaceholderCandidates(
+  chunk: EvidenceChunk,
+  asset: EvidenceAsset,
+): string[] {
+  const candidates = [
+    asset.sourcePath,
+    chunk.filePath,
+    chunk.sourceChunkPath,
+    asset.assetUrl,
+  ]
+  const unique: string[] = []
+  for (const candidate of candidates) {
+    const trimmed = candidate?.trim()
+    if (!trimmed || unique.includes(trimmed)) continue
+    unique.push(trimmed)
+  }
+  return unique
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
diff --git a/src/agent-harness/index.ts b/src/agent-harness/index.ts
index 40e843b..c2b33ee 100644
--- a/src/agent-harness/index.ts
+++ b/src/agent-harness/index.ts
@@ -1,3 +1,4 @@
+export * from "./answer-context"
 export * from "./image-highlights"
 export * from "./ledger"
 export * from "./knowhere-text"
diff --git a/src/agent-harness/knowhere-text.test.ts b/src/agent-harness/knowhere-text.test.ts
index af1094e..c07564e 100644
--- a/src/agent-harness/knowhere-text.test.ts
+++ b/src/agent-harness/knowhere-text.test.ts
@@ -23,10 +23,12 @@ describe("knowhereToolText", () => {
     expect(text).toContain('ref="r1:result:1"')
     expect(text).toContain('ref="asset:r1:result:1"')
     expect(text).toContain("Page one summary.")
-    expect(text).toContain("Call inspectImage")
-    expect(text).toContain("before finalize")
+    expect(text).not.toContain("inspectImage")
+    expect(text).not.toContain("asset_instruction")
     expect(text).not.toContain("<evidence>")
     expect(text).not.toContain("Page one evidence.")
+    expect(text).not.toContain("referencedChunkCount")
+    expect(text).not.toContain("provenance-only-id")
     expect(text).not.toContain("https://assets.example/page-1.png")
   })
 
@@ -81,6 +83,12 @@ function makeSearchResponse(): RetrievalQueryResponse {
         },
       },
     ],
-    referencedChunks: [],
+    referencedChunks: [
+      {
+        documentId: "doc_1",
+        chunkId: "provenance-only-id",
+        pageNums: [],
+      },
+    ] as unknown as RetrievalQueryResponse["referencedChunks"],
   }
 }
diff --git a/src/agent-harness/knowhere-text.ts b/src/agent-harness/knowhere-text.ts
index 5f55ff7..c3a4cc6 100644
--- a/src/agent-harness/knowhere-text.ts
+++ b/src/agent-harness/knowhere-text.ts
@@ -20,9 +20,6 @@ type ErrorTextInput = {
 
 type KnowhereOperation = "search"
 
-const assetInstruction =
-  "Notebook returned image/page asset refs. Call inspectImage with the asset refs you will cite before finalize so OCR/visual context and provenance boxes exist. Do not expose raw asset URLs."
-
 export const knowhereToolText = {
   formatSearch(input: SearchTextInput): string {
     return wrapKnowhereBlock("search", [
@@ -31,7 +28,6 @@ export const knowhereToolText = {
         namespace: input.response.namespace,
         query: input.response.query,
         resultCount: String(input.response.results.length),
-        referencedChunkCount: String(input.response.referencedChunks.length),
         stopReason: input.response.stopReason ?? undefined,
         failureReason: input.response.failureReason ?? undefined,
       }),
@@ -39,7 +35,6 @@ export const knowhereToolText = {
       // evidenceText — same bodies, no citeable refs, doubles context.
       formatEvidenceChunks(input.chunks, input.chunkPickStart),
       formatEvidenceAssets(input.assets),
-      formatAssetInstruction(input.assets),
     ])
   },
 
@@ -88,7 +83,6 @@ function formatEvidenceChunks(
           sectionPath: chunk.source.sectionPath ?? undefined,
           sourceChunkPath: chunk.sourceChunkPath ?? undefined,
           filePath: chunk.filePath ?? undefined,
-          assetRef: chunk.assetRef,
         }),
         formatTextTag("content", chunk.content),
         "</chunk>",
@@ -119,11 +113,6 @@ function formatEvidenceAssets(assets: readonly EvidenceAsset[]): string {
   ].join("\n")
 }
 
-function formatAssetInstruction(assets: readonly EvidenceAsset[]): string {
-  if (!assets.some((asset) => asset.type === "image")) return ""
-  return formatTextTag("asset_instruction", assetInstruction)
-}
-
 function formatTextTag(tagName: string, value: string): string {
   return [`<${tagName}>`, value, `</${tagName}>`].join("\n")
 }
diff --git a/src/agent-harness/ledger.test.ts b/src/agent-harness/ledger.test.ts
index 6d3bdb3..5afd958 100644
--- a/src/agent-harness/ledger.test.ts
+++ b/src/agent-harness/ledger.test.ts
@@ -1,7 +1,8 @@
-import { describe, expect, it } from "vitest"
+import { describe, expect, it, vi } from "vitest"
 import type { RetrievalQueryResponse } from "@ontos-ai/knowhere-sdk"
 
 import { createEvidenceLedger } from "./ledger"
+import type { ResolveConnectedAssets } from "./types"
 
 describe("createEvidenceLedger", () => {
   it("normalizes retrieval chunks and media assets without treating candidates as final output", () => {
@@ -177,17 +178,178 @@ describe("createEvidenceLedger", () => {
           },
         },
       ],
-      // Real agent_explore responses can return referencedChunks entries
-      // that only carry a summary id, with no chunkType/chunkId/documentId
-      // even though the SDK type declares those as required strings.
+      // Real agent_explore responses carry provenance IDs without evidence
+      // fields even though the SDK type declares chunkType as required.
       referencedChunks: [
-        { summary: "8da0776b-c52b-5602-8579-25c421706f5f" },
+        {
+          documentId: "doc_1",
+          chunkId: "8da0776b-c52b-5602-8579-25c421706f5f",
+          pageNums: [],
+        },
       ] as unknown as RetrievalQueryResponse["referencedChunks"],
     })
 
     expect(snapshot.chunks.map((chunk) => chunk.ref)).toEqual(["r1:result:1"])
     expect(snapshot.chunks[0]?.content).toBe("Target BP is <130/80 mmHg.")
   })
+
+  it("opens a pending retention range for new chunks and keeps only retained picks", () => {
+    const ledger = createEvidenceLedger()
+    const snapshot = ledger.addRetrievalResponse(makeRetrievalResponse())
+
+    expect(snapshot.pendingRetention).toEqual({ startPick: 1, endPick: 3 })
+    expect(snapshot.retainedPicks).toEqual([])
+    expect(ledger.hasPendingRetention()).toBe(true)
+
+    const retained = ledger.retainPicks([1, 3])
+    expect(retained).toEqual({ ok: true, retainedPicks: [1, 3] })
+    expect(ledger.hasPendingRetention()).toBe(false)
+    expect(ledger.isRetained(1)).toBe(true)
+    expect(ledger.isRetained(2)).toBe(false)
+    expect(ledger.isRetained(3)).toBe(true)
+    expect(ledger.snapshot().pendingRetention).toBeNull()
+    expect(ledger.snapshot().retainedPicks).toEqual([1, 3])
+  })
+
+  it("does not open pending retention when a search adds no chunks", () => {
+    const ledger = createEvidenceLedger()
+    const snapshot = ledger.addRetrievalResponse({
+      namespace: "notebook",
+      query: "empty",
+      routerUsed: "workflow_single_step",
+      answerText: null,
+      evidenceText: "No hits",
+      stopReason: "completed",
+      failureReason: null,
+      results: [],
+      referencedChunks: [],
+    })
+
+    expect(snapshot.chunks).toEqual([])
+    expect(snapshot.pendingRetention).toBeNull()
+    expect(ledger.hasPendingRetention()).toBe(false)
+    expect(ledger.retainPicks([])).toMatchObject({ ok: false })
+  })
+
+  it("rejects retain picks outside the latest search without changing state", () => {
+    const ledger = createEvidenceLedger()
+    ledger.addRetrievalResponse(makeRetrievalResponse())
+
+    expect(ledger.retainPicks([4])).toMatchObject({
+      ok: false,
+      invalidPicks: [4],
+    })
+    expect(ledger.hasPendingRetention()).toBe(true)
+    expect(ledger.snapshot().retainedPicks).toEqual([])
+  })
+
+  it("locks unretained first-search picks after a later search is retained", () => {
+    const ledger = createEvidenceLedger()
+    ledger.addRetrievalResponse(makeRetrievalResponse())
+    expect(ledger.retainPicks([])).toMatchObject({ ok: true, retainedPicks: [] })
+
+    ledger.addRetrievalResponse({
+      ...makeRetrievalResponse(),
+      results: [
+        {
+          content: "Second retrieval evidence.",
+          chunkType: "text",
+          score: 0.8,
+          source: {
+            documentId: "doc_2",
+            sourceFileName: "second.pdf",
+            sectionPath: "Second",
+          },
+        },
+      ],
+      referencedChunks: [],
+    })
+    expect(ledger.pendingRetentionRange()).toEqual({ startPick: 4, endPick: 4 })
+    expect(ledger.retainPicks([4])).toMatchObject({
+      ok: true,
+      retainedPicks: [4],
+    })
+    expect(ledger.isRetained(1)).toBe(false)
+    expect(ledger.isRetained(4)).toBe(true)
+  })
+
+  it("resolves every embedded table and image connected to retained text", async () => {
+    const ledger = createEvidenceLedger()
+    ledger.addRetrievalResponse({
+      ...makeRetrievalResponse(),
+      results: [
+        {
+          chunkId: "text_chunk",
+          content: "Comparison [tables/comparison.html]",
+          chunkType: "text",
+          score: 0.9,
+          metadata: {
+            connectTo: [
+              {
+                target: "table_chunk",
+                relation: "embeds",
+                ref: "[tables/comparison.html]",
+              },
+              {
+                target: "image_chunk_1",
+                relation: "embeds",
+                ref: "[images/comparison-a.jpg]",
+              },
+              {
+                target: "image_chunk_2",
+                relation: "embeds",
+                ref: "[images/comparison-b.jpg]",
+              },
+            ],
+          },
+          source: {
+            documentId: "doc_1",
+            sourceFileName: "cardiology.pdf",
+            sectionPath: "Differential diagnosis",
+          },
+        },
+      ],
+      referencedChunks: [],
+    })
+    ledger.retainPicks([1])
+    const resolveConnectedAssets = vi.fn<ResolveConnectedAssets>(
+      async (lookups) =>
+        lookups.map((lookup) => ({
+          ...lookup,
+          assetUrl: `https://assets.example/${lookup.chunkId}`,
+        })),
+    )
+
+    const snapshot = await ledger.resolveRetainedConnectedAssets(
+      resolveConnectedAssets,
+    )
+
+    expect(resolveConnectedAssets).toHaveBeenCalledWith([
+      { documentId: "doc_1", chunkId: "table_chunk", type: "table" },
+      { documentId: "doc_1", chunkId: "image_chunk_1", type: "image" },
+      { documentId: "doc_1", chunkId: "image_chunk_2", type: "image" },
+    ])
+    expect(snapshot.assets).toEqual([
+      expect.objectContaining({
+        ref: "asset:r1:result:1:table_chunk",
+        chunkRef: "r1:result:1",
+        type: "table",
+        sourcePath: "tables/comparison.html",
+      }),
+      expect.objectContaining({
+        ref: "asset:r1:result:1:image_chunk_1",
+        chunkRef: "r1:result:1",
+        type: "image",
+        sourcePath: "images/comparison-a.jpg",
+      }),
+      expect.objectContaining({
+        ref: "asset:r1:result:1:image_chunk_2",
+        chunkRef: "r1:result:1",
+        type: "image",
+        sourcePath: "images/comparison-b.jpg",
+      }),
+    ])
+  })
 })
 
 function makeRetrievalResponse(): RetrievalQueryResponse {
diff --git a/src/agent-harness/ledger.ts b/src/agent-harness/ledger.ts
index 9c80448..4cd3123 100644
--- a/src/agent-harness/ledger.ts
+++ b/src/agent-harness/ledger.ts
@@ -7,7 +7,10 @@ import type {
   EvidenceAsset,
   EvidenceChunk,
   EvidenceLedgerSnapshot,
+  PendingRetentionRange,
+  ResolveConnectedAssets,
 } from "./types"
+import { hasReferencedChunkEvidence } from "./referenced-chunks"
 
 const contentPreviewLimit = 1_200
 const imageExtensions = [".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg"] as const
@@ -20,6 +23,8 @@ type MutableLedger = {
   stopReasons: string[]
   failureReasons: string[]
   decisionTraces: unknown[]
+  retainedPicks: Set<number>
+  pendingRetention: PendingRetentionRange | null
 }
 
 type EvidenceAssetCandidate = {
@@ -29,6 +34,15 @@ type EvidenceAssetCandidate = {
   readonly label: string
 }
 
+type ConnectedAssetCandidate = {
+  readonly chunkRef: string
+  readonly targetChunkId: string
+  readonly documentId: string
+  readonly type: EvidenceAsset["type"]
+  readonly sourcePath: string
+  readonly source: EvidenceChunk["source"]
+}
+
 type PageCitationAssetCandidate = {
   readonly pageNum: number
   readonly artifactRef?: string
@@ -47,10 +61,13 @@ export function createEvidenceLedger() {
     stopReasons: [],
     failureReasons: [],
     decisionTraces: [],
+    retainedPicks: new Set<number>(),
+    pendingRetention: null,
   }
 
   return {
     addRetrievalResponse(response: RetrievalQueryResponse): EvidenceLedgerSnapshot {
+      const chunkCountBefore = ledger.chunks.length
       ledger.retrievalCount += 1
       const retrievalIndex = ledger.retrievalCount
 
@@ -76,15 +93,9 @@ export function createEvidenceLedger() {
       })
 
       response.referencedChunks.forEach((chunk, index) => {
-        // Knowhere's agent_explore router returns referencedChunks entries
-        // that may carry only a summary id with no chunkType/content
-        // (despite the SDK type declaring chunkType as required). Skip
-        // entries missing a usable chunkType: they have no real content
-        // (content is always "" here) and chunkType is required downstream
-        // (asset-type detection calls chunkType.toLowerCase()).
-        if (typeof chunk.chunkType !== "string" || chunk.chunkType.trim().length === 0) {
-          return
-        }
+        // ID-only references are provenance, not evidence. Structured page
+        // and media references remain available to the citation pipeline.
+        if (!hasReferencedChunkEvidence(chunk)) return
         const content = ""
         addChunk({
           ledger,
@@ -110,6 +121,121 @@ export function createEvidenceLedger() {
         })
       })
 
+      const chunkCountAfter = ledger.chunks.length
+      if (chunkCountAfter > chunkCountBefore) {
+        ledger.pendingRetention = {
+          startPick: chunkCountBefore + 1,
+          endPick: chunkCountAfter,
+        }
+      }
+
+      return snapshot(ledger)
+    },
+
+    retainPicks(picks: readonly number[]):
+      | { readonly ok: true; readonly retainedPicks: readonly number[] }
+      | {
+          readonly ok: false
+          readonly message: string
+          readonly invalidPicks: readonly number[]
+        } {
+      const pending = ledger.pendingRetention
+      if (!pending) {
+        return {
+          ok: false,
+          message:
+            "retainEvidence can only be called after a search that returned new evidence.",
+          invalidPicks: [],
+        }
+      }
+
+      const kept: number[] = []
+      const invalidPicks: number[] = []
+      for (const pick of picks) {
+        if (
+          !Number.isInteger(pick) ||
+          pick < pending.startPick ||
+          pick > pending.endPick
+        ) {
+          if (!invalidPicks.includes(pick)) invalidPicks.push(pick)
+          continue
+        }
+        if (!kept.includes(pick)) kept.push(pick)
+      }
+      if (invalidPicks.length > 0) {
+        return {
+          ok: false,
+          message: [
+            "retainEvidence picks must come from the latest search.",
+            `Invalid picks: ${invalidPicks.join(" ")}.`,
+            `Latest search picks: ${pending.startPick}-${pending.endPick}.`,
+          ].join(" "),
+          invalidPicks,
+        }
+      }
+
+      for (const pick of kept) {
+        ledger.retainedPicks.add(pick)
+      }
+      ledger.pendingRetention = null
+      return {
+        ok: true,
+        retainedPicks: [...ledger.retainedPicks].sort((left, right) => left - right),
+      }
+    },
+
+    isRetained(pick: number): boolean {
+      return ledger.retainedPicks.has(pick)
+    },
+
+    hasPendingRetention(): boolean {
+      return ledger.pendingRetention !== null
+    },
+
+    pendingRetentionRange(): PendingRetentionRange | null {
+      return ledger.pendingRetention
+    },
+
+    async resolveRetainedConnectedAssets(
+      resolveConnectedAssets?: ResolveConnectedAssets,
+    ): Promise<EvidenceLedgerSnapshot> {
+      const candidates = getRetainedConnectedAssetCandidates(ledger)
+      if (candidates.length === 0) return snapshot(ledger)
+      if (!resolveConnectedAssets) {
+        throw new Error(
+          "No connected asset resolver was provided for retained evidence.",
+        )
+      }
+
+      const lookups = uniqueConnectedAssetLookups(candidates)
+      const resolved = await resolveConnectedAssets(lookups)
+      const assetUrlByLookup = new Map(
+        resolved.map((asset) => [connectedAssetLookupKey(asset), asset.assetUrl]),
+      )
+
+      for (const candidate of candidates) {
+        const lookupKey = connectedAssetLookupKey({
+          documentId: candidate.documentId,
+          chunkId: candidate.targetChunkId,
+          type: candidate.type,
+        })
+        const assetUrl = assetUrlByLookup.get(lookupKey)
+        if (!assetUrl) {
+          throw new Error(
+            `Connected ${candidate.type} chunk ${candidate.targetChunkId} was not resolved.`,
+          )
+        }
+        ledger.assets.push({
+          ref: `asset:${candidate.chunkRef}:${candidate.targetChunkId}`,
+          chunkRef: candidate.chunkRef,
+          type: candidate.type,
+          assetUrl,
+          sourcePath: candidate.sourcePath,
+          source: candidate.source,
+          label: formatConnectedAssetLabel(candidate),
+        })
+      }
+
       return snapshot(ledger)
     },
 
@@ -183,7 +309,7 @@ function addChunkFromResult(input: {
 
 function addChunk(input: {
   readonly ledger: MutableLedger
-  readonly chunk: Omit<EvidenceChunk, "assetRef">
+  readonly chunk: EvidenceChunk
 }): void {
   const asset = getEvidenceAssetCandidate(input.chunk)
   if (!asset) {
@@ -192,23 +318,96 @@ function addChunk(input: {
   }
 
   const assetRef = `asset:${input.chunk.ref}`
-  const chunk: EvidenceChunk = {
-    ...input.chunk,
-    assetRef,
-  }
-  input.ledger.chunks.push(chunk)
+  input.ledger.chunks.push(input.chunk)
   input.ledger.assets.push({
     ref: assetRef,
-    chunkRef: chunk.ref,
+    chunkRef: input.chunk.ref,
     type: asset.type,
     ...(asset.assetUrl ? { assetUrl: asset.assetUrl } : {}),
     ...(asset.sourcePath ? { sourcePath: asset.sourcePath } : {}),
-    ...(chunk.revisionKey ? { revisionKey: chunk.revisionKey } : {}),
-    source: chunk.source,
+    ...(input.chunk.revisionKey ? { revisionKey: input.chunk.revisionKey } : {}),
+    source: input.chunk.source,
     label: asset.label,
   })
 }
 
+function getRetainedConnectedAssetCandidates(
+  ledger: MutableLedger,
+): ConnectedAssetCandidate[] {
+  return ledger.chunks.flatMap((chunk, index) => {
+    if (!ledger.retainedPicks.has(index + 1)) return []
+
+    const documentId = getTrimmedString(chunk.source.documentId)
+    const connections = chunk.metadata?.connectTo ?? chunk.metadata?.connect_to
+    if (!Array.isArray(connections)) return []
+
+    return connections.flatMap((connection): ConnectedAssetCandidate[] => {
+      if (!isRecord(connection) || connection.relation !== "embeds") return []
+      const targetChunkId = getTrimmedString(connection.target)
+      const sourcePath = getConnectedAssetPath(connection.ref)
+      if (!targetChunkId || !sourcePath) return []
+      if (!documentId) {
+        throw new Error(
+          `Retained evidence ${chunk.ref} has connected assets but no document ID.`,
+        )
+      }
+
+      return [{
+        chunkRef: chunk.ref,
+        targetChunkId,
+        documentId,
+        type: sourcePath.startsWith("images/") ? "image" : "table",
+        sourcePath,
+        source: chunk.source,
+      }]
+    })
+  })
+}
+
+function getConnectedAssetPath(value: unknown): string | null {
+  const ref = getTrimmedString(value)
+  if (!ref || !ref.startsWith("[") || !ref.endsWith("]")) return null
+  const path = ref.slice(1, -1).trim()
+  return path.startsWith("images/") || path.startsWith("tables/") ? path : null
+}
+
+function uniqueConnectedAssetLookups(
+  candidates: readonly ConnectedAssetCandidate[],
+) {
+  const lookups = new Map<
+    string,
+    { documentId: string; chunkId: string; type: EvidenceAsset["type"] }
+  >()
+  for (const candidate of candidates) {
+    const lookup = {
+      documentId: candidate.documentId,
+      chunkId: candidate.targetChunkId,
+      type: candidate.type,
+    }
+    lookups.set(connectedAssetLookupKey(lookup), lookup)
+  }
+  return [...lookups.values()]
+}
+
+function connectedAssetLookupKey(input: {
+  readonly documentId: string
+  readonly chunkId: string
+  readonly type: EvidenceAsset["type"]
+}): string {
+  return `${input.documentId}\u0000${input.type}\u0000${input.chunkId}`
+}
+
+function formatConnectedAssetLabel(candidate: ConnectedAssetCandidate): string {
+  return [
+    candidate.source.sourceFileName,
+    candidate.source.sectionPath,
+    candidate.sourcePath,
+    candidate.type,
+  ]
+    .filter((part): part is string => Boolean(part))
+    .join(" / ")
+}
+
 function buildContentPreview(content: string): string {
   const normalized = content.replace(/\s+/g, " ").trim()
   if (normalized.length <= contentPreviewLimit) return normalized
@@ -233,7 +432,7 @@ function isRenderableAsset(chunkType: string, assetUrl: string): boolean {
 }
 
 function getEvidenceAssetCandidate(
-  chunk: Omit<EvidenceChunk, "assetRef">,
+  chunk: EvidenceChunk,
 ): EvidenceAssetCandidate | null {
   const pageAsset = getPageCitationAssetCandidate(chunk)
   if (pageAsset) {
@@ -253,7 +452,7 @@ function getEvidenceAssetCandidate(
 }
 
 function getPageCitationAssetCandidate(
-  chunk: Omit<EvidenceChunk, "assetRef">,
+  chunk: EvidenceChunk,
 ): EvidenceAssetCandidate | null {
   if (normalizeChunkType(chunk.chunkType) !== "page") return null
 
@@ -296,7 +495,7 @@ function isImageAssetUrl(assetUrl: string): boolean {
 }
 
 function getAssetSourcePath(
-  chunk: Omit<EvidenceChunk, "assetRef">,
+  chunk: EvidenceChunk,
   assetUrl: string,
 ): string | null {
   const candidates = [
@@ -485,6 +684,8 @@ function snapshot(ledger: MutableLedger): EvidenceLedgerSnapshot {
     stopReasons: [...ledger.stopReasons],
     failureReasons: [...ledger.failureReasons],
     decisionTraces: [...ledger.decisionTraces],
+    retainedPicks: [...ledger.retainedPicks].sort((left, right) => left - right),
+    pendingRetention: ledger.pendingRetention,
   }
 }
 
diff --git a/src/agent-harness/referenced-chunks.ts b/src/agent-harness/referenced-chunks.ts
new file mode 100644
index 0000000..ccde61b
--- /dev/null
+++ b/src/agent-harness/referenced-chunks.ts
@@ -0,0 +1,7 @@
+import type { RetrievalQueryResponse } from "@ontos-ai/knowhere-sdk"
+
+type ReferencedChunk = RetrievalQueryResponse["referencedChunks"][number]
+
+export function hasReferencedChunkEvidence(chunk: ReferencedChunk): boolean {
+  return typeof chunk.chunkType === "string" && chunk.chunkType.trim().length > 0
+}
diff --git a/src/agent-harness/runtime.test.ts b/src/agent-harness/runtime.test.ts
index d36ca1b..bc06251 100644
--- a/src/agent-harness/runtime.test.ts
+++ b/src/agent-harness/runtime.test.ts
@@ -1,11 +1,13 @@
 import { describe, expect, it, vi } from "vitest"
 import type { RetrievalQueryResponse } from "@ontos-ai/knowhere-sdk"
+import { MockLanguageModelV3 } from "ai/test"
 
 import {
   buildHarnessMessages,
   buildHarnessSystemPrompt,
   createHarnessTools,
   prepareHarnessStep,
+  runAgentHarness,
   sanitizeHarnessModelMessagesForStep,
 } from "./runtime"
 import { createEvidenceLedger } from "./ledger"
@@ -13,25 +15,161 @@ import type {
   AgentTurnInput,
   ContextPolicy,
   HarnessToolCallTrace,
-  ImageInspectionRequest,
   IntentFrame,
   KnowhereToolRuntime,
+  MemorySearchItem,
   MemoryToolRuntime,
   OutputManifest,
+  ResolveConnectedAssets,
 } from "./types"
 
 describe("agent harness runtime", () => {
-  it("tells the agent to search fluid memory first and not treat every question as document retrieval", () => {
+  it("runs retention, resolves connected assets, assembles once, and finalizes", async () => {
+    const modelResults = [
+      toolCallResult([
+        {
+          toolCallId: "intent",
+          toolName: "declareIntent",
+          input: {
+            task: "compare",
+            dependsOnPreviousTurn: false,
+            retrievalNeeded: "yes",
+            targetModalities: ["text", "image", "table"],
+            constraints: {},
+            groundingPolicy: "must_use_sources",
+          },
+        },
+        {
+          toolCallId: "context",
+          toolName: "setContextPolicy",
+          input: {
+            carryHistory: "none",
+            reason: "Self-contained request.",
+            activePriorTurnIds: [],
+          },
+        },
+      ]),
+      toolCallResult([
+        {
+          toolCallId: "search",
+          toolName: "knowhere_search",
+          input: { query: "comparison", targetContent: "all" },
+        },
+      ]),
+      toolCallResult([
+        {
+          toolCallId: "retain",
+          toolName: "retainEvidence",
+          input: { picks: [1] },
+        },
+      ]),
+      toolCallResult([
+        {
+          toolCallId: "prepare",
+          toolName: "prepareAnswer",
+          input: {},
+        },
+      ]),
+      toolCallResult([
+        {
+          toolCallId: "finalize",
+          toolName: "finalize",
+          input: {
+            text: "Comparison [[cite:1]].",
+            citations: [{ pick: 1 }],
+            memoryCitations: [],
+            artifacts: [
+              {
+                type: "table",
+                ref: "asset:r1:result:1:table_chunk",
+                display: true,
+                reason: "Comparison table",
+              },
+              {
+                type: "image",
+                ref: "asset:r1:result:1:image_chunk",
+                display: true,
+                reason: "Comparison image",
+              },
+            ],
+            unresolved: [],
+          },
+        },
+      ]),
+    ]
+    let modelResultIndex = 0
+    const model = new MockLanguageModelV3({
+      supportedUrls: { "image/*": [/^https:\/\//] },
+      doGenerate: async () => {
+        const result = modelResults[modelResultIndex]
+        modelResultIndex += 1
+        if (!result) throw new Error("No mock model result remains.")
+        return result
+      },
+    })
+    const resolveConnectedAssets = vi.fn<ResolveConnectedAssets>(
+      async (lookups) =>
+        lookups.map((lookup) => ({
+          ...lookup,
+          assetUrl: `https://assets.example/${lookup.chunkId}`,
+        })),
+    )
+    const readTableHtml = vi
+      .fn()
+      .mockResolvedValue("<table><tr><td>comparison</td></tr></table>")
+
+    const result = await runAgentHarness({
+      model,
+      turn: makeTurnInput(),
+      knowhereTools: makeKnowhereTools(
+        vi.fn().mockResolvedValue(makeConnectedRetrievalResponse()),
+      ),
+      memoryTools: makeMemoryTools(),
+      resolveConnectedAssets,
+      readTableHtml,
+    })
+
+    expect(model.doGenerateCalls).toHaveLength(5)
+    expect(resolveConnectedAssets).toHaveBeenCalledWith([
+      { documentId: "doc_1", chunkId: "table_chunk", type: "table" },
+      { documentId: "doc_1", chunkId: "image_chunk", type: "image" },
+    ])
+    expect(readTableHtml).toHaveBeenCalledWith(
+      "https://assets.example/table_chunk",
+    )
+    expect(JSON.stringify(model.doGenerateCalls[4]?.prompt)).toContain(
+      "<table><tr><td>comparison</td></tr></table>",
+    )
+    expect(result.manifest.citations).toEqual([{ ref: "r1:result:1" }])
+    expect(result.trace.ledger.assets).toHaveLength(2)
+  })
+
+  it("tells the agent to search memory and documents in parallel when both apply", () => {
     const prompt = buildHarnessSystemPrompt(makeTurnInput())
 
-    expect(prompt).toContain("Call memory_search first")
+    expect(prompt).toContain("call them together in the same step")
     expect(prompt).toContain(
-      "Call knowhere_search only when memory is insufficient and groundingPolicy requires citing source documents",
+      "Call knowhere_search when groundingPolicy requires citing source documents",
     )
     expect(prompt).toContain(
       "call knowhere_search again with a refined query",
     )
     expect(prompt).toContain("Refine knowhere_search at most twice")
+    expect(prompt).toContain(
+      "After the second refined search, call prepareAnswer regardless of its result",
+    )
+    expect(prompt).toContain(
+      "After each search that returns new evidence, call retainEvidence",
+    )
+    expect(prompt).toContain(
+      "When calling knowhere_search after a previous search in this turn, set gapReason",
+    )
+    expect(prompt).toContain(
+      "asset paths in retrieved chunks represent connected assets",
+    )
+    expect(prompt).toContain(
+      "Do not refine the search solely because those assets have not been expanded yet",
+    )
     expect(prompt).not.toContain("knowhere_list_documents")
     expect(prompt).not.toContain("knowhere_get_document_outline")
     expect(prompt).not.toContain("knowhere_read_chunks")
@@ -70,15 +208,16 @@ describe("agent harness runtime", () => {
     expect(prompt).toContain("Do not collapse same-page citations")
   })
 
-  it("requires inspectImage on cited page/image assets before finalize", () => {
+  it("tells the agent to read retained images in the assembled answer message", () => {
     const prompt = buildHarnessSystemPrompt(makeTurnInput())
 
     expect(prompt).toContain(
-      "call inspectImage on the page/image assets you will cite before finalize",
+      "memory_search and knowhere_search are parallel retrieval sources",
     )
     expect(prompt).toContain(
-      "Do not finalize cited page/image assets from chunk text alone",
+      "Images in retained evidence are embedded directly",
     )
+    expect(prompt).not.toContain("inspectImage")
   })
 
   it("passes only outer retrieval parameters to KNOWHERE without planning-tool gating", async () => {
@@ -187,7 +326,11 @@ describe("agent harness runtime", () => {
     })
 
     const firstResult = await executeTool(tools.knowhere_search, { query: "first" })
-    const secondResult = await executeTool(tools.knowhere_search, { query: "second" })
+    await retainLatestSearch(tools, ledger)
+    const secondResult = await executeTool(tools.knowhere_search, {
+      query: "second",
+      gapReason: "The first search lacked the second-source wording this query targets.",
+    })
 
     expect(firstResult).toContain('pick="1"')
     expect(firstResult).toContain('ref="r1:result:1"')
@@ -203,734 +346,260 @@ describe("agent harness runtime", () => {
     ])
   })
 
-  it("rejects image inspection before retrieval has returned image assets", async () => {
-    const inspectImages = vi.fn()
+  it("writes citation refs from ledger picks and rejects picks outside the ledger", async () => {
+    const ledger = createEvidenceLedger()
+    ledger.addRetrievalResponse(makeRetrievalResponse())
+    const state: {
+      finalized?: boolean
+      finalizedManifest?: OutputManifest
+    } = {}
     const tools = createHarnessTools({
-      state: {},
-      ledger: createEvidenceLedger(),
+      state,
+      ledger,
       memoryTools: makeMemoryTools(),
       knowhereTools: makeKnowhereTools(),
-      inspectImages,
       recentTurns: [],
     })
+    await retainLatestSearch(tools, ledger)
 
-    const result = await executeTool(tools.inspectImage, {
-      refs: ["asset:r1:result:1"],
-      question: "What text is visible?",
+    const rejected = await executeTool(tools.finalize, {
+      text: "Target is <130/80 mmHg [[cite:1]].",
+      citations: [{ pick: 99 }],
+      memoryCitations: [],
+      artifacts: [],
+      unresolved: [],
     })
 
-    expect(result).toEqual({
+    expect(rejected).toMatchObject({
       ok: false,
-      message:
-        "Knowhere evidence tools must return image assets before inspectImage.",
-      inspected: [],
-      skipped: [
-        {
-          ref: "asset:r1:result:1",
-          reason: "No Knowhere evidence is available yet.",
-        },
-      ],
+      unknownPicks: [99],
+    })
+    expect(String((rejected as { message: string }).message)).toContain(
+      "Available picks: 1-1",
+    )
+    expect(state.finalized).not.toBe(true)
+
+    const accepted = await executeTool(tools.finalize, {
+      text: "Target is <130/80 mmHg [[cite:1]].",
+      citations: [{ pick: 1 }],
+      memoryCitations: [],
+      artifacts: [],
+      unresolved: [],
+    })
+    expect(accepted).toMatchObject({
+      ok: true,
+      citations: [{ ref: "r1:result:1" }],
     })
-    expect(inspectImages).not.toHaveBeenCalled()
+    expect(state.finalized).toBe(true)
+    expect(state.finalizedManifest?.citations).toEqual([{ ref: "r1:result:1" }])
   })
 
-  it("rejects image inspection refs that are unknown or not image assets", async () => {
+  it("maps finalize picks across successive searches", async () => {
     const ledger = createEvidenceLedger()
-    ledger.addRetrievalResponse(makeTableRetrievalResponse())
-    const inspectImages = vi.fn()
+    ledger.addRetrievalResponse(makeRetrievalResponse())
+    const state: {
+      finalizedManifest?: OutputManifest
+    } = {}
     const tools = createHarnessTools({
-      state: {},
+      state,
       ledger,
       memoryTools: makeMemoryTools(),
       knowhereTools: makeKnowhereTools(),
-      inspectImages,
       recentTurns: [],
     })
-
-    const result = await executeTool(tools.inspectImage, {
-      refs: ["asset:r1:result:1", "missing"],
-      question: "What is in these images?",
-    })
-
-    expect(result).toEqual({
-      ok: false,
-      message: "No inspectable image asset refs were provided.",
-      inspected: [],
-      skipped: [
-        {
-          ref: "asset:r1:result:1",
-          reason: "Ref is not an image asset.",
-        },
+    await retainLatestSearch(tools, ledger)
+    ledger.addRetrievalResponse({
+      ...makeRetrievalResponse(),
+      query: "second query",
+      results: [
         {
-          ref: "missing",
-          reason: "Ref was not returned by Knowhere as an asset.",
+          content: "Second retrieval evidence.",
+          chunkType: "text",
+          score: 0.8,
+          source: {
+            documentId: "doc_2",
+            sourceFileName: "second.pdf",
+            sectionPath: "Second",
+          },
         },
       ],
     })
-    expect(inspectImages).not.toHaveBeenCalled()
+    await retainLatestSearch(tools, ledger)
+
+    const accepted = await executeTool(tools.finalize, {
+      text: "Second source [[cite:1]].",
+      citations: [{ pick: 2 }],
+      memoryCitations: [],
+      artifacts: [],
+      unresolved: [],
+    })
+
+    expect(accepted).toMatchObject({
+      ok: true,
+      citations: [{ ref: "r2:result:1" }],
+    })
+    expect(state.finalizedManifest?.citations).toEqual([{ ref: "r2:result:1" }])
   })
 
-  it("lets retrieval bound the number of images inspected in one call", async () => {
-    const ledger = createEvidenceLedger()
-    ledger.addRetrievalResponse(makeImageRetrievalResponse(7))
-    const inspectImages = vi.fn(async (request: {
-      readonly assets: readonly { readonly ref: string; readonly label: string }[]
-    }) => ({
-      analysis: "Compared all retrieved images.",
-      inspected: request.assets.map(({ ref, label }) => ({ ref, label })),
-      skipped: [],
-    }))
+  it("accepts free-form text with no citations, displayed artifacts, or unresolved gaps", async () => {
+    const state: {
+      finalizedManifest?: OutputManifest
+      finalized?: boolean
+    } = {}
     const tools = createHarnessTools({
-      state: {},
-      ledger,
+      state,
+      ledger: createEvidenceLedger(),
       memoryTools: makeMemoryTools(),
       knowhereTools: makeKnowhereTools(),
-      inspectImages,
       recentTurns: [],
     })
 
-    const result = await executeTool(tools.inspectImage, {
-      refs: Array.from({ length: 7 }, (_, index) => `asset:r1:result:${index + 1}`),
-      question: "Compare these images.",
+    const result = await executeTool(tools.finalize, {
+      text: "Hi there! How can I help?",
+      citations: [],
+      memoryCitations: [],
+      artifacts: [],
+      unresolved: [],
     })
 
     expect(result).toMatchObject({ ok: true })
-    expect(inspectImages.mock.calls[0]?.[0].assets).toHaveLength(7)
+    expect(state.finalizedManifest?.text).toBe("Hi there! How can I help?")
+    expect(state.finalized).toBe(true)
   })
 
-  it("calls the visual inspection capability with retrieved image ledger assets", async () => {
-    const ledger = createEvidenceLedger()
-    ledger.addRetrievalResponse(makeRetrievalResponse())
-    const inspectImages = vi.fn().mockResolvedValue({
-      analysis: "The image shows a Q4 revenue chart with a rising line.",
-      inspected: [
-        {
-          ref: "asset:r1:result:1",
-          label: "report.pdf / images/chart.png / image",
-        },
-      ],
-      skipped: [],
-    })
+  it("accepts explicitly unresolved output without planning-tool gating", async () => {
+    const state: {
+      finalizedManifest?: OutputManifest
+      finalized?: boolean
+      memoryItems?: MemorySearchItem[]
+    } = {}
     const tools = createHarnessTools({
-      state: {},
-      ledger,
+      state,
+      ledger: createEvidenceLedger(),
       memoryTools: makeMemoryTools(),
       knowhereTools: makeKnowhereTools(),
-      inspectImages,
       recentTurns: [],
     })
 
-    const result = await executeTool(tools.inspectImage, {
-      refs: ["asset:r1:result:1"],
-      question: "What does the chart show?",
-    })
+    const manifest = {
+      text: "Answer.",
+      citations: [],
+      memoryCitations: [],
+      artifacts: [],
+      unresolved: ["No source evidence is available."],
+    }
 
-    expect(inspectImages).toHaveBeenCalledWith({
-      question: "What does the chart show?",
-      assets: [
-        {
-          ref: "asset:r1:result:1",
-          label: "report.pdf / images/chart.png / image",
-          assetUrl: "https://assets.example/chart.png",
-          sourcePath: "images/chart.png",
-          source: {
-            documentId: "doc_1",
-            sourceFileName: "report.pdf",
-            sectionPath: "images/chart.png",
-          },
-        },
-      ],
-    })
-    expect(result).toEqual({
+    expect(await executeTool(tools.finalize, manifest)).toMatchObject({
       ok: true,
-      analysis: "The image shows a Q4 revenue chart with a rising line.",
-      inspected: [
-        {
-          ref: "asset:r1:result:1",
-          label: "report.pdf / images/chart.png / image",
-        },
-      ],
-      skipped: [],
+      text: "Answer.",
     })
+    expect(state.finalizedManifest).toEqual(manifest)
+    expect(state.finalized).toBe(true)
   })
 
-  it("calls the visual inspection capability with retrieved page citation assets", async () => {
-    const ledger = createEvidenceLedger()
-    ledger.addRetrievalResponse(makePageCitationRetrievalResponse())
-    const inspectImages = vi.fn().mockResolvedValue({
-      analysis: "The clause says the contractor pays 5000 yuan per occurrence.",
-      inspected: [
+  it("returns memory refs from memory_search and stores memoryCitations on finalize", async () => {
+    const search = vi.fn<MemoryToolRuntime["search"]>().mockResolvedValue({
+      query: "毛利率",
+      items: [
         {
-          ref: "asset:r1:referenced:1",
-          label:
-            "Root / （6）现场工期进度管理方面的违约责任 / page_citation_assets/page-8.png / page",
+          ref: "mem:1",
+          itemId: "item_1",
+          kind: "stance",
+          abstractL0: "关注毛利率下滑",
+          overviewL1: "用户把毛利率当作核心观察指标。",
         },
       ],
-      skipped: [],
     })
+    const state: {
+      finalizedManifest?: OutputManifest
+      finalized?: boolean
+      memoryItems?: MemorySearchItem[]
+    } = {}
     const tools = createHarnessTools({
-      state: {},
-      ledger,
-      memoryTools: makeMemoryTools(),
+      state,
+      ledger: createEvidenceLedger(),
+      memoryTools: makeMemoryTools(search),
       knowhereTools: makeKnowhereTools(),
-      inspectImages,
       recentTurns: [],
     })
 
-    const result = await executeTool(tools.inspectImage, {
-      refs: ["asset:r1:referenced:1"],
-      question: "What liquidated damages amount is visible in this clause?",
+    const searchText = await executeTool(tools.memory_search, {
+      query: "毛利率",
+    })
+    const repeatedSearchText = await executeTool(tools.memory_search, {
+      query: "盈利能力",
+    })
+    expect(searchText).toContain('<memory operation="search" status="ok">')
+    expect(searchText).toContain('ref="mem:1"')
+    expect(searchText).toContain('itemId="item_1"')
+    expect(repeatedSearchText).toContain('status="error"')
+    expect(search).toHaveBeenCalledTimes(1)
+    expect(search).toHaveBeenNthCalledWith(1, {
+      query: "毛利率",
+      kinds: undefined,
     })
+    expect(state.memoryItems).toEqual([
+      {
+        ref: "mem:1",
+        itemId: "item_1",
+        kind: "stance",
+        abstractL0: "关注毛利率下滑",
+        overviewL1: "用户把毛利率当作核心观察指标。",
+      },
+    ])
 
-    expect(inspectImages).toHaveBeenCalledWith({
-      question: "What liquidated damages amount is visible in this clause?",
-      assets: [
-        {
-          ref: "asset:r1:referenced:1",
-          label:
-            "Root / （6）现场工期进度管理方面的违约责任 / page_citation_assets/page-8.png / page",
-          assetUrl: "https://assets.example/page-8.png",
-          sourcePath: "page_citation_assets/page-8.png",
-          revisionKey: "job_contract",
-          source: {
-            documentId: "doc_contract",
-            sourceFileName: null,
-            sectionPath: "Root / （6）现场工期进度管理方面的违约责任",
-          },
-        },
+    const manifest = {
+      text: "按已有记忆，毛利率是核心观察指标。",
+      citations: [],
+      memoryCitations: [
+        { ref: "mem:1", itemId: "item_1", kind: "stance" as const },
       ],
+      artifacts: [],
+      unresolved: [],
+    }
+    const invalidManifest = {
+      ...manifest,
+      memoryCitations: [
+        { ref: "mem:1", itemId: "invented_item", kind: "stance" as const },
+      ],
+    }
+    expect(await executeTool(tools.finalize, invalidManifest)).toMatchObject({
+      ok: false,
+      invalidMemoryCitations: invalidManifest.memoryCitations,
     })
-    expect(result).toMatchObject({
+    expect(state.finalizedManifest).toBeUndefined()
+
+    expect(await executeTool(tools.finalize, manifest)).toMatchObject({
       ok: true,
-      analysis: "The clause says the contractor pays 5000 yuan per occurrence.",
+      memoryCitations: manifest.memoryCitations,
     })
+    expect(state.finalizedManifest).toEqual(manifest)
   })
 
-  it("inspects duplicate retrieved pages only once across namespaces", async () => {
-    const ledger = createEvidenceLedger()
-    const pageMetadata = {
-      pageNums: [4],
-      pageAssets: [
+  it("exposes full prior-turn content through policy-approved readPriorTurn", async () => {
+    const state: {
+      contextPolicy?: ContextPolicy
+      priorTurnReads?: string[]
+    } = {
+      contextPolicy: {
+        carryHistory: "repair_previous",
+        reason: "The current request corrects the previous answer.",
+        activePriorTurnIds: ["turn_1"],
+      },
+      priorTurnReads: [],
+    }
+    const tools = createHarnessTools({
+      state,
+      ledger: createEvidenceLedger(),
+      memoryTools: makeMemoryTools(),
+      knowhereTools: makeKnowhereTools(),
+      recentTurns: [
         {
-          pageNum: 4,
-          artifactRef: "page_citation_assets/page-4.png",
-          assetUrl: "https://assets.example/page-4.png",
-          contentType: "image/png",
-        },
-      ],
-    }
-    ledger.addRetrievalResponse({
-      namespace: "default,notebook",
-      query: "revenue",
-      routerUsed: "mapnav",
-      answerText: null,
-      evidenceText: "Revenue evidence",
-      stopReason: "completed",
-      failureReason: null,
-      results: [
-        {
-          chunkId: "chunk_page_4",
-          content: "Revenue was $24.9B.",
-          chunkType: "page",
-          score: 0.9,
-          metadata: pageMetadata,
-          source: {
-            documentId: "doc_catalog",
-            sourceFileName: "original.pdf",
-            sectionPath: "FINANCIAL SUMMARY",
-          },
-        },
-        {
-          chunkId: "chunk_page_4",
-          content: "Revenue was $24.9B.",
-          chunkType: "page",
-          score: 0.9,
-          metadata: pageMetadata,
-          source: {
-            documentId: "doc_workspace",
-            sourceFileName: "TSLA-Q4-2025-Update.pdf",
-            sectionPath: "FINANCIAL SUMMARY",
-          },
-        },
-      ],
-      referencedChunks: [],
-    })
-    const inspectImages = vi.fn().mockResolvedValue({
-      analysis: "Revenue is visible in the financial summary.",
-      inspected: [
-        {
-          ref: "asset:r1:result:1",
-          label: "original.pdf / page_citation_assets/page-4.png / page",
-        },
-      ],
-      skipped: [],
-      highlights: [
-        {
-          ref: "asset:r1:result:1",
-          regions: [{ x: 0.1, y: 0.2, w: 0.8, h: 0.1 }],
-        },
-      ],
-    })
-    const state: {
-      inspectedImageRefs?: string[]
-    } = {}
-    const tools = createHarnessTools({
-      state,
-      ledger,
-      memoryTools: makeMemoryTools(),
-      knowhereTools: makeKnowhereTools(),
-      inspectImages,
-      recentTurns: [],
-    })
-
-    const inspection = await executeTool(tools.inspectImage, {
-      refs: ["asset:r1:result:1", "asset:r1:result:2"],
-      question: "Locate the cited revenue.",
-    })
-
-    expect(inspection).toMatchObject({ ok: true })
-    expect(inspectImages.mock.calls[0]?.[0].assets).toHaveLength(1)
-    expect(
-      await executeTool(tools.finalize, {
-        text: "Revenue was $24.9B [[cite:1]] [[cite:2]].",
-        citations: [{ pick: 1 }, { pick: 2 }],
-        memoryCitations: [],
-        artifacts: [],
-        unresolved: [],
-      }),
-    ).toMatchObject({ ok: true })
-  })
-
-  it("does not deduplicate unrelated documents with generic page paths", async () => {
-    const ledger = createEvidenceLedger()
-    ledger.addRetrievalResponse({
-      namespace: "notebook",
-      query: "revenue",
-      routerUsed: "mapnav",
-      answerText: null,
-      evidenceText: "Revenue evidence",
-      stopReason: "completed",
-      failureReason: null,
-      results: [
-        {
-          chunkId: "chunk_page_4",
-          content: "Revenue evidence from document A.",
-          chunkType: "page",
-          score: 0.9,
-          metadata: {
-            pageNums: [4],
-            pageAssets: [
-              {
-                pageNum: 4,
-                artifactRef: "page_citation_assets/page-4.png",
-                assetUrl: "https://assets.example/doc-a/page-4.png",
-                contentType: "image/png",
-              },
-            ],
-          },
-          source: {
-            documentId: "doc_a",
-            sourceFileName: "a.pdf",
-            sectionPath: "Page 4",
-          },
-        },
-        {
-          chunkId: "chunk_page_4",
-          content: "Revenue evidence from document B.",
-          chunkType: "page",
-          score: 0.8,
-          metadata: {
-            pageNums: [4],
-            pageAssets: [
-              {
-                pageNum: 4,
-                artifactRef: "page_citation_assets/page-4.png",
-                assetUrl: "https://assets.example/doc-b/page-4.png",
-                contentType: "image/png",
-              },
-            ],
-          },
-          source: {
-            documentId: "doc_b",
-            sourceFileName: "b.pdf",
-            sectionPath: "Page 4",
-          },
-        },
-      ],
-      referencedChunks: [],
-    })
-    const inspectImages = vi.fn(async (request: ImageInspectionRequest) => ({
-      analysis: "Inspected both pages.",
-      inspected: request.assets.map(({ ref, label }) => ({ ref, label })),
-      skipped: [],
-    }))
-    const tools = createHarnessTools({
-      state: {},
-      ledger,
-      memoryTools: makeMemoryTools(),
-      knowhereTools: makeKnowhereTools(),
-      inspectImages,
-      recentTurns: [],
-    })
-
-    expect(
-      await executeTool(tools.inspectImage, {
-        refs: ["asset:r1:result:1", "asset:r1:result:2"],
-        question: "Compare the cited revenue.",
-      }),
-    ).toMatchObject({ ok: true })
-    expect(inspectImages.mock.calls[0]?.[0].assets).toHaveLength(2)
-  })
-
-  it("does not treat skipped image assets as successfully inspected", async () => {
-    const ledger = createEvidenceLedger()
-    ledger.addRetrievalResponse(makePageCitationRetrievalResponse())
-    const state: {
-      inspectedImageRefs?: string[]
-      finalized?: boolean
-    } = {}
-    const tools = createHarnessTools({
-      state,
-      ledger,
-      memoryTools: makeMemoryTools(),
-      knowhereTools: makeKnowhereTools(),
-      inspectImages: vi.fn().mockResolvedValue({
-        analysis: "",
-        inspected: [],
-        skipped: [
-          {
-            ref: "asset:r1:referenced:1",
-            reason: "The image asset was unavailable in Notebook storage.",
-          },
-        ],
-      }),
-      recentTurns: [],
-    })
-
-    const inspection = await executeTool(tools.inspectImage, {
-      refs: ["asset:r1:referenced:1"],
-      question: "Locate the cited amount.",
-    })
-
-    expect(inspection).toMatchObject({
-      ok: false,
-      inspected: [],
-    })
-    expect(state.inspectedImageRefs).toEqual([])
-
-    const finalize = await executeTool(tools.finalize, {
-      text: "The amount is 5000 yuan [[cite:1]].",
-      citations: [{ pick: 1 }],
-      memoryCitations: [],
-      artifacts: [],
-      unresolved: [],
-    })
-    expect(finalize).toMatchObject({
-      ok: false,
-      inspectRefs: ["asset:r1:referenced:1"],
-    })
-    expect(state.finalized).not.toBe(true)
-  })
-
-  it("writes citation refs from ledger picks and rejects picks outside the ledger", async () => {
-    const ledger = createEvidenceLedger()
-    ledger.addRetrievalResponse(makeRetrievalResponse())
-    const state: {
-      finalized?: boolean
-      finalizedManifest?: OutputManifest
-    } = {}
-    const tools = createHarnessTools({
-      state,
-      ledger,
-      memoryTools: makeMemoryTools(),
-      knowhereTools: makeKnowhereTools(),
-      recentTurns: [],
-    })
-
-    const rejected = await executeTool(tools.finalize, {
-      text: "Target is <130/80 mmHg [[cite:1]].",
-      citations: [{ pick: 99 }],
-      memoryCitations: [],
-      artifacts: [],
-      unresolved: [],
-    })
-
-    expect(rejected).toMatchObject({
-      ok: false,
-      unknownPicks: [99],
-    })
-    expect(String((rejected as { message: string }).message)).toContain(
-      "Available picks: 1-1",
-    )
-    expect(state.finalized).not.toBe(true)
-
-    const accepted = await executeTool(tools.finalize, {
-      text: "Target is <130/80 mmHg [[cite:1]].",
-      citations: [{ pick: 1 }],
-      memoryCitations: [],
-      artifacts: [],
-      unresolved: [],
-    })
-    expect(accepted).toMatchObject({
-      ok: true,
-      citations: [{ ref: "r1:result:1" }],
-    })
-    expect(state.finalized).toBe(true)
-    expect(state.finalizedManifest?.citations).toEqual([{ ref: "r1:result:1" }])
-  })
-
-  it("maps finalize picks across successive searches", async () => {
-    const ledger = createEvidenceLedger()
-    ledger.addRetrievalResponse(makeRetrievalResponse())
-    ledger.addRetrievalResponse({
-      ...makeRetrievalResponse(),
-      query: "second query",
-      results: [
-        {
-          content: "Second retrieval evidence.",
-          chunkType: "text",
-          score: 0.8,
-          source: {
-            documentId: "doc_2",
-            sourceFileName: "second.pdf",
-            sectionPath: "Second",
-          },
-        },
-      ],
-    })
-    const state: {
-      finalizedManifest?: OutputManifest
-    } = {}
-    const tools = createHarnessTools({
-      state,
-      ledger,
-      memoryTools: makeMemoryTools(),
-      knowhereTools: makeKnowhereTools(),
-      recentTurns: [],
-    })
-
-    const accepted = await executeTool(tools.finalize, {
-      text: "Second source [[cite:1]].",
-      citations: [{ pick: 2 }],
-      memoryCitations: [],
-      artifacts: [],
-      unresolved: [],
-    })
-
-    expect(accepted).toMatchObject({
-      ok: true,
-      citations: [{ ref: "r2:result:1" }],
-    })
-    expect(state.finalizedManifest?.citations).toEqual([{ ref: "r2:result:1" }])
-  })
-
-  it("accepts finalize output without planning-tool gating", async () => {
-    const state: {
-      finalizedManifest?: OutputManifest
-      finalized?: boolean
-    } = {}
-    const tools = createHarnessTools({
-      state,
-      ledger: createEvidenceLedger(),
-      memoryTools: makeMemoryTools(),
-      knowhereTools: makeKnowhereTools(),
-      recentTurns: [],
-    })
-
-    const manifest = {
-      text: "Answer.",
-      citations: [],
-      memoryCitations: [],
-      artifacts: [],
-      unresolved: [],
-    }
-
-    expect(await executeTool(tools.finalize, manifest)).toMatchObject({
-      ok: true,
-      text: "Answer.",
-    })
-    expect(state.finalizedManifest).toEqual(manifest)
-    expect(state.finalized).toBe(true)
-  })
-
-  it("returns memory refs from memory_search and stores memoryCitations on finalize", async () => {
-    const search = vi.fn<MemoryToolRuntime["search"]>().mockResolvedValue({
-      query: "毛利率",
-      items: [
-        {
-          ref: "mem:1",
-          itemId: "item_1",
-          kind: "stance",
-          abstractL0: "关注毛利率下滑",
-          overviewL1: "用户把毛利率当作核心观察指标。",
-        },
-      ],
-    })
-    const state: {
-      finalizedManifest?: OutputManifest
-      finalized?: boolean
-    } = {}
-    const tools = createHarnessTools({
-      state,
-      ledger: createEvidenceLedger(),
-      memoryTools: makeMemoryTools(search),
-      knowhereTools: makeKnowhereTools(),
-      recentTurns: [],
-    })
-
-    const searchText = await executeTool(tools.memory_search, {
-      query: "毛利率",
-    })
-    expect(searchText).toContain('<memory operation="search" status="ok">')
-    expect(searchText).toContain('ref="mem:1"')
-    expect(searchText).toContain('itemId="item_1"')
-    expect(search).toHaveBeenCalledWith({
-      query: "毛利率",
-      kinds: undefined,
-    })
-
-    const manifest = {
-      text: "按已有记忆，毛利率是核心观察指标。",
-      citations: [],
-      memoryCitations: [
-        { ref: "mem:1", itemId: "item_1", kind: "stance" as const },
-      ],
-      artifacts: [],
-      unresolved: [],
-    }
-    expect(await executeTool(tools.finalize, manifest)).toMatchObject({
-      ok: true,
-      memoryCitations: manifest.memoryCitations,
-    })
-    expect(state.finalizedManifest).toEqual(manifest)
-  })
-
-  it("rejects finalize of cited page images until inspectImage has run", async () => {
-    const ledger = createEvidenceLedger()
-    ledger.addRetrievalResponse(makePageCitationRetrievalResponse())
-    const state: {
-      finalizedManifest?: OutputManifest
-      finalized?: boolean
-      inspectedImageRefs?: string[]
-    } = {}
-    const tools = createHarnessTools({
-      state,
-      ledger,
-      memoryTools: makeMemoryTools(),
-      knowhereTools: makeKnowhereTools(),
-      inspectImages: vi.fn().mockResolvedValue({
-        analysis: "The clause shows 5000 yuan per occurrence.",
-        inspected: [{ ref: "asset:r1:referenced:1", label: "page 8" }],
-        skipped: [],
-        highlights: [
-          {
-            ref: "asset:r1:referenced:1",
-            regions: [{ x: 0.1, y: 0.2, w: 0.4, h: 0.15 }],
-          },
-        ],
-      }),
-      recentTurns: [],
-    })
-    const manifest = {
-      text: "The contractor pays 5000 yuan per occurrence [[cite:1]].",
-      citations: [{ pick: 1 }],
-      memoryCitations: [],
-      artifacts: [],
-      unresolved: [],
-    }
-
-    const blocked = await executeTool(tools.finalize, manifest)
-
-    expect(blocked).toMatchObject({
-      ok: false,
-      inspectRefs: ["asset:r1:referenced:1"],
-    })
-    expect(blocked).toEqual(
-      expect.objectContaining({
-        message: expect.stringContaining("inspectImage"),
-      }),
-    )
-    expect(state.finalized).not.toBe(true)
-
-    await executeTool(tools.inspectImage, {
-      refs: ["asset:r1:referenced:1"],
-      question: "Locate the cited liquidated-damages amount on this page.",
-    })
-
-    expect(await executeTool(tools.finalize, manifest)).toMatchObject({
-      ok: true,
-      text: manifest.text,
-    })
-    expect(state.finalized).toBe(true)
-  })
-
-  it("requires inspection when the cited result shares a page asset with a referenced chunk", async () => {
-    const response = makePageCitationRetrievalResponse()
-    const ledger = createEvidenceLedger()
-    ledger.addRetrievalResponse({
-      ...response,
-      results: [
-        {
-          chunkId: "chunk_page_8",
-          content: "The contractor pays 5000 yuan per occurrence.",
-          chunkType: "page",
-          score: 0.9,
-          metadata: { pageNums: [8] },
-          source: {
-            documentId: "doc_contract",
-            sourceFileName: "contract.pdf",
-            sectionPath: "Root / Liquidated damages",
-          },
-        },
-      ],
-    })
-    const tools = createHarnessTools({
-      state: {},
-      ledger,
-      memoryTools: makeMemoryTools(),
-      knowhereTools: makeKnowhereTools(),
-      inspectImages: vi.fn(),
-      recentTurns: [],
-    })
-
-    const result = await executeTool(tools.finalize, {
-      text: "The contractor pays 5000 yuan [[cite:1]].",
-      citations: [{ pick: 1 }],
-      memoryCitations: [],
-      artifacts: [],
-      unresolved: [],
-    })
-
-    expect(result).toMatchObject({
-      ok: false,
-      inspectRefs: ["asset:r1:referenced:1"],
-    })
-  })
-
-  it("exposes full prior-turn content through policy-approved readPriorTurn", async () => {
-    const state: {
-      contextPolicy?: ContextPolicy
-      priorTurnReads?: string[]
-    } = {
-      contextPolicy: {
-        carryHistory: "repair_previous",
-        reason: "The current request corrects the previous answer.",
-        activePriorTurnIds: ["turn_1"],
-      },
-      priorTurnReads: [],
-    }
-    const tools = createHarnessTools({
-      state,
-      ledger: createEvidenceLedger(),
-      memoryTools: makeMemoryTools(),
-      knowhereTools: makeKnowhereTools(),
-      recentTurns: [
-        {
-          id: "turn_1",
-          role: "assistant",
-          contentPreview: "Truncated preview...",
-          content: "The full earlier answer about the tax filing deadline.",
-          citationLabels: ["tax.pdf / deadline"],
+          id: "turn_1",
+          role: "assistant",
+          contentPreview: "Truncated preview...",
+          content: "The full earlier answer about the tax filing deadline.",
+          citationLabels: ["tax.pdf / deadline"],
         },
       ],
     })
@@ -1094,17 +763,37 @@ describe("agent harness runtime", () => {
     expect(result.activeTools).toEqual([
       "declareIntent",
       "setContextPolicy",
-      "inspectImage",
       "readPriorTurn",
     ])
     expect(result.activeTools).not.toContain("finalize")
-    expect(result.activeTools).not.toContain("memory_search")
+    expect(result.activeTools).not.toContain("memory_search")
+    expect(result.activeTools).not.toContain("knowhere_search")
+  })
+
+  it("opens only memory_search after intent says retrieval may be needed", () => {
+    const result = prepareHarnessStep({
+      stepNumber: 3,
+      intent: {
+        task: "answer",
+        dependsOnPreviousTurn: false,
+        retrievalNeeded: "maybe",
+        targetModalities: ["text"],
+        constraints: {},
+        groundingPolicy: "can_use_context",
+      },
+      messages: [],
+    })
+
+    expect(result.activeTools).toContain("memory_search")
+    expect(result.activeTools).toContain("prepareAnswer")
+    expect(result.activeTools).not.toContain("finalize")
     expect(result.activeTools).not.toContain("knowhere_search")
   })
 
-  it("opens only memory_search after intent says retrieval may be needed", () => {
+  it("does not expose memory_search again after its one call", () => {
     const result = prepareHarnessStep({
-      stepNumber: 3,
+      stepNumber: 4,
+      hasMemorySearch: true,
       intent: {
         task: "answer",
         dependsOnPreviousTurn: false,
@@ -1116,9 +805,7 @@ describe("agent harness runtime", () => {
       messages: [],
     })
 
-    expect(result.activeTools).toContain("memory_search")
-    expect(result.activeTools).toContain("finalize")
-    expect(result.activeTools).not.toContain("knowhere_search")
+    expect(result.activeTools).not.toContain("memory_search")
   })
 
   it("keeps Knowhere tools closed for no_retrieval", () => {
@@ -1135,7 +822,8 @@ describe("agent harness runtime", () => {
       messages: [],
     })
 
-    expect(result.activeTools).toContain("finalize")
+    expect(result.activeTools).toContain("prepareAnswer")
+    expect(result.activeTools).not.toContain("finalize")
     expect(result.activeTools).not.toContain("memory_search")
     expect(result.activeTools).not.toContain("knowhere_search")
   })
@@ -1189,7 +877,7 @@ describe("agent harness runtime", () => {
     expect(result.activeTools).not.toContain("knowhere_grep_chunks")
   })
 
-  it("reopens finalize after must_use_sources has called knowhere_search, including empty results", () => {
+  it("opens answer preparation after must_use_sources has called knowhere_search", () => {
     const result = prepareHarnessStep({
       stepNumber: 4,
       hasKnowhereSearch: true,
@@ -1204,138 +892,284 @@ describe("agent harness runtime", () => {
       messages: [],
     })
 
-    expect(result.activeTools).toContain("finalize")
+    expect(result.activeTools).toContain("prepareAnswer")
+    expect(result.activeTools).not.toContain("finalize")
     expect(result.activeTools).toContain("knowhere_search")
   })
 
-  it("forces image inspection before forced finalization when image assets are available", () => {
+  it("forces answer preparation after the second Knowhere refinement", () => {
     const result = prepareHarnessStep({
-      stepNumber: 12,
-      hasUninspectedImageAssets: true,
-      messages: [
-        {
-          role: "tool",
-          content: [
-            {
-              type: "tool-result",
-              toolCallId: "call_1",
-              toolName: "knowhere_search",
-              output: {
-                type: "text",
-                value:
-                  '<knowhere operation="search" status="ok"><asset ref="asset:r1:referenced:1" type="image" /></knowhere>',
-              },
-            },
-          ],
-        },
-      ],
+      stepNumber: 8,
+      hasKnowhereSearch: true,
+      hasReachedKnowhereSearchLimit: true,
+      intent: {
+        task: "answer",
+        dependsOnPreviousTurn: false,
+        retrievalNeeded: "yes",
+        targetModalities: ["text"],
+        constraints: {},
+        groundingPolicy: "must_use_sources",
+      },
+      messages: [],
     })
 
-    expect(result.activeTools).toEqual(["inspectImage"])
+    expect(result.activeTools).toEqual(["prepareAnswer"])
     expect(result.toolChoice).toEqual({
       type: "tool",
-      toolName: "inspectImage",
+      toolName: "prepareAnswer",
     })
-    expect(result.messages).toEqual([
-      {
-        role: "tool",
-        content: [
-          {
-            type: "tool-result",
-            toolCallId: "call_1",
-            toolName: "knowhere_search",
-            output: {
-              type: "text",
-              value:
-                '<knowhere operation="search" status="ok"><asset ref="asset:r1:referenced:1" type="image" /></knowhere>',
-            },
-          },
-        ],
+  })
+
+  it("replaces retrieval history with the assembled context for finalization", () => {
+    const answerContextMessage = {
+      role: "user" as const,
+      content: [{ type: "text" as const, text: "## User's Question\nQuestion" }],
+    }
+    const result = prepareHarnessStep({
+      stepNumber: 5,
+      messages: [{ role: "user", content: "retrieval history" }],
+      answerContextMessage,
+    })
+
+    expect(result.messages).toEqual([answerContextMessage])
+    expect(result.activeTools).toEqual(["finalize"])
+    expect(result.toolChoice).toEqual({ type: "tool", toolName: "finalize" })
+  })
+
+  it("forces retainEvidence after a search returns new evidence", () => {
+    const result = prepareHarnessStep({
+      stepNumber: 4,
+      hasPendingRetention: true,
+      pendingRetentionRange: { startPick: 1, endPick: 3 },
+      hasKnowhereSearch: true,
+      intent: {
+        task: "answer",
+        dependsOnPreviousTurn: false,
+        retrievalNeeded: "yes",
+        targetModalities: ["text"],
+        constraints: {},
+        groundingPolicy: "must_use_sources",
       },
+      messages: [],
+    })
+
+    expect(result.activeTools).toEqual(["retainEvidence"])
+    expect(result.toolChoice).toEqual({
+      type: "tool",
+      toolName: "retainEvidence",
+    })
+    expect(result.messages).toEqual([
       {
         role: "user",
-        content: expect.stringContaining("Call inspectImage now"),
+        content: expect.stringContaining("1-3"),
       },
     ])
+    expect(result.activeTools).not.toContain("finalize")
+    expect(result.activeTools).not.toContain("knowhere_search")
   })
 
-  it("reserves the finalization step even when unused page assets remain", () => {
-    const result = prepareHarnessStep({
-      stepNumber: 13,
-      hasUninspectedImageAssets: true,
-      messages: [
+  it("prepares the answer only after the latest search has been retained", async () => {
+    const ledger = createEvidenceLedger()
+    ledger.addRetrievalResponse(makeRetrievalResponse())
+    const state: { answerContextRequested?: boolean } = {}
+    const tools = createHarnessTools({
+      state,
+      ledger,
+      memoryTools: makeMemoryTools(),
+      knowhereTools: makeKnowhereTools(),
+      recentTurns: [],
+    })
+
+    expect(await executeTool(tools.prepareAnswer, {})).toMatchObject({ ok: false })
+    expect(state.answerContextRequested).not.toBe(true)
+
+    await executeTool(tools.retainEvidence, { picks: [1] })
+    expect(await executeTool(tools.prepareAnswer, {})).toEqual({ ok: true })
+    expect(state.answerContextRequested).toBe(true)
+  })
+
+  it("rejects displayed artifacts whose evidence was not retained", async () => {
+    const ledger = createEvidenceLedger()
+    ledger.addRetrievalResponse(makeRetrievalResponse())
+    const tools = createHarnessTools({
+      state: {},
+      ledger,
+      memoryTools: makeMemoryTools(),
+      knowhereTools: makeKnowhereTools(),
+      recentTurns: [],
+    })
+    await executeTool(tools.retainEvidence, { picks: [] })
+
+    const result = await executeTool(tools.finalize, {
+      text: "See the chart.",
+      citations: [],
+      memoryCitations: [],
+      artifacts: [
         {
-          role: "user",
-          content: "What is the penalty amount?",
+          type: "image",
+          ref: "asset:r1:result:1",
+          display: true,
+          reason: "Show the chart.",
         },
       ],
+      unresolved: [],
+    })
+    expect(result).toMatchObject({
+      ok: false,
+      unretainedArtifactRefs: ["asset:r1:result:1"],
     })
+  })
 
-    expect(result.activeTools).toEqual(["finalize"])
-    expect(result.toolChoice).toEqual({
-      type: "tool",
-      toolName: "finalize",
+  it("rejects retainEvidence picks outside the latest search", async () => {
+    const ledger = createEvidenceLedger()
+    ledger.addRetrievalResponse(makeRetrievalResponse())
+    const tools = createHarnessTools({
+      state: {},
+      ledger,
+      memoryTools: makeMemoryTools(),
+      knowhereTools: makeKnowhereTools(),
+      recentTurns: [],
+    })
+
+    const rejected = await executeTool(tools.retainEvidence, { picks: [2] })
+    expect(rejected).toMatchObject({
+      ok: false,
+      invalidPicks: [2],
     })
+    expect(ledger.hasPendingRetention()).toBe(true)
+
+    const accepted = await executeTool(tools.retainEvidence, { picks: [] })
+    expect(accepted).toMatchObject({ ok: true, retainedPicks: [] })
+    expect(ledger.hasPendingRetention()).toBe(false)
+    expect(ledger.isRetained(1)).toBe(false)
   })
 
-  it("forces finalize at step 13 using existing tool results", () => {
-    const result = prepareHarnessStep({
-      stepNumber: 13,
-      messages: [
+  it("rejects finalize of unretained first-search picks after a later search", async () => {
+    const ledger = createEvidenceLedger()
+    const tools = createHarnessTools({
+      state: {},
+      ledger,
+      memoryTools: makeMemoryTools(),
+      knowhereTools: makeKnowhereTools(),
+      recentTurns: [],
+    })
+    ledger.addRetrievalResponse(makeRetrievalResponse())
+    await executeTool(tools.retainEvidence, { picks: [] })
+    ledger.addRetrievalResponse({
+      ...makeRetrievalResponse(),
+      query: "second query",
+      results: [
         {
-          role: "tool",
-          content: [
-            {
-              type: "tool-result",
-              toolCallId: "call_1",
-              toolName: "knowhere_search",
-              output: {
-                type: "text",
-                value:
-                  '<knowhere operation="search" status="ok"><chunk ref="r1:result:1"></chunk></knowhere>',
-              },
-              providerOptions: {
-                google: {
-                  thoughtSignature: "signature-1",
-                },
-              },
-            },
-          ],
+          content: "Second retrieval evidence.",
+          chunkType: "text",
+          score: 0.8,
+          source: {
+            documentId: "doc_2",
+            sourceFileName: "second.pdf",
+            sectionPath: "Second",
+          },
         },
       ],
     })
+    await executeTool(tools.retainEvidence, { picks: [2] })
 
-    expect(result.activeTools).toEqual(["finalize"])
-    expect(result.toolChoice).toEqual({
-      type: "tool",
-      toolName: "finalize",
+    const rejected = await executeTool(tools.finalize, {
+      text: "First source [[cite:1]].",
+      citations: [{ pick: 1 }],
+      memoryCitations: [],
+      artifacts: [],
+      unresolved: [],
     })
-    expect(result.messages).toEqual([
-      {
-        role: "tool",
-        content: [
-          {
-            type: "tool-result",
-            toolCallId: "call_1",
-            toolName: "knowhere_search",
-            output: {
-              type: "text",
-              value:
-                '<knowhere operation="search" status="ok"><chunk ref="r1:result:1"></chunk></knowhere>',
-            },
-          },
-        ],
-      },
-      {
-        role: "user",
-        content: expect.stringContaining(
-          "Use only the evidence and tool results already available",
-        ),
-      },
-    ])
+    expect(rejected).toMatchObject({
+      ok: false,
+      unretainedPicks: [1],
+    })
+    expect(String((rejected as { message: string }).message)).toContain(
+      "Unretained citation picks",
+    )
+    expect(String((rejected as { message: string }).message)).not.toContain(
+      "Unknown citation picks",
+    )
+
+    const accepted = await executeTool(tools.finalize, {
+      text: "Second source [[cite:1]].",
+      citations: [{ pick: 2 }],
+      memoryCitations: [],
+      artifacts: [],
+      unresolved: [],
+    })
+    expect(accepted).toMatchObject({
+      ok: true,
+      citations: [{ ref: "r2:result:1" }],
+    })
+  })
+
+  it("allows the first knowhere_search without gapReason and rejects a follow-up without it", async () => {
+    const search = vi
+      .fn<KnowhereToolRuntime["search"]>()
+      .mockResolvedValue(makeRetrievalResponse())
+    const tools = createHarnessTools({
+      state: {},
+      ledger: createEvidenceLedger(),
+      memoryTools: makeMemoryTools(),
+      knowhereTools: makeKnowhereTools(search),
+      recentTurns: [],
+    })
+
+    const first = await executeTool(tools.knowhere_search, { query: "first" })
+    expect(first).toContain('status="ok"')
+    expect(search).toHaveBeenCalledWith(
+      expect.objectContaining({ query: "first" }),
+    )
+    expect(search.mock.calls[0]?.[0]).not.toHaveProperty("gapReason")
+
+    const rejected = await executeTool(tools.knowhere_search, { query: "second" })
+    expect(rejected).toContain('status="error"')
+    expect(String(rejected)).toContain("gapReason")
+    expect(search).toHaveBeenCalledTimes(1)
+
+    const accepted = await executeTool(tools.knowhere_search, {
+      query: "second",
+      gapReason: "The first search lacked the wording this query will add.",
+    })
+    expect(accepted).toContain('status="ok"')
+    expect(search).toHaveBeenCalledWith(
+      expect.objectContaining({
+        query: "second",
+        gapReason: "The first search lacked the wording this query will add.",
+      }),
+    )
+
+    const third = await executeTool(tools.knowhere_search, {
+      query: "third",
+      gapReason: "The second search still lacked the requested comparison.",
+    })
+    expect(third).toContain('status="ok"')
+
+    const fourth = await executeTool(tools.knowhere_search, {
+      query: "fourth",
+      gapReason: "Try one more query.",
+    })
+    expect(fourth).toContain('status="error"')
+    expect(fourth).toContain("initial search and two refinements")
+    expect(search).toHaveBeenCalledTimes(3)
   })
+
 })
 
+function retainLatestSearch(
+  tools: { retainEvidence: unknown },
+  ledger: ReturnType<typeof createEvidenceLedger>,
+): Promise<unknown> {
+  const pending = ledger.pendingRetentionRange()
+  if (!pending) return Promise.resolve(undefined)
+  const picks: number[] = []
+  for (let pick = pending.startPick; pick <= pending.endPick; pick += 1) {
+    picks.push(pick)
+  }
+  return executeTool(tools.retainEvidence, { picks })
+}
+
 function executeTool(tool: unknown, input: unknown): Promise<unknown> {
   return (tool as { execute: (input: unknown) => Promise<unknown> }).execute(input)
 }
@@ -1396,25 +1230,39 @@ function makeRetrievalResponse(): RetrievalQueryResponse {
   }
 }
 
-function makeTableRetrievalResponse(): RetrievalQueryResponse {
+function makeConnectedRetrievalResponse(): RetrievalQueryResponse {
   return {
     namespace: "notebook",
-    query: "q4 table",
-    routerUsed: "workflow_single_step",
+    query: "comparison",
+    routerUsed: "agent_explore",
     answerText: null,
-    evidenceText: "Table evidence",
+    evidenceText: "Comparison evidence",
     stopReason: "answer_done",
     failureReason: null,
     results: [
       {
-        content: "",
-        chunkType: "table",
-        score: 0.8,
-        assetUrl: "https://assets.example/tables/revenue.html",
+        chunkId: "text_chunk",
+        content: "Comparison [tables/comparison.html]",
+        chunkType: "text",
+        score: 0.9,
+        metadata: {
+          connectTo: [
+            {
+              target: "table_chunk",
+              relation: "embeds",
+              ref: "[tables/comparison.html]",
+            },
+            {
+              target: "image_chunk",
+              relation: "embeds",
+              ref: "[images/comparison.jpg]",
+            },
+          ],
+        },
         source: {
           documentId: "doc_1",
-          sourceFileName: "report.pdf",
-          sectionPath: "tables/revenue.html",
+          sourceFileName: "cardiology.pdf",
+          sectionPath: "Differential diagnosis",
         },
       },
     ],
@@ -1422,61 +1270,34 @@ function makeTableRetrievalResponse(): RetrievalQueryResponse {
   }
 }
 
-function makeImageRetrievalResponse(count: number): RetrievalQueryResponse {
+function toolCallResult(
+  calls: readonly {
+    toolCallId: string
+    toolName: string
+    input: unknown
+  }[],
+) {
   return {
-    namespace: "notebook",
-    query: "q4 images",
-    routerUsed: "workflow_single_step",
-    answerText: null,
-    evidenceText: "Image evidence",
-    stopReason: "answer_done",
-    failureReason: null,
-    results: Array.from({ length: count }, (_, index) => ({
-      content: "",
-      chunkType: "image",
-      score: 0.8,
-      assetUrl: `https://assets.example/images/chart-${index + 1}.png`,
-      source: {
-        documentId: "doc_1",
-        sourceFileName: "report.pdf",
-        sectionPath: `images/chart-${index + 1}.png`,
-      },
+    content: calls.map((call) => ({
+      type: "tool-call" as const,
+      toolCallId: call.toolCallId,
+      toolName: call.toolName,
+      input: JSON.stringify(call.input),
     })),
-    referencedChunks: [],
-  }
-}
-
-function makePageCitationRetrievalResponse(): RetrievalQueryResponse {
-  return {
-    namespace: "notebook",
-    query: "进度计划",
-    routerUsed: "workflow_single_step",
-    answerText: null,
-    evidenceText: "Root / （6）现场工期进度管理方面的违约责任",
-    stopReason: "answer_done",
-    failureReason: null,
-    results: [],
-    referencedChunks: [
-      {
-        chunkId: "chunk_page_8",
-        documentId: "doc_contract",
-        chunkType: "page",
-        sectionPath: "Root / （6）现场工期进度管理方面的违约责任",
-        filePath: null,
-        jobId: "job_contract",
-        assetUrl: "https://assets.example/page-8.png",
-        metadata: {
-          pageNums: [8],
-          pageAssets: [
-            {
-              pageNum: 8,
-              artifactRef: "page_citation_assets/page-8.png",
-              assetUrl: "https://assets.example/page-8.png",
-              contentType: "image/png",
-            },
-          ],
-        },
+    finishReason: { unified: "tool-calls" as const, raw: undefined },
+    usage: {
+      inputTokens: {
+        total: undefined,
+        noCache: undefined,
+        cacheRead: undefined,
+        cacheWrite: undefined,
       },
-    ],
+      outputTokens: {
+        total: undefined,
+        text: undefined,
+        reasoning: undefined,
+      },
+    },
+    warnings: [],
   }
 }
diff --git a/src/agent-harness/runtime.ts b/src/agent-harness/runtime.ts
index dbe91a5..4c0784b 100644
--- a/src/agent-harness/runtime.ts
+++ b/src/agent-harness/runtime.ts
@@ -7,39 +7,35 @@ import {
 } from "ai"
 import { z } from "zod"
 
+import { composeAnswerContext, type ReadTableHtml } from "./answer-context"
 import { createEvidenceLedger } from "./ledger"
-import { getCanonicalImageAssetKey } from "./image-asset-identity"
 import { knowhereToolText } from "./knowhere-text"
 import { memoryToolText } from "./memory-text"
-import { mergeImageInspectionHighlights } from "./image-highlights"
 import type {
   AgentTurn,
   AgentTurnInput,
   ContextPolicy,
-  EvidenceAsset,
-  EvidenceChunk,
   EvidenceLedgerSnapshot,
   HarnessRunResult,
   HarnessToolCallTrace,
   HarnessTrace,
-  ImageInspectionAsset,
-  ImageInspectionHighlights,
-  ImageInspectionResponse,
-  InspectImages,
   IntentFrame,
   KnowhereSearchTargetContent,
   KnowhereToolRuntime,
+  MemoryCitation,
   MemorySearchKind,
+  MemorySearchItem,
   MemoryToolRuntime,
   OutputArtifactView,
   OutputCitation,
   OutputManifest,
+  ResolveConnectedAssets,
 } from "./types"
 import { memorySearchKinds } from "./types"
 
-const defaultMaxSteps = 14
-const imageInspectionReminderStepNumber = 12
-const forcedFinalizationStepNumber = 13
+const defaultMaxSteps = 15
+const maxKnowhereRefinements = 2
+const maxKnowhereSearchAttempts = 1 + maxKnowhereRefinements
 
 type ToolLoopAgentSettings = ConstructorParameters<typeof ToolLoopAgent>[0]
 
@@ -50,7 +46,8 @@ export type RunAgentHarnessInput = {
   readonly turn: AgentTurnInput
   readonly knowhereTools: KnowhereToolRuntime
   readonly memoryTools: MemoryToolRuntime
-  readonly inspectImages?: InspectImages
+  readonly resolveConnectedAssets?: ResolveConnectedAssets
+  readonly readTableHtml?: ReadTableHtml
   readonly maxSteps?: number
 }
 
@@ -59,9 +56,12 @@ type HarnessToolState = {
   contextPolicy?: ContextPolicy
   finalizedManifest?: OutputManifest
   finalized?: boolean
+  answerContextRequested?: boolean
+  answerContextMessage?: ModelMessage
+  memoryItems?: MemorySearchItem[]
+  memorySearchAttempted?: boolean
+  knowhereSearchAttemptCount?: number
   priorTurnReads?: string[]
-  inspectedImageRefs?: string[]
-  imageHighlights?: ImageInspectionHighlights[]
   toolCalls?: HarnessToolCallTrace[]
 }
 
@@ -91,13 +91,14 @@ const knowhereSearchTargetContentSchema = z.enum([
 const knowhereSearchSchema = z.object({
   query: z.string().min(1),
   includeDocumentIds: z.array(z.string().trim().min(1)).optional().describe(
-    "Only search these verified document IDs. Omit for unrestricted search; [] searches no documents. Use IDs from source context or previous search results, never filenames or guessed IDs.",
+    "Only search these verified document IDs. Omit for unrestricted search; [] searches no documents. Use IDs from previous search results, never filenames or guessed IDs.",
   ),
   excludeDocumentIds: z.array(z.string().trim().min(1)).optional().describe(
     "Exclude these verified document IDs. Exclusions take precedence over includeDocumentIds. If the ID is unknown, describe the document constraint in query instead.",
   ),
   targetContent: knowhereSearchTargetContentSchema.default("all"),
   purpose: z.string().optional(),
+  gapReason: z.string().optional(),
   topK: z.number().int().min(1).max(12).optional(),
   signalPaths: z.array(z.string().min(1)).max(8).optional(),
   filterMode: z.enum(["keep", "delete"]).optional(),
@@ -206,36 +207,53 @@ export async function runAgentHarness(
     ledger,
     knowhereTools: input.knowhereTools,
     memoryTools: input.memoryTools,
-    inspectImages: input.inspectImages,
     recentTurns: input.turn.recentTurns,
   })
   const agent = new ToolLoopAgent({
     model: input.model,
     instructions: buildHarnessSystemPrompt(input.turn),
     tools,
-    prepareStep: ({ messages: stepMessages, stepNumber }) =>
-      prepareHarnessStep({
+    prepareStep: async ({ messages: stepMessages, stepNumber }) => {
+      if (
+        state.answerContextRequested &&
+        !state.answerContextMessage &&
+        !ledger.hasPendingRetention()
+      ) {
+        await ledger.resolveRetainedConnectedAssets(input.resolveConnectedAssets)
+        state.answerContextMessage = await composeAnswerContext({
+          ledger: ledger.snapshot(),
+          memoryItems: state.memoryItems ?? [],
+          memorySearchAttempted: state.memorySearchAttempted === true,
+          userText: input.turn.userText,
+          readTableHtml: input.readTableHtml,
+        })
+      }
+      return prepareHarnessStep({
         messages: stepMessages,
         stepNumber,
         intent: state.intent,
-        hasUninspectedImageAssets:
-          input.inspectImages !== undefined &&
-          hasUninspectedImageAssets({ state, ledger }),
-        hasKnowhereSearch: (state.toolCalls ?? []).some(
-          (call) => call.tool === "knowhere_search",
-        ),
-      }),
+        hasKnowhereSearch: (state.knowhereSearchAttemptCount ?? 0) > 0,
+        hasReachedKnowhereSearchLimit:
+          (state.knowhereSearchAttemptCount ?? 0) >= maxKnowhereSearchAttempts,
+        hasMemorySearch: state.memorySearchAttempted === true,
+        hasPendingRetention: ledger.hasPendingRetention(),
+        pendingRetentionRange: ledger.pendingRetentionRange(),
+        answerContextMessage: state.answerContextMessage,
+      })
+    },
     stopWhen: [
       () => state.finalized === true,
       stepCountIs(input.maxSteps ?? defaultMaxSteps),
     ],
   })
 
-  const response = await agent.generate({
+  await agent.generate({
     messages: buildHarnessMessages(input.turn),
   })
-  const manifest =
-    state.finalizedManifest ?? buildFallbackManifest(response.text.trim())
+  if (!state.finalizedManifest) {
+    throw new Error("The agent did not finalize an output manifest.")
+  }
+  const manifest = state.finalizedManifest
   const ledgerSnapshot = ledger.snapshot()
   return {
     manifest,
@@ -246,7 +264,7 @@ export async function runAgentHarness(
       finalized: state.finalized === true,
       priorTurnReads: [...(state.priorTurnReads ?? [])],
       toolCalls: [...(state.toolCalls ?? [])],
-      imageHighlights: [...(state.imageHighlights ?? [])],
+      imageHighlights: [],
       validationErrors: [],
       revisionsUsed: 0,
     },
@@ -256,7 +274,6 @@ export async function runAgentHarness(
 const alwaysAvailableTools = [
   "declareIntent",
   "setContextPolicy",
-  "inspectImage",
   "readPriorTurn",
 ] as const
 
@@ -280,46 +297,51 @@ const cognitionRetrievalTools = [] as const
 export function prepareHarnessStep(input: {
   readonly stepNumber: number
   readonly messages: readonly ModelMessage[]
-  readonly hasUninspectedImageAssets?: boolean
   readonly hasKnowhereSearch?: boolean
+  readonly hasReachedKnowhereSearchLimit?: boolean
+  readonly hasMemorySearch?: boolean
+  readonly hasPendingRetention?: boolean
+  readonly pendingRetentionRange?: { startPick: number; endPick: number } | null
+  readonly answerContextMessage?: ModelMessage
   readonly intent?: IntentFrame
 }): HarnessStepPreparation {
   const messages = sanitizeHarnessModelMessagesForStep(input.messages)
 
-  const shouldForceImageInspection =
-    input.hasUninspectedImageAssets === true &&
-    input.stepNumber === imageInspectionReminderStepNumber
+  if (input.answerContextMessage) {
+    return {
+      messages: [input.answerContextMessage],
+      activeTools: ["finalize"],
+      toolChoice: {
+        type: "tool",
+        toolName: "finalize",
+      },
+    }
+  }
 
-  if (shouldForceImageInspection) {
+  if (input.hasPendingRetention === true && input.pendingRetentionRange) {
     return {
       messages: [
         ...messages,
         {
           role: "user",
-          content: buildImageInspectionReminderFeedback(),
+          content: buildRetainEvidenceFeedback(input.pendingRetentionRange),
         },
       ],
-      activeTools: ["inspectImage"],
+      activeTools: ["retainEvidence"],
       toolChoice: {
         type: "tool",
-        toolName: "inspectImage",
+        toolName: "retainEvidence",
       },
     }
   }
 
-  if (input.stepNumber >= forcedFinalizationStepNumber) {
+  if (input.hasReachedKnowhereSearchLimit === true) {
     return {
-      messages: [
-        ...messages,
-        {
-          role: "user",
-          content: buildForcedFinalizationFeedback(),
-        },
-      ],
-      activeTools: ["finalize"],
+      messages,
+      activeTools: ["prepareAnswer"],
       toolChoice: {
         type: "tool",
-        toolName: "finalize",
+        toolName: "prepareAnswer",
       },
     }
   }
@@ -329,10 +351,10 @@ export function prepareHarnessStep(input: {
     activeTools: selectHarnessActiveTools({
       intent: input.intent,
       hasKnowhereSearch: input.hasKnowhereSearch === true,
+      hasMemorySearch: input.hasMemorySearch === true,
     }),
-    // finalize is the only output contract (see its tool description). Force
-    // a tool call every step so the model cannot end the turn with a bare
-    // text response that skips finalize's citation/artifact validation.
+    // Tool calls are required so the retrieval phase cannot end with bare
+    // text and skip the composed answer context or finalize validation.
     toolChoice: "required",
   }
 }
@@ -340,12 +362,13 @@ export function prepareHarnessStep(input: {
 function selectHarnessActiveTools(input: {
   readonly intent?: IntentFrame
   readonly hasKnowhereSearch: boolean
+  readonly hasMemorySearch: boolean
 }): Array<Extract<keyof HarnessTools, string>> {
   const tools: Array<Extract<keyof HarnessTools, string>> = [
     ...alwaysAvailableTools,
   ]
-  if (allowsFinalize(input)) {
-    tools.push("finalize")
+  if (allowsAnswerPreparation(input)) {
+    tools.push("prepareAnswer")
   }
   if (!allowsRetrieval(input.intent)) {
     return tools
@@ -354,7 +377,7 @@ function selectHarnessActiveTools(input: {
   // memory_search and knowhere_search are peers: both open together once
   // retrieval is allowed. The agent decides which to call and in what
   // order — neither tool gates the other.
-  tools.push(...fluidRetrievalTools)
+  if (!input.hasMemorySearch) tools.push(...fluidRetrievalTools)
   if (input.intent?.groundingPolicy === "must_use_sources") {
     tools.push(...crystalRetrievalTools)
   }
@@ -369,7 +392,7 @@ function allowsRetrieval(intent?: IntentFrame): boolean {
   )
 }
 
-function allowsFinalize(input: {
+function allowsAnswerPreparation(input: {
   readonly intent?: IntentFrame
   readonly hasKnowhereSearch: boolean
 }): boolean {
@@ -440,57 +463,24 @@ type ModelMessageForRole<TRole extends ModelMessage["role"]> = Extract<
   { readonly role: TRole }
 >
 
-function buildForcedFinalizationFeedback(): string {
-  return [
-    "The retrieval step budget has been reached.",
-    "Do not search again.",
-    "Use only the evidence and tool results already available in this turn.",
-    "Call finalize now with the best supported answer.",
-    "If the existing evidence is insufficient, explain the gap in unresolved",
-    "instead of making unsupported claims.",
-  ].join("\n")
-}
-
-function buildImageInspectionReminderFeedback(): string {
+function buildRetainEvidenceFeedback(range: {
+  readonly startPick: number
+  readonly endPick: number
+}): string {
   return [
-    "Retrieved image/page assets are available and have not been inspected.",
-    "Call inspectImage now with the page/image asset refs you will cite.",
-    "Use a question that locates the cited evidence on those pages for OCR/visual context and provenance boxes.",
-    "Do not finalize until those cited image assets have been inspected.",
-    "Do not search again.",
+    "The latest search returned new evidence that has not been retained.",
+    `Call retainEvidence with the pick numbers you will keep from ${range.startPick}-${range.endPick}.`,
+    "An empty picks list means this search found nothing useful.",
+    "Picks not retained cannot be cited later.",
+    "Do not search or finalize until retainEvidence has been called.",
   ].join("\n")
 }
 
-function hasUninspectedImageAssets(input: {
-  readonly state: HarnessToolState
-  readonly ledger: ReturnType<typeof createEvidenceLedger>
-}): boolean {
-  const snapshot = input.ledger.snapshot()
-  const chunksByRef = new Map(
-    snapshot.chunks.map((chunk) => [chunk.ref, chunk] as const),
-  )
-  const assetsByRef = new Map(
-    snapshot.assets.map((asset) => [asset.ref, asset] as const),
-  )
-  const inspectedKeys = new Set(
-    (input.state.inspectedImageRefs ?? []).map((ref) => {
-      const asset = assetsByRef.get(ref)
-      return asset ? getCanonicalImageAssetKey(asset, chunksByRef) : ref
-    }),
-  )
-  return snapshot.assets.some(
-    (asset) =>
-      asset.type === "image" &&
-      !inspectedKeys.has(getCanonicalImageAssetKey(asset, chunksByRef)),
-  )
-}
-
 export function createHarnessTools(input: {
   readonly state: HarnessToolState
   readonly ledger: ReturnType<typeof createEvidenceLedger>
   readonly knowhereTools: KnowhereToolRuntime
   readonly memoryTools: MemoryToolRuntime
-  readonly inspectImages?: InspectImages
   readonly recentTurns: readonly AgentTurn[]
 }) {
   return {
@@ -528,7 +518,7 @@ export function createHarnessTools(input: {
 
     memory_search: tool({
       description:
-        "Search distilled fluid memory for this workspace. Returns tagged text with memory refs such as mem:1. Use this before Knowhere document search.",
+        "Search distilled fluid memory for this workspace. Returns tagged text with memory refs such as mem:1. It can run alongside Knowhere document search when both are useful.",
       inputSchema: memorySearchSchema,
       execute: async (request) =>
         traceToolCall(input.state, {
@@ -536,6 +526,7 @@ export function createHarnessTools(input: {
           inputSummary: summarizeMemorySearchRequest(request),
           execute: async () => {
             return await executeMemorySearch({
+              state: input.state,
               memoryTools: input.memoryTools,
               request,
             })
@@ -544,9 +535,27 @@ export function createHarnessTools(input: {
         }),
     }),
 
+    retainEvidence: tool({
+      description:
+        "Keep pick numbers from the latest Knowhere search that are useful. " +
+        "Call this after every search that returns new evidence. " +
+        "An empty picks list means that search found nothing useful. " +
+        "Picks not retained cannot be cited later.",
+      inputSchema: z.object({
+        picks: z.array(z.number().int().positive()),
+      }),
+      execute: async ({ picks }) =>
+        traceToolCall(input.state, {
+          toolName: "retainEvidence",
+          inputSummary: { picks },
+          execute: async () => input.ledger.retainPicks(picks),
+          summarizeOutput: (output) => output,
+        }),
+    }),
+
     knowhere_search: tool({
       description:
-        "Search Knowhere for relevant Notebook evidence. Returns tagged text with pick numbers for finalize citations, evidence refs such as r1:result:1, and asset refs such as asset:r1:result:1.",
+        "Search Knowhere for relevant Notebook evidence. Returns tagged text with pick numbers for finalize citations, evidence refs such as r1:result:1, and connected image/table asset paths when present. After a previous search in this turn, set gapReason to what the previous search lacked and how this query will fill that gap.",
       inputSchema: knowhereSearchSchema,
       execute: async (request) =>
         traceToolCall(input.state, {
@@ -554,6 +563,7 @@ export function createHarnessTools(input: {
           inputSummary: summarizeKnowhereSearchRequest(request),
           execute: async () =>
             executeKnowhereSearch({
+              state: input.state,
               ledger: input.ledger,
               knowhereTools: input.knowhereTools,
               request,
@@ -562,29 +572,6 @@ export function createHarnessTools(input: {
         }),
     }),
 
-    inspectImage: tool({
-      description:
-        "Inspect cited Knowhere page/image asset refs for OCR, visual details, and provenance boxes. Call this after retrieval and before finalize whenever the answer cites page or image assets.",
-      inputSchema: z.object({
-        refs: z.array(z.string().min(1)).min(1),
-        question: z.string().min(1),
-      }),
-      execute: async (request) =>
-        traceToolCall(input.state, {
-          toolName: "inspectImage",
-          inputSummary: summarizeInspectImageRequest(request),
-          execute: async () =>
-            inspectRetrievedImages({
-              state: input.state,
-              ledger: input.ledger,
-              inspectImages: input.inspectImages,
-              refs: request.refs,
-              question: request.question,
-            }),
-          summarizeOutput: summarizeInspectImageOutput,
-        }),
-    }),
-
     readPriorTurn: tool({
       description:
         "Read the full text and citation labels of a specific prior turn by id " +
@@ -644,6 +631,28 @@ export function createHarnessTools(input: {
         }),
     }),
 
+    prepareAnswer: tool({
+      description:
+        "Finish retrieval and assemble retained Knowledge Base evidence, all fluid memory results, and the user's original question into one multimodal message for the answer step.",
+      inputSchema: z.object({}),
+      execute: async () =>
+        traceToolCall(input.state, {
+          toolName: "prepareAnswer",
+          inputSummary: {},
+          execute: async () => {
+            if (input.ledger.hasPendingRetention()) {
+              return {
+                ok: false as const,
+                message: "Call retainEvidence for the latest search before prepareAnswer.",
+              }
+            }
+            input.state.answerContextRequested = true
+            return { ok: true as const }
+          },
+          summarizeOutput: (output) => output,
+        }),
+    }),
+
     finalize: tool({
       description:
         "Finalize the user-facing output manifest. This is the only final answer " +
@@ -651,8 +660,8 @@ export function createHarnessTools(input: {
         "images/tables shown to the user. citations is the list of evidence picks " +
         "you used; each pick is the pick number on a Knowhere search chunk. " +
         "Notebook writes citation refs from the evidence ledger. " +
-        "Use memoryCitations for fluid memory refs. " +
-        "Cited page/image assets must be inspected with inspectImage first.",
+        "Use memoryCitations for fluid memory and copy ref, itemId, and kind " +
+        "exactly from the assembled Fluid Memory entries.",
       inputSchema: finalizeManifestSchema,
       execute: async (manifest) =>
         traceToolCall(input.state, {
@@ -664,38 +673,61 @@ export function createHarnessTools(input: {
               ledger: input.ledger,
             })
             if (!resolvedCitations.ok) {
+              if ("unknownPicks" in resolvedCitations) {
+                return {
+                  ok: false as const,
+                  message: buildFinalizeRequiresPicksMessage({
+                    unknownPicks: resolvedCitations.unknownPicks,
+                    ledger: input.ledger.snapshot(),
+                  }),
+                  unknownPicks: resolvedCitations.unknownPicks,
+                }
+              }
               return {
                 ok: false as const,
-                message: buildFinalizeRequiresPicksMessage({
-                  unknownPicks: resolvedCitations.unknownPicks,
+                message: buildFinalizeRequiresRetainedPicksMessage({
+                  unretainedPicks: resolvedCitations.unretainedPicks,
                   ledger: input.ledger.snapshot(),
                 }),
-                unknownPicks: resolvedCitations.unknownPicks,
+                unretainedPicks: resolvedCitations.unretainedPicks,
               }
             }
 
-            const outputManifest: OutputManifest = {
-              text: manifest.text,
-              citations: resolvedCitations.citations,
-              memoryCitations: manifest.memoryCitations,
-              artifacts: manifest.artifacts,
-              unresolved: manifest.unresolved,
+            const invalidMemoryCitations = getInvalidMemoryCitations({
+              citations: manifest.memoryCitations,
+              memoryItems: input.state.memoryItems ?? [],
+            })
+            if (invalidMemoryCitations.length > 0) {
+              return {
+                ok: false as const,
+                message:
+                  "memoryCitations must exactly match ref, itemId, and kind from this turn's Fluid Memory results.",
+                invalidMemoryCitations,
+              }
             }
 
-            const inspectRefs = getUninspectedCitedImageRefs({
-              manifest: outputManifest,
+            const unretainedArtifactRefs = getUnretainedDisplayedArtifactRefs({
+              artifacts: manifest.artifacts,
               ledger: input.ledger,
-              inspectedImageRefs: input.state.inspectedImageRefs ?? [],
-              inspectImagesAvailable: input.inspectImages !== undefined,
             })
-            if (inspectRefs.length > 0) {
+            if (unretainedArtifactRefs.length > 0) {
               return {
                 ok: false as const,
-                message: buildFinalizeRequiresInspectionMessage(inspectRefs),
-                inspectRefs,
+                message: buildFinalizeRequiresRetainedArtifactsMessage(
+                  unretainedArtifactRefs,
+                ),
+                unretainedArtifactRefs,
               }
             }
 
+            const outputManifest: OutputManifest = {
+              text: manifest.text,
+              citations: resolvedCitations.citations,
+              memoryCitations: manifest.memoryCitations,
+              artifacts: manifest.artifacts,
+              unresolved: manifest.unresolved,
+            }
+
             input.state.finalizedManifest = outputManifest
             input.state.finalized = true
             return { ok: true as const, ...outputManifest }
@@ -706,175 +738,16 @@ export function createHarnessTools(input: {
   } as const
 }
 
-async function inspectRetrievedImages(input: {
-  readonly state: HarnessToolState
-  readonly ledger: ReturnType<typeof createEvidenceLedger>
-  readonly inspectImages?: InspectImages
-  readonly refs: readonly string[]
-  readonly question: string
-}): Promise<
-  | ({ readonly ok: true } & ImageInspectionResponse)
-  | {
-      readonly ok: false
-      readonly message: string
-      readonly inspected: readonly []
-      readonly skipped: readonly {
-        readonly ref: string
-        readonly reason: string
-      }[]
-    }
-> {
-  const refs = getUniqueTrimmedRefs(input.refs)
-  const question = input.question.trim()
-
-  if (refs.length === 0 || question.length === 0) {
-    return {
-      ok: false,
-      message: "At least one image asset ref and a question are required.",
-      inspected: [],
-      skipped: [],
-    }
-  }
-  const snapshot = input.ledger.snapshot()
-  if (snapshot.chunks.length === 0 && snapshot.assets.length === 0) {
-    return {
-      ok: false,
-      message:
-        "Knowhere evidence tools must return image assets before inspectImage.",
-      inspected: [],
-      skipped: refs.map((ref) => ({
-        ref,
-        reason: "No Knowhere evidence is available yet.",
-      })),
-    }
-  }
-  if (!input.inspectImages) {
-    return {
-      ok: false,
-      message: "Image inspection is not available for this turn.",
-      inspected: [],
-      skipped: refs.map((ref) => ({
-        ref,
-        reason: "No image inspection capability is configured.",
-      })),
-    }
-  }
-
-  const assetsByRef = new Map(
-    snapshot.assets.map((asset) => [asset.ref, asset] as const),
-  )
-  const chunksByRef = new Map(
-    snapshot.chunks.map((chunk) => [chunk.ref, chunk] as const),
-  )
-  const skipped: {
-    readonly ref: string
-    readonly reason: string
-  }[] = []
-  const selectedAssets: ImageInspectionAsset[] = []
-  const selectedKeys = new Set<string>()
-
-  for (const ref of refs) {
-    const asset = assetsByRef.get(ref)
-    if (!asset) {
-      skipped.push({
-        ref,
-        reason: "Ref was not returned by Knowhere as an asset.",
-      })
-      continue
-    }
-    if (asset.type !== "image") {
-      skipped.push({
-        ref,
-        reason: "Ref is not an image asset.",
-      })
-      continue
-    }
-
-    const assetKey = getCanonicalImageAssetKey(asset, chunksByRef)
-    if (selectedKeys.has(assetKey)) {
-      skipped.push({
-        ref,
-        reason: "Duplicate of another retrieved page selected for inspection.",
-      })
-      continue
-    }
-    selectedKeys.add(assetKey)
-    selectedAssets.push({
-      ref: asset.ref,
-      label: asset.label,
-      ...(asset.assetUrl ? { assetUrl: asset.assetUrl } : {}),
-      ...(asset.sourcePath ? { sourcePath: asset.sourcePath } : {}),
-      ...(asset.revisionKey ? { revisionKey: asset.revisionKey } : {}),
-      source: asset.source,
-    })
-  }
-
-  if (selectedAssets.length === 0) {
-    return {
-      ok: false,
-      message: "No inspectable image asset refs were provided.",
-      inspected: [],
-      skipped,
-    }
-  }
-
-  const inspectedImageRefs = input.state.inspectedImageRefs ?? []
-
-  try {
-    const response = await input.inspectImages({
-      question,
-      assets: selectedAssets,
-    })
-    const selectedRefs = new Set(selectedAssets.map((asset) => asset.ref))
-    const successfulRefs = response.inspected
-      .map((asset) => asset.ref)
-      .filter((ref) => selectedRefs.has(ref))
-    input.state.inspectedImageRefs = [
-      ...inspectedImageRefs,
-      ...successfulRefs.filter((ref) => !inspectedImageRefs.includes(ref)),
-    ]
-    input.state.imageHighlights = mergeImageInspectionHighlights(
-      input.state.imageHighlights,
-      response.highlights,
-    )
-    if (successfulRefs.length === 0) {
-      return {
-        ok: false as const,
-        message: "Image inspection skipped every requested asset.",
-        inspected: [],
-        skipped: [...skipped, ...response.skipped],
-      }
-    }
-    return {
-      ok: true as const,
-      analysis: response.analysis,
-      inspected: response.inspected,
-      skipped: [...skipped, ...response.skipped],
-    }
-  } catch (error) {
-    return {
-      ok: false,
-      message:
-        error instanceof Error
-          ? `Image inspection failed: ${error.message}`
-          : "Image inspection failed.",
-      inspected: [],
-      skipped: selectedAssets.map((asset) => ({
-        ref: asset.ref,
-        reason: "The image inspection request failed.",
-      })),
-    }
-  }
-}
-
 function resolveCitationPicks(input: {
   readonly citations: readonly { pick: number }[]
   readonly ledger: ReturnType<typeof createEvidenceLedger>
 }):
   | { ok: true; citations: OutputCitation[] }
-  | { ok: false; unknownPicks: number[] } {
+  | { ok: false; unknownPicks: number[] }
+  | { ok: false; unretainedPicks: number[] } {
   const chunks = input.ledger.snapshot().chunks
   const unknownPicks: number[] = []
+  const unretainedPicks: number[] = []
   const citations: OutputCitation[] = []
 
   for (const citation of input.citations) {
@@ -887,15 +760,39 @@ function resolveCitationPicks(input: {
       }
       continue
     }
+    if (!input.ledger.isRetained(citation.pick)) {
+      if (!unretainedPicks.includes(citation.pick)) {
+        unretainedPicks.push(citation.pick)
+      }
+      continue
+    }
     citations.push({ ref: chunk.ref })
   }
 
   if (unknownPicks.length > 0) {
     return { ok: false, unknownPicks }
   }
+  if (unretainedPicks.length > 0) {
+    return { ok: false, unretainedPicks }
+  }
   return { ok: true, citations }
 }
 
+function getInvalidMemoryCitations(input: {
+  readonly citations: readonly MemoryCitation[]
+  readonly memoryItems: readonly MemorySearchItem[]
+}): MemoryCitation[] {
+  return input.citations.filter(
+    (citation) =>
+      !input.memoryItems.some(
+        (item) =>
+          item.ref === citation.ref &&
+          item.itemId === citation.itemId &&
+          item.kind === citation.kind,
+      ),
+  )
+}
+
 function buildFinalizeRequiresPicksMessage(input: {
   readonly unknownPicks: readonly number[]
   readonly ledger: EvidenceLedgerSnapshot
@@ -911,89 +808,66 @@ function buildFinalizeRequiresPicksMessage(input: {
   ].join(" ")
 }
 
-function getUninspectedCitedImageRefs(input: {
-  readonly manifest: OutputManifest
+function buildFinalizeRequiresRetainedPicksMessage(input: {
+  readonly unretainedPicks: readonly number[]
+  readonly ledger: EvidenceLedgerSnapshot
+}): string {
+  const retained =
+    input.ledger.retainedPicks.length > 0
+      ? `Retained picks: ${input.ledger.retainedPicks.join(" ")}.`
+      : "No evidence picks have been retained."
+  return [
+    "Citations can only use retained evidence picks.",
+    `Unretained citation picks: ${input.unretainedPicks.join(" ")}.`,
+    retained,
+    "Call retainEvidence after each search, then finalize using only retained picks.",
+  ].join(" ")
+}
+
+function getUnretainedDisplayedArtifactRefs(input: {
+  readonly artifacts: readonly OutputArtifactView[]
   readonly ledger: ReturnType<typeof createEvidenceLedger>
-  readonly inspectedImageRefs: readonly string[]
-  readonly inspectImagesAvailable: boolean
 }): string[] {
-  if (!input.inspectImagesAvailable) return []
-
-  const snapshot = input.ledger.snapshot()
-  const chunksByRef = new Map(
-    snapshot.chunks.map((chunk) => [chunk.ref, chunk] as const),
-  )
-  const assetsByRef = new Map(
-    snapshot.assets.map((asset) => [asset.ref, asset] as const),
-  )
-  const inspected = new Set(input.inspectedImageRefs)
-  const inspectedKeys = new Set(
-    input.inspectedImageRefs.map((ref) => {
-      const asset = assetsByRef.get(ref)
-      return asset ? getCanonicalImageAssetKey(asset, chunksByRef) : ref
-    }),
-  )
-
   const refs: string[] = []
-  const seenKeys = new Set<string>()
-  const addRef = (ref: string | null): void => {
-    if (!ref || inspected.has(ref)) return
-    const asset = assetsByRef.get(ref)
-    const key = asset ? getCanonicalImageAssetKey(asset, chunksByRef) : ref
-    if (seenKeys.has(key) || inspectedKeys.has(key)) return
-    seenKeys.add(key)
-    refs.push(ref)
-  }
-
-  for (const citation of input.manifest.citations) {
-    addRef(resolveImageAssetRef(citation.ref, chunksByRef, assetsByRef))
-  }
-
-  for (const artifact of input.manifest.artifacts) {
-    if (artifact.type !== "image" || artifact.display === false) continue
-    addRef(resolveImageAssetRef(artifact.ref, chunksByRef, assetsByRef))
+  for (const artifact of input.artifacts) {
+    if (artifact.display === false || artifact.type === "derived_table") continue
+    if (!isRefRetained(input.ledger, artifact.ref) && !refs.includes(artifact.ref)) {
+      refs.push(artifact.ref)
+    }
   }
-
   return refs
 }
 
-function resolveImageAssetRef(
-  ref: string,
-  chunksByRef: ReadonlyMap<string, EvidenceChunk>,
-  assetsByRef: ReadonlyMap<string, EvidenceAsset>,
-): string | null {
-  const directAsset = assetsByRef.get(ref)
-  if (directAsset?.type === "image") return directAsset.ref
-
-  const chunk = chunksByRef.get(ref)
-  if (!chunk) return null
-
-  if (chunk.assetRef) {
-    const chunkAsset = assetsByRef.get(chunk.assetRef)
-    if (chunkAsset?.type === "image") return chunkAsset.ref
-  }
+function buildFinalizeRequiresRetainedArtifactsMessage(
+  refs: readonly string[],
+): string {
+  return [
+    "Displayed artifacts can only use retained evidence.",
+    `Unretained artifact refs: ${refs.join(" ")}.`,
+    "Call retainEvidence after each search, then finalize using only retained evidence.",
+  ].join(" ")
+}
 
-  if (!chunk.chunkId) return null
-  const sibling = Array.from(chunksByRef.values()).find(
-    (candidate) =>
-      candidate.ref !== chunk.ref &&
-      candidate.chunkId === chunk.chunkId &&
-      candidate.source.documentId === chunk.source.documentId &&
-      candidate.assetRef !== undefined &&
-      assetsByRef.get(candidate.assetRef)?.type === "image",
+function pickForRef(
+  snapshot: EvidenceLedgerSnapshot,
+  ref: string,
+): number | null {
+  const chunkIndex = snapshot.chunks.findIndex((chunk) => chunk.ref === ref)
+  if (chunkIndex >= 0) return chunkIndex + 1
+  const asset = snapshot.assets.find((candidate) => candidate.ref === ref)
+  if (!asset) return null
+  const parentIndex = snapshot.chunks.findIndex(
+    (chunk) => chunk.ref === asset.chunkRef,
   )
-  return sibling?.assetRef ?? null
+  return parentIndex >= 0 ? parentIndex + 1 : null
 }
 
-function buildFinalizeRequiresInspectionMessage(
-  inspectRefs: readonly string[],
-): string {
-  return [
-    "Cited page/image assets must be inspected before finalize.",
-    `Call inspectImage with refs: ${inspectRefs.join(" ")}.`,
-    "Use a question that locates the cited evidence on those pages.",
-    "Then call finalize again, using the inspection notes in the answer.",
-  ].join(" ")
+function isRefRetained(
+  ledger: ReturnType<typeof createEvidenceLedger>,
+  ref: string,
+): boolean {
+  const pick = pickForRef(ledger.snapshot(), ref)
+  return pick !== null && ledger.isRetained(pick)
 }
 
 type KnowhereToolOperation = "search"
@@ -1002,14 +876,24 @@ type MemorySearchToolRequest = z.infer<typeof memorySearchSchema>
 type KnowhereSearchToolRequest = z.infer<typeof knowhereSearchSchema>
 
 async function executeMemorySearch(input: {
+  readonly state: HarnessToolState
   readonly memoryTools: MemoryToolRuntime
   readonly request: MemorySearchToolRequest
 }): Promise<string> {
+  if (input.state.memorySearchAttempted) {
+    return memoryToolText.formatError({
+      operation: "search",
+      message: "Fluid memory search already ran for this turn.",
+    })
+  }
+  input.state.memorySearchAttempted = true
+
   try {
     const response = await input.memoryTools.search({
       query: input.request.query,
       kinds: input.request.kinds,
     })
+    accumulateMemoryItems(input.state, response.items)
     return memoryToolText.formatSearch(response)
   } catch (error) {
     return memoryToolText.formatError({
@@ -1019,7 +903,22 @@ async function executeMemorySearch(input: {
   }
 }
 
+function accumulateMemoryItems(
+  state: HarnessToolState,
+  items: readonly MemorySearchItem[],
+): void {
+  const accumulated = state.memoryItems ?? []
+  const itemIds = new Set(accumulated.map((item) => item.itemId))
+  for (const item of items) {
+    if (itemIds.has(item.itemId)) continue
+    accumulated.push(item)
+    itemIds.add(item.itemId)
+  }
+  state.memoryItems = accumulated
+}
+
 async function executeKnowhereSearch(input: {
+  readonly state: HarnessToolState
   readonly ledger: ReturnType<typeof createEvidenceLedger>
   readonly knowhereTools: KnowhereToolRuntime
   readonly request: KnowhereSearchToolRequest
@@ -1027,6 +926,23 @@ async function executeKnowhereSearch(input: {
   return executeKnowhereTextTool({
     operation: "search",
     execute: async () => {
+      const attemptCount = input.state.knowhereSearchAttemptCount ?? 0
+      const gapReason = input.request.gapReason?.trim()
+      if (attemptCount > 0 && !gapReason) {
+        return knowhereToolText.formatError({
+          operation: "search",
+          message:
+            "This is a follow-up search. Set gapReason to what the previous search lacked and how this query will fill that gap.",
+        })
+      }
+      if (attemptCount >= maxKnowhereSearchAttempts) {
+        return knowhereToolText.formatError({
+          operation: "search",
+          message:
+            "Knowhere search already completed its initial search and two refinements. Call prepareAnswer now.",
+        })
+      }
+      input.state.knowhereSearchAttemptCount = attemptCount + 1
       const beforeSnapshot = input.ledger.snapshot()
       const response = await input.knowhereTools.search({
         query: input.request.query,
@@ -1038,6 +954,7 @@ async function executeKnowhereSearch(input: {
           : {}),
         targetContent: input.request.targetContent,
         purpose: input.request.purpose,
+        ...(gapReason ? { gapReason } : {}),
         topK: input.request.topK,
         signalPaths: input.request.signalPaths,
         filterMode: input.request.filterMode,
@@ -1069,16 +986,6 @@ async function executeKnowhereTextTool(input: {
   }
 }
 
-function getUniqueTrimmedRefs(refs: readonly string[]): string[] {
-  const normalizedRefs: string[] = []
-  for (const ref of refs) {
-    const normalizedRef = ref.trim()
-    if (!normalizedRef || normalizedRefs.includes(normalizedRef)) continue
-    normalizedRefs.push(normalizedRef)
-  }
-  return normalizedRefs
-}
-
 async function traceToolCall<T>(input: {
   readonly toolCalls?: HarnessToolCallTrace[]
 }, call: {
@@ -1173,6 +1080,7 @@ function summarizeKnowhereSearchRequest(request: {
   readonly query: string
   readonly targetContent?: KnowhereSearchTargetContent
   readonly purpose?: string
+  readonly gapReason?: string
   readonly topK?: number
   readonly signalPaths?: readonly string[]
   readonly filterMode?: string
@@ -1182,6 +1090,7 @@ function summarizeKnowhereSearchRequest(request: {
     query: request.query,
     targetContent: request.targetContent ?? "all",
     purpose: request.purpose,
+    gapReason: request.gapReason,
     topK: request.topK,
     signalPathCount: request.signalPaths?.length ?? 0,
     filterMode: request.filterMode,
@@ -1211,30 +1120,6 @@ function countOccurrences(value: string, pattern: string): number {
   }
 }
 
-function summarizeInspectImageRequest(request: {
-  readonly refs: readonly string[]
-  readonly question: string
-}): unknown {
-  return {
-    refs: getUniqueTrimmedRefs(request.refs),
-    questionLength: request.question.trim().length,
-  }
-}
-
-function summarizeInspectImageOutput(output: unknown): unknown {
-  if (!isRecord(output)) return output
-  return {
-    ok: output.ok,
-    analysisLength:
-      typeof output.analysis === "string" ? output.analysis.length : 0,
-    inspectedCount: Array.isArray(output.inspected)
-      ? output.inspected.length
-      : 0,
-    skippedCount: Array.isArray(output.skipped) ? output.skipped.length : 0,
-    message: output.message,
-  }
-}
-
 function summarizeReadPriorTurnOutput(output: unknown): unknown {
   if (!isRecord(output)) return output
   return {
@@ -1305,17 +1190,21 @@ export function buildHarnessSystemPrompt(turn: AgentTurnInput): string {
     "1. Call declareIntent when it helps you plan the response. Capture constraints like a requested image/table count in constraints.desiredCount.",
     "2. Call setContextPolicy when prior turns may influence this turn.",
     "3. When the policy needs prior-turn detail (references or corrections), call readPriorTurn for the relevant ids.",
-    "4. Call memory_search first when known fluid memory may answer the request. Call knowhere_search when memory is insufficient and groundingPolicy requires citing source documents. If the returned evidence is not enough to answer, or the query needs to focus differently, call knowhere_search again with a refined query (different keywords / topK / targetContent) instead of trying to browse documents directly. Knowhere's own retrieval agent already navigates the corpus internally.",
-    "5. After Knowhere returns image/page asset refs, call inspectImage on the page/image assets you will cite before finalize. This supplies OCR/visual context and provenance boxes.",
-    "6. Inspect each unique cited page once; retrieval already bounds the available evidence set.",
-    "7. Call finalize with text, citations, artifacts, and unresolved issues when you are ready to answer.",
+    "4. Call memory_search for relevant fluid memory and knowhere_search when groundingPolicy requires source documents. When both are useful, call them together in the same step. If the returned evidence is not enough to answer, or the query needs to focus differently, call knowhere_search again with a refined query (different keywords / topK / targetContent) instead of trying to browse documents directly. Knowhere's own retrieval agent already navigates the corpus internally.",
+    "5. After a search returns new evidence, call retainEvidence with the pick numbers from that search you will keep, then decide whether to search again or prepare the answer. An empty picks list means this search found nothing useful. Picks not retained cannot be cited later.",
+    "6. When retrieval is complete, call prepareAnswer. The retained evidence, all fluid memory results, and the user's original question will be assembled into one multimodal message.",
+    "7. Read that assembled message once and call finalize with the answer, citations, artifacts, and unresolved issues.",
     "",
     "Retrieval rules:",
-    "- First use memory_search to see whether known fluid memory can answer directly.",
-    "- Call knowhere_search only when memory is insufficient and groundingPolicy requires citing source documents.",
-    "- Refine knowhere_search at most twice. If two refined searches still do not add new relevant evidence, call finalize and list the gap in unresolved.",
+    "- memory_search and knowhere_search are parallel retrieval sources. When both apply, call them together rather than making one wait for the other.",
+    "- Call memory_search once per turn. An empty result remains empty; do not retry it.",
+    "- Call knowhere_search when groundingPolicy requires citing source documents.",
+    "- Image/table asset paths in retrieved chunks represent connected assets that prepareAnswer will resolve into table HTML and image inputs. Do not refine the search solely because those assets have not been expanded yet; refine only when the source content needed to answer is missing.",
+    "- After each search that returns new evidence, call retainEvidence before searching again or finalizing.",
+    "- When calling knowhere_search after a previous search in this turn, set gapReason to what the previous search lacked and how the new query will fill that gap.",
+    "- Refine knowhere_search at most twice. After the second refined search, call prepareAnswer regardless of its result.",
     "- Do not treat every question as a document-retrieval task.",
-    "- For document-scoped searches, use includeDocumentIds/excludeDocumentIds only with verified IDs from source context or prior search results. If IDs are unknown, preserve the document requirement in query so Knowhere can locate it. Never invent IDs or substitute filenames. Exclusions win; an empty includeDocumentIds means no documents.",
+    "- For document-scoped searches, use includeDocumentIds/excludeDocumentIds only with verified IDs from prior search results. If IDs are unknown, preserve the document requirement in query so Knowhere can locate it. Never invent IDs or substitute filenames. Exclusions win; an empty includeDocumentIds means no documents.",
     "",
     "Context rules:",
     "- If the current user request is unrelated to prior turns, set carryHistory to none and do not reuse prior topics.",
@@ -1326,19 +1215,16 @@ export function buildHarnessSystemPrompt(turn: AgentTurnInput): string {
     "- Final output is the OutputManifest passed to finalize, not freeform tool JSON or trailing text.",
     "- artifacts with display=true are the exact images/tables shown. Never display every candidate; honor constraints.desiredCount / maxCount.",
     "- Use type=derived_table only for tables you create from evidence; every derived_table.sourceRefs entry must reference evidence in the ledger.",
-    "- citations is a list of { pick }. pick is the 1-based number on the search chunk you are using. Notebook writes the citation list from those picks. Do not pass documentId or evidence refs as citations.",
+    "- citations is a list of { pick }. pick is the 1-based number on the search chunk you are using, and it must have been retained. Notebook writes the citation list from those picks. Do not pass documentId or evidence refs as citations.",
     "- Place [[cite:n]] immediately after the supported claim. n is the 1-based index into the citations array passed to finalize.",
     "- Write one marker per index: [[cite:1]] [[cite:3]] [[cite:5]]. Never group indices as [[cite:1, 3, 5]].",
     "- Do not write title/pN, [1], Markdown footnotes, or [Source N: ...] in the answer text. Notebook renders chips from [[cite:n]] and citation metadata.",
     "- Repeat [[cite:n]] when another claim uses the same page. Do not collapse same-page citations to one row.",
     "- If you have no supporting evidence pick, omit citations and list the gap in unresolved.",
-    "- inspectImage observations are inspection notes, not new source refs. Final citations and displayed image artifacts must use the original retrieved image asset refs.",
-    "- Do not finalize cited page/image assets from chunk text alone when inspectImage is available. Inspect those asset refs first, then write the answer using the inspection notes.",
-    "- If text evidence identifies a relevant page/image but does not include the exact fact, inspect the returned image asset for OCR/detail before saying the answer is unavailable.",
+    "- Images in retained evidence are embedded directly in the assembled user message. Read them there; do not call a separate image-inspection step.",
     "- If evidence is insufficient, list it in unresolved instead of fabricating facts.",
     `Surface: ${turn.surface}`,
     `Output capabilities: ${JSON.stringify(turn.outputCapabilities)}`,
-    turn.sourceContext ? `Searchable source context:\n${turn.sourceContext}` : "",
   ]
     .filter((line): line is string => line.length > 0)
     .join("\n")
@@ -1370,15 +1256,4 @@ function formatRecentTurnIndex(turn: AgentTurnInput): string {
   })
   return ["Recent turn index:", ...lines].join("\n")
 }
-
-function buildFallbackManifest(text: string): OutputManifest {
-  return {
-    text,
-    citations: [],
-    memoryCitations: [],
-    artifacts: [],
-    unresolved: text ? [] : ["The agent did not finalize an output manifest."],
-  }
-}
-
 export type { HarnessTrace }
diff --git a/src/agent-harness/types.ts b/src/agent-harness/types.ts
index b5a9416..1d7f9ae 100644
--- a/src/agent-harness/types.ts
+++ b/src/agent-harness/types.ts
@@ -68,7 +68,6 @@ export type AgentTurnInput = {
   readonly userText: string
   readonly recentTurns: readonly AgentTurn[]
   readonly localContext?: string
-  readonly sourceContext?: string
   readonly outputCapabilities: {
     readonly text: boolean
     readonly image: boolean
@@ -94,6 +93,7 @@ export type KnowhereSearchRequest = Pick<
   readonly excludeDocumentIds?: string[]
   readonly targetContent?: KnowhereSearchTargetContent
   readonly purpose?: string
+  readonly gapReason?: string
 }
 
 export type KnowhereToolRuntime = {
@@ -102,6 +102,20 @@ export type KnowhereToolRuntime = {
   ) => Promise<RetrievalQueryResponse>
 }
 
+export type ConnectedAssetLookup = {
+  readonly documentId: string
+  readonly chunkId: string
+  readonly type: "image" | "table"
+}
+
+export type ResolvedConnectedAsset = ConnectedAssetLookup & {
+  readonly assetUrl: string
+}
+
+export type ResolveConnectedAssets = (
+  lookups: readonly ConnectedAssetLookup[],
+) => Promise<readonly ResolvedConnectedAsset[]>
+
 export const memorySearchKinds = [
   "indicator_pref",
   "stance",
@@ -156,7 +170,6 @@ export type EvidenceChunk = {
     readonly sectionPath?: string | null
   }
   readonly revisionKey?: string | null
-  readonly assetRef?: string
   readonly assetUrl?: string
 }
 
@@ -223,6 +236,11 @@ export type InspectImages = (
   input: ImageInspectionRequest,
 ) => Promise<ImageInspectionResponse>
 
+export type PendingRetentionRange = {
+  readonly startPick: number
+  readonly endPick: number
+}
+
 export type EvidenceLedgerSnapshot = {
   readonly retrievalCount: number
   readonly chunks: readonly EvidenceChunk[]
@@ -231,6 +249,8 @@ export type EvidenceLedgerSnapshot = {
   readonly stopReasons: readonly string[]
   readonly failureReasons: readonly string[]
   readonly decisionTraces: readonly unknown[]
+  readonly retainedPicks: readonly number[]
+  readonly pendingRetention: PendingRetentionRange | null
 }
 
 export type OutputCitation = {
diff --git a/src/app/api/demo-sources/materialize/route.test.ts b/src/app/api/demo-sources/materialize/route.test.ts
index 3a3be24..618dc2c 100644
--- a/src/app/api/demo-sources/materialize/route.test.ts
+++ b/src/app/api/demo-sources/materialize/route.test.ts
@@ -242,6 +242,7 @@ function makeSource(
     originalBlobUrl: "https://example.com/tsla-q4-2025.pdf",
     demoKey: "demo-tsla-q4-2025",
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-10T00:00:00.000Z"),
     updatedAt: new Date("2026-05-10T00:00:00.000Z"),
     deletedAt: null,
diff --git a/src/app/api/folders/[folderId]/route.ts b/src/app/api/folders/[folderId]/route.ts
new file mode 100644
index 0000000..dc680e8
--- /dev/null
+++ b/src/app/api/folders/[folderId]/route.ts
@@ -0,0 +1,45 @@
+import type { NextRequest, NextResponse } from "next/server"
+
+import { folderRouteRequest } from "@/domains/folders/route-request"
+import { folderRouteService } from "@/domains/folders/route-service"
+import { withApiErrorResponse } from "@/lib/api-error-response"
+import { nextRouteResponse } from "@/lib/next-route-response"
+
+type RouteContext = {
+  params: Promise<{
+    folderId: string
+  }>
+}
+
+export async function PATCH(
+  request: NextRequest,
+  context: RouteContext,
+): Promise<NextResponse> {
+  return withApiErrorResponse("folders:update", async () => {
+    const { folderId } = await context.params
+    const updateRequest = await folderRouteRequest.readUpdateFolder({ request })
+    if (!updateRequest.ok) {
+      return nextRouteResponse.toNextResponse(updateRequest.result)
+    }
+
+    return nextRouteResponse.toNextResponse(
+      await folderRouteService.updateFolder({
+        folderId,
+        name: updateRequest.name,
+        parentId: updateRequest.parentId,
+      }),
+    )
+  })
+}
+
+export async function DELETE(
+  _request: NextRequest,
+  context: RouteContext,
+): Promise<NextResponse> {
+  return withApiErrorResponse("folders:delete", async () => {
+    const { folderId } = await context.params
+    return nextRouteResponse.toNextResponse(
+      await folderRouteService.deleteFolder({ folderId }),
+    )
+  })
+}
diff --git a/src/app/api/folders/route.ts b/src/app/api/folders/route.ts
new file mode 100644
index 0000000..cd9e6ad
--- /dev/null
+++ b/src/app/api/folders/route.ts
@@ -0,0 +1,28 @@
+import type { NextRequest, NextResponse } from "next/server"
+
+import { folderRouteRequest } from "@/domains/folders/route-request"
+import { folderRouteService } from "@/domains/folders/route-service"
+import { withApiErrorResponse } from "@/lib/api-error-response"
+import { nextRouteResponse } from "@/lib/next-route-response"
+
+export async function GET(): Promise<NextResponse> {
+  return withApiErrorResponse("folders:list", async () =>
+    nextRouteResponse.toNextResponse(await folderRouteService.listFolders()),
+  )
+}
+
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  return withApiErrorResponse("folders:create", async () => {
+    const createRequest = await folderRouteRequest.readCreateFolder({ request })
+    if (!createRequest.ok) {
+      return nextRouteResponse.toNextResponse(createRequest.result)
+    }
+
+    return nextRouteResponse.toNextResponse(
+      await folderRouteService.createFolder({
+        name: createRequest.name,
+        parentId: createRequest.parentId,
+      }),
+    )
+  })
+}
diff --git a/src/app/api/sources/[sourceId]/chunks/route.test.ts b/src/app/api/sources/[sourceId]/chunks/route.test.ts
index e38d9a8..3ff4188 100644
--- a/src/app/api/sources/[sourceId]/chunks/route.test.ts
+++ b/src/app/api/sources/[sourceId]/chunks/route.test.ts
@@ -312,6 +312,7 @@ describe("GET /api/sources/[sourceId]/chunks", () => {
       originalBlobUrl: "/api/demo-sources/demo-tsla-q4-2025/original",
       demoKey: "demo-tsla-q4-2025",
       chunkCount: null,
+    folderId: null,
       createdAt: new Date("2026-05-10T00:00:00.000Z"),
       updatedAt: new Date("2026-05-10T00:00:00.000Z"),
       deletedAt: null,
@@ -847,6 +848,7 @@ function makeReadySource(overrides: Record<string, unknown>) {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-10T00:00:00.000Z"),
     updatedAt: new Date("2026-05-10T00:00:00.000Z"),
     deletedAt: null,
diff --git a/src/app/api/sources/[sourceId]/route.test.ts b/src/app/api/sources/[sourceId]/route.test.ts
index b9cbcd6..034d677 100644
--- a/src/app/api/sources/[sourceId]/route.test.ts
+++ b/src/app/api/sources/[sourceId]/route.test.ts
@@ -344,6 +344,7 @@ describe("PATCH /api/sources/[sourceId]", () => {
         "https://store.public.blob.vercel-storage.com/source-uploads/upload_1/document.pdf",
       demoKey: null,
       chunkCount: null,
+    folderId: null,
       createdAt: new Date("2026-05-10T00:00:00Z"),
       updatedAt: new Date("2026-05-10T00:00:00Z"),
       deletedAt: null,
@@ -377,6 +378,7 @@ describe("PATCH /api/sources/[sourceId]", () => {
         "https://store.public.blob.vercel-storage.com/source-uploads/upload_1/document.pdf",
       demoKey: null,
       chunkCount: null,
+    folderId: null,
       createdAt: new Date("2026-05-10T00:00:00Z"),
       updatedAt: new Date("2026-05-10T00:00:00Z"),
       deletedAt: null,
diff --git a/src/app/api/sources/[sourceId]/route.ts b/src/app/api/sources/[sourceId]/route.ts
index 9d05d81..0104b42 100644
--- a/src/app/api/sources/[sourceId]/route.ts
+++ b/src/app/api/sources/[sourceId]/route.ts
@@ -31,7 +31,11 @@ export async function PATCH(
   const result =
     mutationRequest.mutation.kind === "archive"
       ? await sourceRouteService.archiveSource(mutationRequest.mutation.input)
-      : await sourceRouteService.retrySource(mutationRequest.mutation.input)
+      : mutationRequest.mutation.kind === "retry"
+        ? await sourceRouteService.retrySource(mutationRequest.mutation.input)
+        : await sourceRouteService.assignSourceFolder(
+            mutationRequest.mutation.input,
+          )
 
   return nextRouteResponse.toNextResponse(result)
 }
diff --git a/src/app/api/sources/route.test.ts b/src/app/api/sources/route.test.ts
index 154efa2..edc83a2 100644
--- a/src/app/api/sources/route.test.ts
+++ b/src/app/api/sources/route.test.ts
@@ -76,6 +76,7 @@ const source: Source = {
   originalBlobUrl: null,
   demoKey: null,
   chunkCount: null,
+    folderId: null,
   createdAt: new Date("2026-05-10T00:00:00Z"),
   updatedAt: new Date("2026-05-10T00:00:00Z"),
   deletedAt: null,
diff --git a/src/components/folder-destination-menu.tsx b/src/components/folder-destination-menu.tsx
new file mode 100644
index 0000000..6ad20a4
--- /dev/null
+++ b/src/components/folder-destination-menu.tsx
@@ -0,0 +1,56 @@
+"use client"
+
+import type { ReactElement } from "react"
+import { Folder } from "lucide-react"
+
+import {
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+} from "@/components/ui/dropdown-menu"
+import { getFolderPath } from "@/domains/folders/tree"
+import type { FolderView } from "@/domains/folders/types"
+
+export type FolderDestinationMenuProps = {
+  readonly folders: readonly FolderView[]
+  readonly excludedFolderIds?: ReadonlySet<string>
+  readonly onSelect: (folderId: string | null) => void
+}
+
+export function FolderDestinationMenu({
+  folders,
+  excludedFolderIds,
+  onSelect,
+}: FolderDestinationMenuProps): ReactElement {
+  const destinations = folders.filter(
+    (folder) => !excludedFolderIds?.has(folder.id),
+  )
+
+  return (
+    <>
+      <DropdownMenuLabel>Move to</DropdownMenuLabel>
+      <DropdownMenuItem onSelect={() => onSelect(null)}>
+        All sources
+      </DropdownMenuItem>
+      {destinations.length > 0 ? <DropdownMenuSeparator /> : null}
+      {destinations.map((folder) => (
+        <DropdownMenuItem
+          key={folder.id}
+          onSelect={() => onSelect(folder.id)}
+        >
+          <Folder className="size-3.5" />
+          {formatFolderDestination(folders, folder.id)}
+        </DropdownMenuItem>
+      ))}
+    </>
+  )
+}
+
+function formatFolderDestination(
+  folders: readonly FolderView[],
+  folderId: string,
+): string {
+  return getFolderPath(folders, folderId)
+    .map((folder) => folder.name)
+    .join(" / ")
+}
diff --git a/src/components/folder-panel-state.ts b/src/components/folder-panel-state.ts
new file mode 100644
index 0000000..16bffca
--- /dev/null
+++ b/src/components/folder-panel-state.ts
@@ -0,0 +1,49 @@
+import {
+  getFolderPath,
+  listChildFolders,
+  listSourcesInFolder,
+} from "@/domains/folders/tree"
+import type { FolderView } from "@/domains/folders/types"
+import type { SourceView } from "@/domains/sources/types"
+
+export type FolderListItem =
+  | {
+      readonly kind: "folder"
+      readonly folder: FolderView
+    }
+  | {
+      readonly kind: "source"
+      readonly source: SourceView
+    }
+
+export function getFolderListItems(
+  folders: readonly FolderView[],
+  sources: readonly SourceView[],
+  currentFolderId: string | null,
+): FolderListItem[] {
+  return [
+    ...listChildFolders(folders, currentFolderId).map(
+      (folder): FolderListItem => ({ kind: "folder", folder }),
+    ),
+    ...listSourcesInFolder(sources, currentFolderId).map(
+      (source): FolderListItem => ({ kind: "source", source }),
+    ),
+  ]
+}
+
+export function getResolvedCurrentFolderId(
+  folders: readonly FolderView[],
+  currentFolderId: string | null,
+): string | null {
+  if (!currentFolderId) return null
+  return folders.some((folder) => folder.id === currentFolderId)
+    ? currentFolderId
+    : null
+}
+
+export function getFolderBreadcrumb(
+  folders: readonly FolderView[],
+  currentFolderId: string | null,
+): FolderView[] {
+  return getFolderPath(folders, currentFolderId)
+}
diff --git a/src/components/folder-row.tsx b/src/components/folder-row.tsx
new file mode 100644
index 0000000..0f749df
--- /dev/null
+++ b/src/components/folder-row.tsx
@@ -0,0 +1,115 @@
+"use client"
+
+import type { ReactElement } from "react"
+import { Folder, MoreHorizontal, Pencil, Trash2 } from "lucide-react"
+
+import { FolderDestinationMenu } from "@/components/folder-destination-menu"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu"
+import { Spinner } from "@/components/ui/spinner"
+import { getDescendantFolderIds } from "@/domains/folders/tree"
+import type { FolderView } from "@/domains/folders/types"
+
+export type FolderRowProps = {
+  readonly folder: FolderView
+  readonly folders: readonly FolderView[]
+  readonly isDeleting?: boolean
+  readonly isNarrow?: boolean
+  readonly onDelete: (folderId: string) => void
+  readonly onMove: (folderId: string, parentId: string | null) => void
+  readonly onOpen: (folderId: string) => void
+  readonly onRename: (folderId: string) => void
+}
+
+export function FolderRow({
+  folder,
+  folders,
+  isDeleting = false,
+  isNarrow = false,
+  onDelete,
+  onMove,
+  onOpen,
+  onRename,
+}: FolderRowProps): ReactElement {
+  const excludedFolderIds = new Set(getDescendantFolderIds(folders, folder.id))
+
+  return (
+    <div
+      data-testid="folder-row"
+      className={`grid w-full min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center text-left transition-colors ${
+        isNarrow ? "gap-1.5 rounded-lg p-1.5" : "gap-2 rounded-lg p-2"
+      } border border-border/70 bg-background hover:bg-muted/40`}
+    >
+      <button
+        type="button"
+        onClick={() => onOpen(folder.id)}
+        disabled={isDeleting}
+        className={`grid min-w-0 grid-cols-[auto_minmax(0,1fr)] items-center text-left ${
+          isNarrow ? "gap-1.5" : "gap-2"
+        }`}
+        aria-label={`Open folder ${folder.name}`}
+      >
+        <div
+          className={`flex shrink-0 items-center justify-center rounded-lg bg-amber-100 text-amber-700 ${
+            isNarrow ? "size-7" : "size-8"
+          }`}
+        >
+          <Folder className="size-4" />
+        </div>
+        <div className="min-w-0 overflow-hidden">
+          <p className="truncate text-sm font-medium text-foreground">
+            {folder.name}
+          </p>
+          <p className="truncate text-[10px] font-bold uppercase tracking-wider text-muted-foreground">
+            Folder
+          </p>
+        </div>
+      </button>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <button
+            type="button"
+            disabled={isDeleting}
+            className="shrink-0 rounded-lg p-1 text-muted-foreground hover:bg-muted hover:text-foreground disabled:opacity-70"
+            aria-label={`Folder actions for ${folder.name}`}
+          >
+            {isDeleting ? (
+              <Spinner className="size-3.5" />
+            ) : (
+              <MoreHorizontal className="size-3.5" />
+            )}
+          </button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem onSelect={() => onRename(folder.id)}>
+            <Pencil className="size-3.5" />
+            Rename
+          </DropdownMenuItem>
+          <DropdownMenuSub>
+            <DropdownMenuSubTrigger>Move to…</DropdownMenuSubTrigger>
+            <DropdownMenuSubContent>
+              <FolderDestinationMenu
+                folders={folders}
+                excludedFolderIds={excludedFolderIds}
+                onSelect={(parentId) => onMove(folder.id, parentId)}
+              />
+            </DropdownMenuSubContent>
+          </DropdownMenuSub>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem onSelect={() => onDelete(folder.id)}>
+            <Trash2 className="size-3.5" />
+            Delete
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  )
+}
diff --git a/src/components/source-row.tsx b/src/components/source-row.tsx
index 473453f..4f95196 100644
--- a/src/components/source-row.tsx
+++ b/src/components/source-row.tsx
@@ -2,10 +2,18 @@
 
 import type { ReactElement } from "react";
 import Link from "next/link";
-import { FileText, ListTree, Plus, RotateCcw, Trash2 } from "lucide-react";
+import { FileText, FolderInput, ListTree, Plus, RotateCcw, Trash2 } from "lucide-react";
 
+import { FolderDestinationMenu } from "@/components/folder-destination-menu";
 import { Checkbox } from "@/components/ui/checkbox";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
 import { Spinner } from "@/components/ui/spinner";
+import { canAssignSourceToFolder } from "@/domains/folders/tree";
+import type { FolderView } from "@/domains/folders/types";
 import type { SourceView } from "@/domains/sources/types";
 
 export type SourceRowProps = {
@@ -20,6 +28,9 @@ export type SourceRowProps = {
   readonly onRetryClick?: (sourceId: string) => void;
   readonly onSelect: () => void;
   readonly onToggleIncluded?: (sourceId: string, included: boolean) => void;
+  readonly folders?: readonly FolderView[];
+  readonly isMoving?: boolean;
+  readonly onMoveToFolder?: (sourceId: string, folderId: string | null) => void;
   readonly source: SourceView;
 };
 
@@ -36,8 +47,12 @@ export function SourceRow({
   chunkTreeHref,
   isArchiving,
   isRetrying = false,
+  folders = [],
+  isMoving = false,
+  onMoveToFolder,
 }: SourceRowProps): ReactElement {
   const isReady = source.status === "ready";
+  const canMove = canAssignSourceToFolder(source) && onMoveToFolder !== undefined;
   const isBusy = source.status === "uploading" || source.status === "parsing";
   const isFailed = source.status === "failed";
   const canRetry = isFailed && source.originalFile !== undefined;
@@ -146,6 +161,31 @@ export function SourceRow({
             {isNarrow ? null : "Add"}
           </button>
         )}
+        {canMove ? (
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <button
+                type="button"
+                disabled={isMoving || isArchiving}
+                className="shrink-0 rounded-lg p-1 text-muted-foreground hover:bg-muted hover:text-foreground disabled:cursor-wait disabled:opacity-70"
+                aria-label={`Move ${source.title} to folder`}
+                title="Move to folder"
+              >
+                {isMoving ? (
+                  <Spinner className="size-3.5" />
+                ) : (
+                  <FolderInput className="size-3.5" />
+                )}
+              </button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end">
+              <FolderDestinationMenu
+                folders={folders}
+                onSelect={(folderId) => onMoveToFolder?.(source.id, folderId)}
+              />
+            </DropdownMenuContent>
+          </DropdownMenu>
+        ) : null}
         {canRetry && onRetryClick ? (
           <button
             type="button"
diff --git a/src/components/sources-panel.test.ts b/src/components/sources-panel.test.ts
index 785ec0a..d9459fd 100644
--- a/src/components/sources-panel.test.ts
+++ b/src/components/sources-panel.test.ts
@@ -336,6 +336,33 @@ describe("SourcesPanel", () => {
     expect(screen.getByText("26-27 of 27")).toBeTruthy();
   });
 
+  it("opens a folder from the mixed sources list", () => {
+    const onOpenFolder = vi.fn();
+
+    render(
+      React.createElement(C, {
+        currentFolderId: null,
+        folders: [
+          { id: "folder_cardio", parentId: null, name: "Cardio" },
+        ],
+        onOpenFolder,
+        sources: [
+          {
+            id: "source_1",
+            title: "lecture.pdf",
+            status: "ready",
+            chunkCount: 3,
+          },
+        ],
+      }),
+    );
+
+    expect(screen.getByText("All sources")).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "Open folder Cardio" }));
+    expect(onOpenFolder).toHaveBeenCalledWith("folder_cardio");
+    expect(screen.getByText("lecture.pdf")).toBeTruthy();
+  });
+
   it("hides source actions that are not wired", () => {
     render(
       React.createElement(C, {
diff --git a/src/components/sources-panel.tsx b/src/components/sources-panel.tsx
index d21181c..70f200c 100644
--- a/src/components/sources-panel.tsx
+++ b/src/components/sources-panel.tsx
@@ -5,8 +5,30 @@ import {
   useMemo,
   useState,
 } from "react";
-import { BookOpen, ChevronLeft, ChevronRight, Database, Plus } from "lucide-react";
+import { BookOpen, ChevronLeft, ChevronRight, Database, FolderPlus, Plus } from "lucide-react";
+import { FolderRow } from "@/components/folder-row";
+import {
+  getFolderBreadcrumb,
+  getFolderListItems,
+  type FolderListItem,
+} from "@/components/folder-panel-state";
 import { Button } from "@/components/ui/button";
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from "@/components/ui/breadcrumb";
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
 import { ScrollArea } from "@/components/ui/scroll-area";
 import {
   AlertDialog,
@@ -22,6 +44,7 @@ import { Spinner } from "@/components/ui/spinner";
 import { sourcePanelState } from "@/components/source-panel-state";
 import { SourceRow } from "@/components/source-row";
 import { SourceUploadDialog } from "@/components/source-upload-dialog";
+import type { FolderView } from "@/domains/folders/types";
 import type {
   OfficialLibrarySourceView,
   SourceView,
@@ -41,6 +64,17 @@ export type SourcesPanelProps = {
   onArchiveSource?: (sourceId: string) => void;
   onRetrySource?: (sourceId: string) => void;
   onLibraryOpen?: () => void;
+  folders?: readonly FolderView[];
+  currentFolderId?: string | null;
+  creatingFolder?: boolean;
+  deletingFolderIds?: readonly string[];
+  movingSourceIds?: readonly string[];
+  onOpenFolder?: (folderId: string | null) => void;
+  onCreateFolder?: (name: string) => void | Promise<void>;
+  onRenameFolder?: (folderId: string, name: string) => void | Promise<void>;
+  onMoveFolder?: (folderId: string, parentId: string | null) => void | Promise<void>;
+  onDeleteFolder?: (folderId: string) => void | Promise<void>;
+  onMoveSourceToFolder?: (sourceId: string, folderId: string | null) => void;
   onOfficialLibrarySourceAdd?: (demoSourceId: string) => void;
   archivingSourceIds?: readonly string[];
   retryingSourceIds?: readonly string[];
@@ -68,6 +102,17 @@ export function SourcesPanel({
   onArchiveSource,
   onRetrySource,
   onLibraryOpen,
+  folders = [],
+  currentFolderId = null,
+  creatingFolder = false,
+  deletingFolderIds = [],
+  movingSourceIds = [],
+  onOpenFolder,
+  onCreateFolder,
+  onRenameFolder,
+  onMoveFolder,
+  onDeleteFolder,
+  onMoveSourceToFolder,
   archivingSourceIds = [],
   retryingSourceIds = [],
   analyticsContext,
@@ -75,6 +120,13 @@ export function SourcesPanel({
   onLoginClick,
 }: Partial<SourcesPanelProps> = {}): ReactElement {
   const [confirmSourceId, setConfirmSourceId] = useState<string | null>(null);
+  const [confirmFolderId, setConfirmFolderId] = useState<string | null>(null);
+  const [folderNameDialog, setFolderNameDialog] = useState<
+    | { readonly kind: "create" }
+    | { readonly kind: "rename"; readonly folderId: string }
+    | null
+  >(null);
+  const [folderName, setFolderName] = useState("");
   const [sourcePageState, setSourcePageState] = useState<SourcePageState>({
     page: 1,
     selectedSourceId: null,
@@ -92,8 +144,19 @@ export function SourcesPanel({
   const workspaceSources = sources.filter(
     (source) => source.officialLibrary === undefined,
   );
-  const selectedSourcePage = getSelectedSourcePage(
+  const folderRows = folders ?? [];
+  const breadcrumb = getFolderBreadcrumb(folderRows, currentFolderId);
+  const confirmFolder =
+    folderRows.find((folder) => folder.id === confirmFolderId) ?? null;
+  const deletingFolderIdSet = new Set(deletingFolderIds);
+  const movingSourceIdSet = new Set(movingSourceIds);
+  const listItems = getFolderListItems(
+    folderRows,
     workspaceSources,
+    currentFolderId,
+  );
+  const selectedSourcePage = getSelectedSourcePage(
+    listItems,
     selectedSourceId,
   );
   const requestedSourcePage =
@@ -102,10 +165,22 @@ export function SourcesPanel({
       ? selectedSourcePage
       : sourcePageState.page;
   const sourcePagination = useMemo(
-    () => getSourcePagination(workspaceSources, requestedSourcePage),
-    [requestedSourcePage, workspaceSources],
+    () => getSourcePagination(listItems, requestedSourcePage),
+    [listItems, requestedSourcePage],
   );
 
+  async function submitFolderName(): Promise<void> {
+    const name = folderName.trim();
+    if (!folderNameDialog || name.length === 0) return;
+    if (folderNameDialog.kind === "create") {
+      await onCreateFolder?.(name);
+    } else {
+      await onRenameFolder?.(folderNameDialog.folderId, name);
+    }
+    setFolderNameDialog(null);
+    setFolderName("");
+  }
+
   return (
     <aside className="z-10 flex h-full w-full shrink-0 flex-col border-r border-border/70 bg-background">
       <AlertDialog
@@ -153,6 +228,78 @@ export function SourcesPanel({
           </AlertDialogFooter>
         </AlertDialogContent>
       </AlertDialog>
+      <AlertDialog
+        open={confirmFolderId !== null}
+        onOpenChange={(open) => {
+          if (!open) setConfirmFolderId(null);
+        }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Delete folder</AlertDialogTitle>
+            <AlertDialogDescription>
+              {confirmFolder
+                ? `Delete "${confirmFolder.name}"? Move its contents out first.`
+                : "Delete this folder? Move its contents out first."}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              disabled={
+                confirmFolderId !== null &&
+                deletingFolderIdSet.has(confirmFolderId)
+              }
+              onClick={() => {
+                if (confirmFolderId) {
+                  void onDeleteFolder?.(confirmFolderId);
+                  setConfirmFolderId(null);
+                }
+              }}
+            >
+              Delete
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+      <Dialog
+        open={folderNameDialog !== null}
+        onOpenChange={(open) => {
+          if (!open) {
+            setFolderNameDialog(null);
+            setFolderName("");
+          }
+        }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>
+              {folderNameDialog?.kind === "rename"
+                ? "Rename folder"
+                : "New folder"}
+            </DialogTitle>
+          </DialogHeader>
+          <Input
+            value={folderName}
+            onChange={(event) => setFolderName(event.target.value)}
+            placeholder="Folder name"
+            aria-label="Folder name"
+          />
+          <DialogFooter>
+            <Button
+              type="button"
+              size="sm"
+              disabled={creatingFolder || folderName.trim().length === 0}
+              onClick={() => {
+                void submitFolderName();
+              }}
+            >
+              {creatingFolder ? <Spinner className="size-3.5" /> : null}
+              Save
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
 
       <div className={`border-b border-border/70 ${isNarrow ? "p-2" : "p-4"}`}>
         {onLoginClick ? (
@@ -199,6 +346,25 @@ export function SourcesPanel({
             sourceCountSnapshot={sourceCountSnapshot}
           />
         )}
+        {onCreateFolder && !onLoginClick ? (
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className={`mt-2 flex w-full items-center justify-center gap-2 shadow-xs ${
+              isNarrow ? "px-0" : ""
+            }`}
+            onClick={() => {
+              setFolderName("");
+              setFolderNameDialog({ kind: "create" });
+            }}
+            aria-label="New folder"
+            title="New folder"
+          >
+            <FolderPlus className="size-4" />
+            {isNarrow ? null : "New folder"}
+          </Button>
+        ) : null}
       </div>
       <ScrollArea className="flex-1">
         <div className={isNarrow ? "px-2 py-3" : "px-4 py-4"}>
@@ -221,39 +387,70 @@ export function SourcesPanel({
               {isNarrow ? null : "open library"}
             </button>
           </div>
+          {onOpenFolder ? (
+            <FolderBreadcrumb
+              folders={breadcrumb}
+              onOpenFolder={onOpenFolder}
+            />
+          ) : null}
 
-          {workspaceSources.length === 0 ? (
+          {listItems.length === 0 ? (
             <EmptySourcesState />
           ) : (
             <div className="flex flex-col gap-1.5">
-              {sourcePagination.sources.map((source) => (
-                <SourceRow
-                  key={source.id}
-                  source={source}
-                  chunkTreeHref={getChunkTreeHref(source)}
-                  isSelected={source.id === selectedSourceId}
-                  onSelect={() =>
-                    onSelectSource?.(
-                      sourcePanelState.getNextSelectedSourceId({
-                        sourceId: source.id,
-                      }),
-                    )
-                  }
-                  onToggleIncluded={onToggleIncluded}
-                  onArchiveClick={
-                    onArchiveSource ? setConfirmSourceId : undefined
-                  }
-                  onRetryClick={onRetrySource}
-                  isArchiving={archivingSourceIdSet.has(source.id)}
-                  isRetrying={retryingSourceIdSet.has(source.id)}
-                  isNarrow={isNarrow}
-                />
-              ))}
+              {sourcePagination.items.map((item) =>
+                item.kind === "folder" ? (
+                  <FolderRow
+                    key={item.folder.id}
+                    folder={item.folder}
+                    folders={folderRows}
+                    isDeleting={deletingFolderIdSet.has(item.folder.id)}
+                    isNarrow={isNarrow}
+                    onDelete={setConfirmFolderId}
+                    onMove={(folderId, parentId) => {
+                      void onMoveFolder?.(folderId, parentId);
+                    }}
+                    onOpen={(folderId) => onOpenFolder?.(folderId)}
+                    onRename={(folderId) => {
+                      const folder = folderRows.find(
+                        (candidate) => candidate.id === folderId,
+                      );
+                      setFolderName(folder?.name ?? "");
+                      setFolderNameDialog({ kind: "rename", folderId });
+                    }}
+                  />
+                ) : (
+                  <SourceRow
+                    key={item.source.id}
+                    source={item.source}
+                    chunkTreeHref={getChunkTreeHref(item.source)}
+                    isSelected={item.source.id === selectedSourceId}
+                    onSelect={() =>
+                      onSelectSource?.(
+                        sourcePanelState.getNextSelectedSourceId({
+                          sourceId: item.source.id,
+                        }),
+                      )
+                    }
+                    onToggleIncluded={onToggleIncluded}
+                    onArchiveClick={
+                      onArchiveSource ? setConfirmSourceId : undefined
+                    }
+                    onRetryClick={onRetrySource}
+                    folders={folderRows}
+                    isMoving={movingSourceIdSet.has(item.source.id)}
+                    onMoveToFolder={onMoveSourceToFolder}
+                    isArchiving={archivingSourceIdSet.has(item.source.id)}
+                    isRetrying={retryingSourceIdSet.has(item.source.id)}
+                    isNarrow={isNarrow}
+                  />
+                ),
+              )}
             </div>
           )}
         </div>
       </ScrollArea>
-      {workspaceSources.length > sourceListPageSize ? (
+      {listItems.length > sourceListPageSize ? (
         <SourcePaginationControls
           end={sourcePagination.end}
           isNarrow={isNarrow}
@@ -301,17 +498,17 @@ function EmptySourcesState(): ReactElement {
 type SourcePagination = {
   readonly end: number;
   readonly page: number;
-  readonly sources: readonly SourceView[];
+  readonly items: readonly FolderListItem[];
   readonly start: number;
   readonly total: number;
   readonly totalPages: number;
 };
 
 function getSourcePagination(
-  sources: readonly SourceView[],
+  items: readonly FolderListItem[],
   requestedPage: number,
 ): SourcePagination {
-  const total = sources.length;
+  const total = items.length;
   const totalPages = getTotalSourcePages(total);
   const page = Math.min(Math.max(requestedPage, 1), totalPages);
   const startIndex = (page - 1) * sourceListPageSize;
@@ -320,7 +517,7 @@ function getSourcePagination(
   return {
     end: endIndex,
     page,
-    sources: sources.slice(startIndex, endIndex),
+    items: items.slice(startIndex, endIndex),
     start: total === 0 ? 0 : startIndex + 1,
     total,
     totalPages,
@@ -336,17 +533,65 @@ function getSourcePageForIndex(sourceIndex: number): number {
 }
 
 function getSelectedSourcePage(
-  sources: readonly SourceView[],
+  items: readonly FolderListItem[],
   selectedSourceId: string | null,
 ): number | null {
   if (!selectedSourceId) return null;
 
-  const selectedIndex = sources.findIndex(
-    (source) => source.id === selectedSourceId,
+  const selectedIndex = items.findIndex(
+    (item) => item.kind === "source" && item.source.id === selectedSourceId,
   );
   return selectedIndex >= 0 ? getSourcePageForIndex(selectedIndex) : null;
 }
 
+function FolderBreadcrumb({
+  folders,
+  onOpenFolder,
+}: {
+  readonly folders: readonly FolderView[];
+  readonly onOpenFolder: (folderId: string | null) => void;
+}): ReactElement {
+  return (
+    <Breadcrumb className="mb-3">
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          {folders.length === 0 ? (
+            <BreadcrumbPage>All sources</BreadcrumbPage>
+          ) : (
+            <BreadcrumbLink
+              href="#"
+              onClick={(event) => {
+                event.preventDefault();
+                onOpenFolder(null);
+              }}
+            >
+              All sources
+            </BreadcrumbLink>
+          )}
+        </BreadcrumbItem>
+        {folders.map((folder, index) => (
+          <BreadcrumbItem key={folder.id}>
+            <BreadcrumbSeparator />
+            {index === folders.length - 1 ? (
+              <BreadcrumbPage>{folder.name}</BreadcrumbPage>
+            ) : (
+              <BreadcrumbLink
+                href="#"
+                onClick={(event) => {
+                  event.preventDefault();
+                  onOpenFolder(folder.id);
+                }}
+              >
+                {folder.name}
+              </BreadcrumbLink>
+            )}
+          </BreadcrumbItem>
+        ))}
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}
+
 function getChunkTreeHref(source: SourceView): string | undefined {
   if (source.documentPresentation?.kind === "page-assets") return undefined;
   return source.documentId
diff --git a/src/components/ui/breadcrumb.tsx b/src/components/ui/breadcrumb.tsx
new file mode 100644
index 0000000..58858ea
--- /dev/null
+++ b/src/components/ui/breadcrumb.tsx
@@ -0,0 +1,113 @@
+import { cn } from "@/lib/utils"
+import { Slot } from "@radix-ui/react-slot"
+import { ChevronRight, MoreHorizontal } from "lucide-react"
+import * as React from "react"
+
+const Breadcrumb = React.forwardRef<
+  HTMLElement,
+  React.ComponentPropsWithoutRef<"nav"> & {
+    separator?: React.ReactNode
+  }
+>(({ ...props }, ref) => <nav ref={ref} aria-label="breadcrumb" {...props} />)
+Breadcrumb.displayName = "Breadcrumb"
+
+const BreadcrumbList = React.forwardRef<
+  HTMLOListElement,
+  React.ComponentPropsWithoutRef<"ol">
+>(({ className, ...props }, ref) => (
+  <ol
+    ref={ref}
+    className={cn(
+      "flex flex-wrap items-center gap-1.5 break-words text-[11px] font-semibold text-muted-foreground sm:gap-2",
+      className,
+    )}
+    {...props}
+  />
+))
+BreadcrumbList.displayName = "BreadcrumbList"
+
+const BreadcrumbItem = React.forwardRef<
+  HTMLLIElement,
+  React.ComponentPropsWithoutRef<"li">
+>(({ className, ...props }, ref) => (
+  <li
+    ref={ref}
+    className={cn("inline-flex items-center gap-1.5", className)}
+    {...props}
+  />
+))
+BreadcrumbItem.displayName = "BreadcrumbItem"
+
+const BreadcrumbLink = React.forwardRef<
+  HTMLAnchorElement,
+  React.ComponentPropsWithoutRef<"a"> & {
+    asChild?: boolean
+  }
+>(({ asChild, className, ...props }, ref) => {
+  const Comp = asChild ? Slot : "a"
+
+  return (
+    <Comp
+      ref={ref}
+      className={cn("transition-colors hover:text-foreground", className)}
+      {...props}
+    />
+  )
+})
+BreadcrumbLink.displayName = "BreadcrumbLink"
+
+const BreadcrumbPage = React.forwardRef<
+  HTMLSpanElement,
+  React.ComponentPropsWithoutRef<"span">
+>(({ className, ...props }, ref) => (
+  <span
+    ref={ref}
+    aria-disabled="true"
+    aria-current="page"
+    className={cn("font-bold tracking-wide text-foreground", className)}
+    {...props}
+  />
+))
+BreadcrumbPage.displayName = "BreadcrumbPage"
+
+const BreadcrumbSeparator = ({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<"li">) => (
+  <li
+    role="presentation"
+    aria-hidden="true"
+    className={cn("[&>svg]:size-3.5", className)}
+    {...props}
+  >
+    {children ?? <ChevronRight />}
+  </li>
+)
+BreadcrumbSeparator.displayName = "BreadcrumbSeparator"
+
+const BreadcrumbEllipsis = ({
+  className,
+  ...props
+}: React.ComponentProps<"span">) => (
+  <span
+    role="presentation"
+    aria-hidden="true"
+    className={cn("flex size-7 items-center justify-center", className)}
+    {...props}
+  >
+    <MoreHorizontal className="size-4" />
+    <span className="sr-only">More</span>
+  </span>
+)
+BreadcrumbEllipsis.displayName = "BreadcrumbEllipsis"
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+}
diff --git a/src/components/workspace-chat-workflow.test.ts b/src/components/workspace-chat-workflow.test.ts
index babf01a..25ac6b9 100644
--- a/src/components/workspace-chat-workflow.test.ts
+++ b/src/components/workspace-chat-workflow.test.ts
@@ -60,7 +60,7 @@ describe("useWorkspaceChatWorkflow", () => {
     expect(result.current.chatThreads).toEqual([thread])
   })
 
-  it("sends Chat messages with excluded Source ids and updates the active thread", async () => {
+  it("sends Chat messages with excluded Source ids and the current folder", async () => {
     const source = makeSource({
       id: "source_excluded",
       excludedFromQuery: true,
@@ -78,6 +78,7 @@ describe("useWorkspaceChatWorkflow", () => {
     })
 
     const { result } = renderWorkspaceChatWorkflow({
+      currentFolderId: "folder_1",
       initialChatThreads: [],
       initialChatMessages: [],
       sources: [source],
@@ -94,6 +95,7 @@ describe("useWorkspaceChatWorkflow", () => {
       threadId: undefined,
       useAgentic: true,
       excludedSourceIds: ["source_excluded"],
+      folderId: "folder_1",
     })
     await waitFor(() => {
       expect(result.current.chat.threadId).toBe("thread_1")
@@ -192,6 +194,7 @@ describe("useWorkspaceChatWorkflow", () => {
 
 function renderWorkspaceChatWorkflow(input: {
   readonly activeChatThreadId?: string | null
+  readonly currentFolderId?: string | null
   readonly initialChatMessages: readonly []
   readonly initialChatThreads: readonly ChatThreadView[]
   readonly isGuest?: boolean
diff --git a/src/components/workspace-chat-workflow.ts b/src/components/workspace-chat-workflow.ts
index dd85576..feaa402 100644
--- a/src/components/workspace-chat-workflow.ts
+++ b/src/components/workspace-chat-workflow.ts
@@ -35,6 +35,7 @@ type WorkspaceChatWorkflowInput = {
     materializedSources: readonly SourceView[],
   ) => void
   readonly sources: readonly SourceView[]
+  readonly currentFolderId?: string | null
 }
 
 type ChatMessageRequest = Parameters<typeof workspaceClient.sendChatMessage>[0]
@@ -67,6 +68,7 @@ export function useWorkspaceChatWorkflow({
   isGuest = false,
   onSourcesMaterialized,
   sources,
+  currentFolderId = null,
 }: WorkspaceChatWorkflowInput): WorkspaceChatWorkflow {
   const [loadingThreadId, setLoadingThreadId] = useState<string | null>(null)
   const [archivingThreadIds, setArchivingThreadIds] = useState<string[]>([])
@@ -308,6 +310,7 @@ export function useWorkspaceChatWorkflow({
         excludedSourceIds: sources
           .filter((source) => source.excludedFromQuery)
           .map((source) => source.id),
+        ...(currentFolderId ? { folderId: currentFolderId } : {}),
       })
 
       if (!body.threadId || !Array.isArray(body.messages)) {
diff --git a/src/components/workspace-folder-workflow.ts b/src/components/workspace-folder-workflow.ts
new file mode 100644
index 0000000..2669c94
--- /dev/null
+++ b/src/components/workspace-folder-workflow.ts
@@ -0,0 +1,217 @@
+"use client"
+
+import { useMemo, useState } from "react"
+import useSWR from "swr"
+import useSWRMutation from "swr/mutation"
+
+import { getResolvedCurrentFolderId } from "@/components/folder-panel-state"
+import type { FolderView } from "@/domains/folders/types"
+import type { SourceView } from "@/domains/sources/types"
+import { workspaceClient } from "@/domains/workspace/client"
+
+type WorkspaceFolderWorkflowInput = {
+  readonly initialFolders?: readonly FolderView[]
+  readonly isGuest?: boolean
+  readonly onSourceMoved?: (source: SourceView) => void
+}
+
+type WorkspaceFolderWorkflow = {
+  readonly creatingFolder: boolean
+  readonly currentFolderId: string | null
+  readonly deletingFolderIds: readonly string[]
+  readonly folders: FolderView[]
+  readonly handleCreateFolder: (name: string) => Promise<void>
+  readonly handleDeleteFolder: (folderId: string) => Promise<void>
+  readonly handleMoveFolder: (
+    folderId: string,
+    parentId: string | null,
+  ) => Promise<void>
+  readonly handleMoveSource: (
+    sourceId: string,
+    folderId: string | null,
+  ) => Promise<void>
+  readonly handleOpenFolder: (folderId: string | null) => void
+  readonly handleRenameFolder: (folderId: string, name: string) => Promise<void>
+  readonly movingSourceIds: readonly string[]
+}
+
+const foldersSWRKey = workspaceClient.keys.folders
+
+export function useWorkspaceFolderWorkflow({
+  initialFolders = [],
+  isGuest = false,
+  onSourceMoved,
+}: WorkspaceFolderWorkflowInput): WorkspaceFolderWorkflow {
+  const initialFolderRows = useMemo(() => [...initialFolders], [initialFolders])
+  const [currentFolderId, setCurrentFolderId] = useState<string | null>(null)
+  const [deletingFolderIds, setDeletingFolderIds] = useState<string[]>([])
+  const [movingSourceIds, setMovingSourceIds] = useState<string[]>([])
+  const { data: serverFolders, mutate: mutateFolders } = useSWR(
+    isGuest ? null : foldersSWRKey,
+    workspaceClient.fetchFolders,
+    {
+      fallbackData: initialFolderRows,
+      revalidateIfStale: false,
+      revalidateOnMount: false,
+    },
+  )
+  const folders = serverFolders ?? initialFolderRows
+  const resolvedCurrentFolderId = getResolvedCurrentFolderId(
+    folders,
+    currentFolderId,
+  )
+  const { trigger: createFolder, isMutating: creatingFolder } = useSWRMutation(
+    foldersSWRKey,
+    createFolderMutation,
+  )
+  const { trigger: updateFolder } = useSWRMutation(
+    foldersSWRKey,
+    updateFolderMutation,
+  )
+  const { trigger: deleteFolder } = useSWRMutation(
+    foldersSWRKey,
+    deleteFolderMutation,
+  )
+  const { trigger: assignSourceFolder } = useSWRMutation(
+    workspaceClient.keys.assignSourceFolder,
+    assignSourceFolderMutation,
+  )
+
+  function handleOpenFolder(folderId: string | null): void {
+    setCurrentFolderId(folderId)
+  }
+
+  async function handleCreateFolder(name: string): Promise<void> {
+    const folder = await createFolder({
+      name,
+      parentId: resolvedCurrentFolderId,
+    })
+    void mutateFolders(
+      (current) => [...(current ?? folders), folder],
+      { revalidate: false },
+    )
+    void mutateFolders()
+  }
+
+  async function handleRenameFolder(
+    folderId: string,
+    name: string,
+  ): Promise<void> {
+    const folder = await updateFolder({ folderId, name })
+    void mutateFolders(
+      (current) => replaceFolder(current ?? folders, folder),
+      { revalidate: false },
+    )
+  }
+
+  async function handleMoveFolder(
+    folderId: string,
+    parentId: string | null,
+  ): Promise<void> {
+    const folder = await updateFolder({ folderId, parentId })
+    void mutateFolders(
+      (current) => replaceFolder(current ?? folders, folder),
+      { revalidate: false },
+    )
+  }
+
+  async function handleDeleteFolder(folderId: string): Promise<void> {
+    setDeletingFolderIds((current) => [...current, folderId])
+    try {
+      await deleteFolder(folderId)
+      void mutateFolders(
+        (current) =>
+          (current ?? folders).filter((folder) => folder.id !== folderId),
+        { revalidate: false },
+      )
+      if (resolvedCurrentFolderId === folderId) {
+        setCurrentFolderId(null)
+      }
+    } finally {
+      setDeletingFolderIds((current) =>
+        current.filter((id) => id !== folderId),
+      )
+    }
+  }
+
+  async function handleMoveSource(
+    sourceId: string,
+    folderId: string | null,
+  ): Promise<void> {
+    setMovingSourceIds((current) => [...current, sourceId])
+    try {
+      const source = await assignSourceFolder({ sourceId, folderId })
+      onSourceMoved?.(source)
+    } finally {
+      setMovingSourceIds((current) =>
+        current.filter((id) => id !== sourceId),
+      )
+    }
+  }
+
+  return {
+    creatingFolder,
+    currentFolderId: resolvedCurrentFolderId,
+    deletingFolderIds,
+    folders,
+    handleCreateFolder,
+    handleDeleteFolder,
+    handleMoveFolder,
+    handleMoveSource,
+    handleOpenFolder,
+    handleRenameFolder,
+    movingSourceIds,
+  }
+}
+
+function replaceFolder(
+  folders: readonly FolderView[],
+  nextFolder: FolderView,
+): FolderView[] {
+  return folders.map((folder) =>
+    folder.id === nextFolder.id ? nextFolder : folder,
+  )
+}
+
+function createFolderMutation(
+  _key: string,
+  { arg }: { readonly arg: { readonly name: string; readonly parentId: string | null } },
+): Promise<FolderView> {
+  return workspaceClient.createFolder(arg)
+}
+
+function updateFolderMutation(
+  _key: string,
+  {
+    arg,
+  }: {
+    readonly arg: {
+      readonly folderId: string
+      readonly name?: string
+      readonly parentId?: string | null
+    }
+  },
+): Promise<FolderView> {
+  return workspaceClient.updateFolder(arg.folderId, {
+    name: arg.name,
+    parentId: arg.parentId,
+  })
+}
+
+function deleteFolderMutation(
+  _key: string,
+  { arg }: { readonly arg: string },
+): Promise<void> {
+  return workspaceClient.deleteFolder(arg)
+}
+
+function assignSourceFolderMutation(
+  _key: string,
+  {
+    arg,
+  }: {
+    readonly arg: { readonly sourceId: string; readonly folderId: string | null }
+  },
+): Promise<SourceView> {
+  return workspaceClient.assignSourceFolder(arg.sourceId, arg.folderId)
+}
diff --git a/src/components/workspace-shell-layout.tsx b/src/components/workspace-shell-layout.tsx
index 5a8082c..4f0d2cf 100644
--- a/src/components/workspace-shell-layout.tsx
+++ b/src/components/workspace-shell-layout.tsx
@@ -25,6 +25,7 @@ import type {
   ChatThreadView,
 } from "@/domains/chat/types"
 import type { ParsedChunkView } from "@/domains/chunks/types"
+import type { FolderView } from "@/domains/folders/types"
 import type {
   OfficialLibrarySourceView,
   SourceOriginalFileView,
@@ -98,6 +99,11 @@ export type WorkspaceShellLayoutProps = {
   readonly selectedSourceView?: SourceView
   readonly sourceTitlesByDocumentId: Readonly<Record<string, string>>
   readonly sources: readonly SourceView[]
+  readonly folders?: readonly FolderView[]
+  readonly currentFolderId?: string | null
+  readonly creatingFolder?: boolean
+  readonly deletingFolderIds?: readonly string[]
+  readonly movingSourceIds?: readonly string[]
   readonly officialLibrarySources: readonly OfficialLibrarySourceView[]
   readonly user: WorkspaceShellUser | undefined
   readonly analyticsContext?: AnalyticsContext
@@ -143,6 +149,18 @@ export type WorkspaceShellLayoutProps = {
   readonly onSourceSelected: (sourceId: string | null) => void
   readonly onSourceUploaded: (source: SourceView) => void
   readonly onToggleIncluded: (sourceId: string, included: boolean) => void
+  readonly onOpenFolder?: (folderId: string | null) => void
+  readonly onCreateFolder?: (name: string) => void | Promise<void>
+  readonly onRenameFolder?: (folderId: string, name: string) => void | Promise<void>
+  readonly onMoveFolder?: (
+    folderId: string,
+    parentId: string | null,
+  ) => void | Promise<void>
+  readonly onDeleteFolder?: (folderId: string) => void | Promise<void>
+  readonly onMoveSourceToFolder?: (
+    sourceId: string,
+    folderId: string | null,
+  ) => void
 }
 
 export function WorkspaceShellLayout(
@@ -253,6 +271,19 @@ export function WorkspaceShellLayout(
                 archivingSourceIds={[...props.archivingSourceIds]}
                 retryingSourceIds={[...retryingSourceIds]}
                 addingLibrarySourceIds={[...addingLibrarySourceIds]}
+                folders={props.folders}
+                currentFolderId={props.currentFolderId}
+                creatingFolder={props.creatingFolder}
+                deletingFolderIds={props.deletingFolderIds}
+                movingSourceIds={props.movingSourceIds}
+                onOpenFolder={props.isGuest ? undefined : props.onOpenFolder}
+                onCreateFolder={props.isGuest ? undefined : props.onCreateFolder}
+                onRenameFolder={props.isGuest ? undefined : props.onRenameFolder}
+                onMoveFolder={props.isGuest ? undefined : props.onMoveFolder}
+                onDeleteFolder={props.isGuest ? undefined : props.onDeleteFolder}
+                onMoveSourceToFolder={
+                  props.isGuest ? undefined : props.onMoveSourceToFolder
+                }
                 onLoginClick={props.isGuest ? props.onLoginClick : undefined}
               />
             )}
@@ -414,6 +445,19 @@ export function WorkspaceShellLayout(
           archivingSourceIds={[...props.archivingSourceIds]}
           retryingSourceIds={[...retryingSourceIds]}
           addingLibrarySourceIds={[...addingLibrarySourceIds]}
+          folders={props.folders}
+          currentFolderId={props.currentFolderId}
+          creatingFolder={props.creatingFolder}
+          deletingFolderIds={props.deletingFolderIds}
+          movingSourceIds={props.movingSourceIds}
+          onOpenFolder={props.isGuest ? undefined : props.onOpenFolder}
+          onCreateFolder={props.isGuest ? undefined : props.onCreateFolder}
+          onRenameFolder={props.isGuest ? undefined : props.onRenameFolder}
+          onMoveFolder={props.isGuest ? undefined : props.onMoveFolder}
+          onDeleteFolder={props.isGuest ? undefined : props.onDeleteFolder}
+          onMoveSourceToFolder={
+            props.isGuest ? undefined : props.onMoveSourceToFolder
+          }
           onLoginClick={props.isGuest ? props.onLoginClick : undefined}
         />
       </div>
diff --git a/src/components/workspace-shell.tsx b/src/components/workspace-shell.tsx
index 7dd43dc..5254403 100644
--- a/src/components/workspace-shell.tsx
+++ b/src/components/workspace-shell.tsx
@@ -12,6 +12,7 @@ import {
 import { useWorkspaceDesktopPanels } from "@/components/workspace-desktop-panels"
 import { useWorkspaceCitationFocus } from "@/components/workspace-citation-focus"
 import { useWorkspaceChatWorkflow } from "@/components/workspace-chat-workflow"
+import { useWorkspaceFolderWorkflow } from "@/components/workspace-folder-workflow"
 import { useWorkspaceSourceWorkflow } from "@/components/workspace-source-workflow"
 import { workspaceShellState } from "@/components/workspace-shell-state"
 import {
@@ -27,6 +28,7 @@ import type {
   ChatThreadView,
 } from "@/domains/chat/types"
 import type { ParsedChunkView } from "@/domains/chunks/types"
+import type { FolderView } from "@/domains/folders/types"
 import type {
   OfficialLibrarySourceView,
   SourceView,
@@ -50,6 +52,7 @@ export type WorkspaceShellProps = {
     namespace: string
   }
   sources?: SourceView[]
+  folders?: FolderView[]
   officialLibrarySources?: OfficialLibrarySourceView[]
   chatThreads?: ChatThreadView[]
   activeChatThreadId?: string | null
@@ -80,6 +83,7 @@ export function WorkspaceShell(props: WorkspaceShellProps): ReactElement {
 function WorkspaceShellContent({
   user,
   sources: initialSources,
+  folders: initialFolders,
   officialLibrarySources,
   chatThreads: initialChatThreads,
   activeChatThreadId,
@@ -101,6 +105,11 @@ function WorkspaceShellContent({
     initialSources: initialSources ?? [],
     isGuest,
   })
+  const folderWorkflow = useWorkspaceFolderWorkflow({
+    initialFolders: initialFolders ?? [],
+    isGuest,
+    onSourceMoved: sourceWorkflow.handleSourceMoved,
+  })
   const analyticsContext = useMemo<AnalyticsContext>(
     () => ({
       workspaceId: workspace?.id,
@@ -126,6 +135,7 @@ function WorkspaceShellContent({
     isGuest,
     onSourcesMaterialized: sourceWorkflow.handleSourcesMaterialized,
     sources: sourceWorkflow.sources,
+    currentFolderId: folderWorkflow.currentFolderId,
   })
   const {
     desktopPanelWidths,
@@ -244,6 +254,11 @@ function WorkspaceShellContent({
       selectedSourceView={citationFocus.selectedSource}
       sourceTitlesByDocumentId={sourceWorkflow.sourceTitlesByDocumentId}
       sources={sourceWorkflow.sources}
+      folders={folderWorkflow.folders}
+      currentFolderId={folderWorkflow.currentFolderId}
+      creatingFolder={folderWorkflow.creatingFolder}
+      deletingFolderIds={folderWorkflow.deletingFolderIds}
+      movingSourceIds={folderWorkflow.movingSourceIds}
       officialLibrarySources={officialLibrarySources ?? []}
       user={user}
       analyticsContext={analyticsContext}
@@ -270,6 +285,12 @@ function WorkspaceShellContent({
       onOfficialLibrarySourceAdd={handleOfficialLibrarySourceAdd}
       onSourceUploaded={handleSourceUploaded}
       onToggleIncluded={sourceWorkflow.handleToggleIncluded}
+      onOpenFolder={folderWorkflow.handleOpenFolder}
+      onCreateFolder={folderWorkflow.handleCreateFolder}
+      onRenameFolder={folderWorkflow.handleRenameFolder}
+      onMoveFolder={folderWorkflow.handleMoveFolder}
+      onDeleteFolder={folderWorkflow.handleDeleteFolder}
+      onMoveSourceToFolder={folderWorkflow.handleMoveSource}
     />
   )
 }
diff --git a/src/components/workspace-source-workflow.ts b/src/components/workspace-source-workflow.ts
index 7ad2871..64bb399 100644
--- a/src/components/workspace-source-workflow.ts
+++ b/src/components/workspace-source-workflow.ts
@@ -28,6 +28,7 @@ type WorkspaceSourceWorkflow = {
     materializedSources: readonly SourceView[],
   ) => void
   readonly handleSourceUploaded: (source: SourceView) => void
+  readonly handleSourceMoved: (source: SourceView) => void
   readonly handleToggleIncluded: (sourceId: string, included: boolean) => void
   readonly readySourceCount: number
   readonly retryingSourceIds: string[]
@@ -109,6 +110,14 @@ export function useWorkspaceSourceWorkflow({
     materializeDemoSourcesMutation,
   )
 
+  function handleSourceMoved(source: SourceView): void {
+    void mutateSources(
+      (current) =>
+        workspaceSourceState.upsertSource(current ?? sourceRows, source),
+      { revalidate: false },
+    )
+  }
+
   function handleSourceUploaded(source: SourceView): void {
     void mutateSources(
       (current) =>
@@ -245,6 +254,7 @@ export function useWorkspaceSourceWorkflow({
     handleSourcesRefresh,
     handleSourcesMaterialized,
     handleSourceUploaded,
+    handleSourceMoved,
     handleToggleIncluded,
     readySourceCount,
     retryingSourceIds,
diff --git a/src/domains/chat/commit-turn.test.ts b/src/domains/chat/commit-turn.test.ts
index 97f19da..0324309 100644
--- a/src/domains/chat/commit-turn.test.ts
+++ b/src/domains/chat/commit-turn.test.ts
@@ -75,6 +75,8 @@ describe("commitChatTurn", () => {
           stopReasons: [],
           failureReasons: [],
           decisionTraces: [],
+          retainedPicks: [],
+          pendingRetention: null,
         },
         finalized: true,
         priorTurnReads: [],
diff --git a/src/domains/chat/connected-assets.test.ts b/src/domains/chat/connected-assets.test.ts
new file mode 100644
index 0000000..270c32c
--- /dev/null
+++ b/src/domains/chat/connected-assets.test.ts
@@ -0,0 +1,86 @@
+import type { Documents } from "@ontos-ai/knowhere-sdk"
+import { describe, expect, it, vi } from "vitest"
+
+import { createConnectedAssetResolver } from "./connected-assets"
+
+describe("createConnectedAssetResolver", () => {
+  it("pages asset chunks by type and matches parser chunk ids", async () => {
+    const listChunks = vi.fn(async (
+      documentId: string,
+      params?: {
+        page?: number
+        chunkType?: "image" | "table"
+        includeAssetUrls?: boolean
+      },
+    ) => {
+      const page = params?.page ?? 1
+      const chunkType = params?.chunkType
+      const chunks =
+        chunkType === "table" && page === 2
+          ? [{
+              id: "dchk_table",
+              chunkId: "parser_table",
+              chunkType: "table" as const,
+              sortOrder: 1,
+              metadata: {},
+              assetUrl: "https://assets.example/table.html",
+            }]
+          : chunkType === "image"
+            ? [{
+                id: "dchk_image",
+                chunkId: "parser_image",
+                chunkType: "image" as const,
+                sortOrder: 1,
+                metadata: {},
+                assetUrl: "https://assets.example/image.jpg",
+              }]
+            : []
+      return {
+        documentId,
+        namespace: "default",
+        chunks,
+        pagination: {
+          page,
+          pageSize: 200,
+          total: chunks.length,
+          totalPages: chunkType === "table" ? 2 : 1,
+        },
+      }
+    })
+    const resolveConnectedAssets = createConnectedAssetResolver({
+      listChunks,
+    } as unknown as Pick<Documents, "listChunks">)
+
+    const result = await resolveConnectedAssets([
+      { documentId: "doc_1", chunkId: "parser_table", type: "table" },
+      { documentId: "doc_1", chunkId: "parser_image", type: "image" },
+    ])
+
+    expect(result).toEqual([
+      {
+        documentId: "doc_1",
+        chunkId: "parser_table",
+        type: "table",
+        assetUrl: "https://assets.example/table.html",
+      },
+      {
+        documentId: "doc_1",
+        chunkId: "parser_image",
+        type: "image",
+        assetUrl: "https://assets.example/image.jpg",
+      },
+    ])
+    expect(listChunks).toHaveBeenCalledWith("doc_1", {
+      page: 1,
+      pageSize: 200,
+      chunkType: "table",
+      includeAssetUrls: true,
+    })
+    expect(listChunks).toHaveBeenCalledWith("doc_1", {
+      page: 2,
+      pageSize: 200,
+      chunkType: "table",
+      includeAssetUrls: true,
+    })
+  })
+})
diff --git a/src/domains/chat/connected-assets.ts b/src/domains/chat/connected-assets.ts
new file mode 100644
index 0000000..fa5c7dd
--- /dev/null
+++ b/src/domains/chat/connected-assets.ts
@@ -0,0 +1,105 @@
+import type { Documents } from "@ontos-ai/knowhere-sdk"
+
+import type {
+  ConnectedAssetLookup,
+  ResolveConnectedAssets,
+  ResolvedConnectedAsset,
+} from "@/agent-harness"
+
+const documentChunkApiMaximumPageSize = 200
+
+type DocumentChunkReader = Pick<Documents, "listChunks">
+
+export function createConnectedAssetResolver(
+  documents: DocumentChunkReader,
+): ResolveConnectedAssets {
+  return (lookups) => resolveConnectedAssets(documents, lookups)
+}
+
+async function resolveConnectedAssets(
+  documents: DocumentChunkReader,
+  lookups: readonly ConnectedAssetLookup[],
+): Promise<readonly ResolvedConnectedAsset[]> {
+  const lookupGroups = groupLookups(lookups)
+  const resolvedGroups = await Promise.all(
+    [...lookupGroups.values()].map((group) =>
+      resolveLookupGroup(documents, group),
+    ),
+  )
+  const assetUrlByLookup = new Map(
+    resolvedGroups.flatMap((group) =>
+      group.map((asset) => [lookupKey(asset), asset.assetUrl] as const),
+    ),
+  )
+
+  return lookups.map((lookup) => {
+    const assetUrl = assetUrlByLookup.get(lookupKey(lookup))
+    if (!assetUrl) {
+      throw new Error(
+        `Connected ${lookup.type} chunk ${lookup.chunkId} was not found in document ${lookup.documentId}.`,
+      )
+    }
+    return { ...lookup, assetUrl }
+  })
+}
+
+function groupLookups(
+  lookups: readonly ConnectedAssetLookup[],
+): Map<string, ConnectedAssetLookup[]> {
+  const groups = new Map<string, ConnectedAssetLookup[]>()
+  for (const lookup of lookups) {
+    const key = `${lookup.documentId}\u0000${lookup.type}`
+    const group = groups.get(key) ?? []
+    group.push(lookup)
+    groups.set(key, group)
+  }
+  return groups
+}
+
+async function resolveLookupGroup(
+  documents: DocumentChunkReader,
+  lookups: readonly ConnectedAssetLookup[],
+): Promise<readonly ResolvedConnectedAsset[]> {
+  const first = lookups[0]
+  if (!first) return []
+
+  const remaining = new Set(lookups.map((lookup) => lookup.chunkId))
+  const resolved: ResolvedConnectedAsset[] = []
+  let page = 1
+  let totalPages = page
+
+  do {
+    const response = await documents.listChunks(first.documentId, {
+      page,
+      pageSize: documentChunkApiMaximumPageSize,
+      chunkType: first.type,
+      includeAssetUrls: true,
+    })
+    totalPages = response.pagination.totalPages
+
+    for (const chunk of response.chunks) {
+      if (!remaining.has(chunk.chunkId)) continue
+      const assetUrl = chunk.assetUrl?.trim()
+      if (!assetUrl) {
+        throw new Error(
+          `Connected ${first.type} chunk ${chunk.chunkId} has no signed asset URL.`,
+        )
+      }
+      resolved.push({
+        documentId: first.documentId,
+        chunkId: chunk.chunkId,
+        type: first.type,
+        assetUrl,
+      })
+      remaining.delete(chunk.chunkId)
+    }
+
+    page += 1
+  } while (remaining.size > 0 && page <= totalPages)
+
+  return resolved
+}
+
+function lookupKey(lookup: ConnectedAssetLookup): string {
+  return `${lookup.documentId}\u0000${lookup.type}\u0000${lookup.chunkId}`
+}
diff --git a/src/domains/chat/contracts.ts b/src/domains/chat/contracts.ts
index a38a6f9..4f9991c 100644
--- a/src/domains/chat/contracts.ts
+++ b/src/domains/chat/contracts.ts
@@ -7,9 +7,10 @@ import type {
 import type { Source } from "@/infrastructure/db/schema"
 import type {
   HarnessRunResult,
-  InspectImages,
   KnowhereToolRuntime,
   KnowhereSearchRequest,
+  ReadTableHtml,
+  ResolveConnectedAssets,
 } from "@/agent-harness"
 import type {
   ChatArtifactView,
@@ -39,6 +40,7 @@ export type AgenticRetrievalTargetContent =
 export type AgenticRetrievalPlan = {
   targetContent: AgenticRetrievalTargetContent
   purpose: string | null
+  gapReason: string | null
 }
 
 export type AgenticRetrievalQuery = KnowhereSearchRequest
@@ -56,9 +58,11 @@ export type GenerateAnswer = (input: {
   messages: readonly ChatHistoryMessage[]
   sources: readonly Source[]
   excludedSourceIds: readonly string[]
+  folderScopeSourceIds?: readonly string[]
   searchSources: SearchSources
   knowhereTools?: KnowhereToolRuntime
-  inspectImages?: InspectImages
+  resolveConnectedAssets?: ResolveConnectedAssets
+  readTableHtml?: ReadTableHtml
 }) => Promise<HarnessRunResult>
 
 export type AnswerQuestionInput = {
@@ -67,13 +71,15 @@ export type AnswerQuestionInput = {
   namespaces?: readonly string[]
   sources: readonly Source[]
   excludedSourceIds: readonly string[]
+  folderScopeSourceIds?: readonly string[]
   useAgentic?: boolean
   retrieval: RetrievalClient
   knowledge?: Knowledge
   generateAnswer: GenerateAnswer
   hardenChatAssetUrl?: HardenChatAssetUrl
   hardenMediaAssetUrls?: HardenMediaAssetUrls
-  inspectImages?: InspectImages
+  resolveConnectedAssets?: ResolveConnectedAssets
+  readTableHtml?: ReadTableHtml
   messages: readonly ChatHistoryMessage[]
 }
 
diff --git a/src/domains/chat/index.test.ts b/src/domains/chat/index.test.ts
index 48203ff..1d405cf 100644
--- a/src/domains/chat/index.test.ts
+++ b/src/domains/chat/index.test.ts
@@ -106,6 +106,35 @@ describe("answerQuestionWithRetrieval", () => {
     });
   });
 
+  it("refuses knowhere search when the current folder has no documents", async () => {
+    const retrieval = { query: vi.fn() };
+    const generateAnswer = vi.fn(async ({ searchSources }) => {
+      await expect(searchSources({ query: "What is in this folder?" })).rejects.toThrow(
+        "The current folder has no documents. Do not call knowhere_search.",
+      );
+      return makeHarnessRunResult("This folder has no documents.");
+    });
+
+    const answer = await Effect.runPromise(
+      answerQuestionWithRetrieval({
+        question: "hello",
+        namespace: "notebook-workspace",
+        sources: [makeSource({ id: "source_elsewhere" })],
+        excludedSourceIds: [],
+        folderScopeSourceIds: [],
+        retrieval,
+        generateAnswer,
+        messages: [],
+      }),
+    );
+
+    expect(retrieval.query).not.toHaveBeenCalled();
+    expect(generateAnswer).toHaveBeenCalledWith(
+      expect.objectContaining({ folderScopeSourceIds: [] }),
+    );
+    expect(answer.answer).toBe("This folder has no documents.");
+  });
+
   it.each([true, false])("sends document scope through the installed SDK (agentic=%s)", async (useAgentic) => {
     const received: Record<string, unknown>[] = []
     const result = makeRetrievalResult({
@@ -555,13 +584,21 @@ describe("answerQuestionWithRetrieval", () => {
       chunkType: "text" as const,
       sectionPath: `Reference ${index + 1}`,
     }));
+    const referencedChunksWithProvenance = [
+      {
+        documentId: "doc_provenance",
+        chunkId: "provenance-only-id",
+        pageNums: [],
+      } as unknown as (typeof referencedChunks)[number],
+      ...referencedChunks,
+    ];
     const retrieval = {
       query: vi
         .fn()
         .mockResolvedValueOnce({
           results: defaultResults,
           evidenceText: "Default evidence",
-          referencedChunks,
+          referencedChunks: referencedChunksWithProvenance,
           namespace: "default",
           query: "large response",
           routerUsed: "workflow_single_step",
@@ -572,7 +609,7 @@ describe("answerQuestionWithRetrieval", () => {
         .mockResolvedValueOnce({
           results: workspaceResults,
           evidenceText: "Workspace evidence",
-          referencedChunks,
+          referencedChunks: referencedChunksWithProvenance,
           namespace: "notebook-workspace",
           query: "large response",
           routerUsed: "workflow_single_step",
@@ -589,6 +626,7 @@ describe("answerQuestionWithRetrieval", () => {
         });
         expect(response.results).toHaveLength(6);
         expect(response.referencedChunks).toHaveLength(6);
+        expect(response.referencedChunks[0]?.chunkId).toBe("chunk_1");
         expect(response.results.map((result) => result.content)).toEqual(
           [
             ...defaultResults.slice(0, 3),
@@ -1075,6 +1113,8 @@ describe("answerQuestionWithRetrieval", () => {
             stopReasons: [],
             failureReasons: [],
             decisionTraces: [],
+            retainedPicks: [],
+            pendingRetention: null,
             chunks: [
               {
                 ref: "r1:result:1",
@@ -1084,7 +1124,6 @@ describe("answerQuestionWithRetrieval", () => {
                 chunkType: "image",
                 score: 0.9,
                 assetUrl: rawAssetUrl,
-                assetRef: "asset:r1:result:1",
                 source: {
                   documentId: "doc_identity",
                   sourceFileName: "document-generated.pdf",
@@ -1543,7 +1582,6 @@ describe("answerQuestionWithRetrieval", () => {
         chunks: [
           {
             ...makeEvidenceChunkFromRetrievalResult("r1:result:1", pageResult),
-            assetRef: "asset:r1:result:1",
           },
         ],
         assets: [
@@ -1606,7 +1644,6 @@ describe("answerQuestionWithRetrieval", () => {
       ...resultChunk,
       ref: "r1:referenced:1",
       kind: "referenced_chunk" as const,
-      assetRef: "asset:r1:referenced:1",
     };
     const generateAnswer = vi.fn(async () =>
       makeHarnessRunResultWithLedger("Revenue was $24.9B [[cite:1]].", {
@@ -1674,11 +1711,9 @@ describe("answerQuestionWithRetrieval", () => {
     });
     const catalogChunk = {
       ...makeEvidenceChunkFromRetrievalResult("r1:result:1", catalogResult),
-      assetRef: "asset:r1:result:1",
     };
     const workspaceChunk = {
       ...makeEvidenceChunkFromRetrievalResult("r1:result:2", workspaceResult),
-      assetRef: "asset:r1:result:2",
     };
     const assets = [
       {
@@ -1737,7 +1772,7 @@ describe("answerQuestionWithRetrieval", () => {
     ]);
   });
 
-  it("returns only harness-selected artifacts when retrieval has extra media candidates", async () => {
+  it("returns the exact displayed artifact set from the harness manifest", async () => {
     const frontAssetUrl = "https://blob.example/images/id-front.jpg";
     const backAssetUrl = "https://blob.example/images/id-back.jpg";
     const extraAssetUrl = "https://blob.example/images/extra.jpg";
@@ -1819,6 +1854,8 @@ describe("answerQuestionWithRetrieval", () => {
             stopReasons: [],
             failureReasons: [],
             decisionTraces: [],
+            retainedPicks: [],
+            pendingRetention: null,
             chunks: [
               {
                 ref: "r1:result:1",
@@ -1828,7 +1865,6 @@ describe("answerQuestionWithRetrieval", () => {
                 chunkType: "image",
                 score: 0.9,
                 assetUrl: frontAssetUrl,
-                assetRef: "asset:r1:result:1",
                 source: {
                   documentId: "doc_identity",
                   sourceFileName: "document-generated.pdf",
@@ -1843,7 +1879,6 @@ describe("answerQuestionWithRetrieval", () => {
                 chunkType: "image",
                 score: 0.88,
                 assetUrl: backAssetUrl,
-                assetRef: "asset:r1:result:2",
                 source: {
                   documentId: "doc_identity",
                   sourceFileName: "document-generated.pdf",
@@ -1858,7 +1893,6 @@ describe("answerQuestionWithRetrieval", () => {
                 chunkType: "image",
                 score: 0.7,
                 assetUrl: extraAssetUrl,
-                assetRef: "asset:r1:result:3",
                 source: {
                   documentId: "doc_identity",
                   sourceFileName: "document-generated.pdf",
@@ -1949,6 +1983,7 @@ describe("answerQuestionWithRetrieval", () => {
     expect(answer.artifacts?.map((artifact) => artifact.assetUrl)).toEqual([
       frontAssetUrl,
       backAssetUrl,
+      extraAssetUrl,
     ]);
     expect(answer.artifacts?.map((artifact) => artifact.citation?.source)).toEqual(
       [
@@ -1962,11 +1997,17 @@ describe("answerQuestionWithRetrieval", () => {
           sourceFileName: "商务标文件.pdf",
           sectionPath: "身份证反面",
         },
+        {
+          documentId: "doc_identity",
+          sourceFileName: "商务标文件.pdf",
+          sectionPath: "营业执照",
+        },
       ],
     );
     expect(answer.citations.map((citation) => citation.assetUrl)).toEqual([
       frontAssetUrl,
       backAssetUrl,
+      extraAssetUrl,
     ]);
   });
 
@@ -2065,6 +2106,7 @@ describe("answerQuestionWithRetrieval", () => {
             query: "information hiding",
             targetContent: "text",
           });
+          await tools.retainEvidence?.execute({ picks: [1] });
         }
 
         await tools.finalize?.execute({
@@ -2162,6 +2204,8 @@ describe("answerQuestionWithRetrieval", () => {
             stopReasons: [],
             failureReasons: [],
             decisionTraces: [],
+            retainedPicks: [],
+            pendingRetention: null,
             chunks: [
               {
                 ref: "r1:result:1",
@@ -2171,7 +2215,6 @@ describe("answerQuestionWithRetrieval", () => {
                 chunkType: "image",
                 score: 0.9,
                 assetUrl,
-                assetRef: "asset:r1:result:1",
                 source: {
                   documentId: "doc_diagram",
                   sourceFileName: "generated.pdf",
@@ -2283,6 +2326,8 @@ describe("answerQuestionWithRetrieval", () => {
             stopReasons: [],
             failureReasons: [],
             decisionTraces: [],
+            retainedPicks: [],
+            pendingRetention: null,
             chunks: [
               {
                 ref: "r1:result:1",
@@ -2428,7 +2473,7 @@ describe("answerQuestionWithRetrieval", () => {
     expect(hardenChatAssetUrl).not.toHaveBeenCalled();
   });
 
-  it("returns the agent answer without citations when retrieval has no results", async () => {
+  it("throws when the harness finalizes with empty answer text", async () => {
     const retrieval = {
       query: vi.fn().mockResolvedValue({
         results: [],
@@ -2442,26 +2487,29 @@ describe("answerQuestionWithRetrieval", () => {
     };
     const generateAnswer = vi.fn(async ({ searchSources }) => {
       await searchSources({ query: "Missing fact?" });
-      return makeHarnessRunResult("I couldn't find that in your sources.");
+      const run = makeHarnessRunResult("");
+      return {
+        ...run,
+        manifest: {
+          ...run.manifest,
+          unresolved: ["The requested fact is not present in the sources."],
+        },
+      };
     });
 
-    const answer = await Effect.runPromise(
-      answerQuestionWithRetrieval({
-        question: "Missing fact?",
-        namespace: "notebook-workspace",
-        sources: [makeSource()],
-        excludedSourceIds: [],
-        retrieval,
-        generateAnswer,
-        messages: [],
-      }),
-    );
-
-    expect(answer).toEqual({
-      answer: "I couldn't find that in your sources.",
-      citations: [],
-      artifacts: [],
-    });
+    await expect(
+      Effect.runPromise(
+        answerQuestionWithRetrieval({
+          question: "Missing fact?",
+          namespace: "notebook-workspace",
+          sources: [makeSource()],
+          excludedSourceIds: [],
+          retrieval,
+          generateAnswer,
+          messages: [],
+        }),
+      ),
+    ).rejects.toThrow();
   });
 
   it("lets the agent issue contextual retrieval queries while answering the original question", async () => {
@@ -2701,6 +2749,7 @@ describe("generateAgenticOutputManifest", () => {
           topK: 2,
           purpose: "Find exactly the requested identity-card images.",
         });
+        await tools.retainEvidence?.execute({ picks: [1] });
         await tools.finalize?.execute({
           text: "已找到相关身份证图片，见下方图片。",
           citations: [{ pick: 1 }],
@@ -2796,281 +2845,6 @@ describe("generateAgenticOutputManifest", () => {
     expect(JSON.stringify(capturedGenerateInput)).toContain("tax.pdf / deadline");
   });
 
-  it("lets the agent inspect retrieved image assets before finalizing cited image output", async () => {
-    process.env.AI_GATEWAY_API_KEY = "test_gateway_key";
-    vi.spyOn(ToolLoopAgent.prototype, "generate").mockImplementation(
-      async function mockGenerate(
-        this: ToolLoopAgent,
-      ): ReturnType<ToolLoopAgent["generate"]> {
-        const tools = this.tools as unknown as Record<
-          string,
-          { execute: (input: unknown) => Promise<unknown> }
-        >;
-
-        await tools.declareIntent?.execute({
-          task: "show_media",
-          dependsOnPreviousTurn: false,
-          retrievalNeeded: "yes",
-          targetModalities: ["image"],
-          constraints: { desiredCount: 1, maxCount: 1 },
-          groundingPolicy: "must_use_sources",
-        });
-        await tools.setContextPolicy?.execute({
-          carryHistory: "none",
-          reason: "The current request is self-contained.",
-          activePriorTurnIds: [],
-        });
-        await tools.knowhere_search?.execute({
-          query: "identity card front image",
-          targetContent: "image",
-          topK: 1,
-          purpose: "Find the ID card image to inspect.",
-        });
-        await tools.inspectImage?.execute({
-          refs: ["asset:r1:result:1"],
-          question: "What text is visible on the ID card?",
-        });
-        await tools.finalize?.execute({
-          text: "The inspected image appears to show the requested ID card.",
-          citations: [{ pick: 1 }],
-          memoryCitations: [],
-          artifacts: [
-            {
-              type: "image",
-              ref: "asset:r1:result:1",
-              display: true,
-              reason: "Requested inspected ID card image.",
-            },
-          ],
-          unresolved: [],
-        });
-
-        return {
-          text: "ignored",
-        } as Awaited<ReturnType<ToolLoopAgent["generate"]>>;
-      },
-    );
-    const searchSources = vi.fn().mockResolvedValue({
-      results: [
-        makeRetrievalResult({
-          chunkType: "image",
-          assetUrl: "https://blob.example/images/id-front.png",
-          source: {
-            documentId: "doc_identity",
-            sourceFileName: "generated.pdf",
-            sectionPath: "images/id-front.png",
-          },
-        }),
-      ],
-      evidenceText: "Identity image evidence.",
-      referencedChunks: [],
-      namespace: "notebook-workspace",
-      query: "identity card front image",
-      routerUsed: "workflow_single_step",
-      answerText: null,
-      stopReason: "answer_done",
-      failureReason: null,
-    });
-    const inspectImages = vi.fn().mockResolvedValue({
-      analysis: "The image contains a visible identity card number.",
-      inspected: [
-        {
-          ref: "asset:r1:result:1",
-          label: "generated.pdf / images/id-front.png / image",
-        },
-      ],
-      skipped: [],
-    });
-
-    const result = await generateAgenticOutputManifest({
-      workspaceId: "workspace_1",
-      question: "Inspect and show the ID card image.",
-      messages: [],
-      sources: [
-        makeSource({ title: "identity.pdf", knowhereDocumentId: "doc_identity" }),
-      ],
-      excludedSourceIds: [],
-      searchSources,
-      inspectImages,
-    });
-
-    expect(inspectImages).toHaveBeenCalledWith({
-      question: "What text is visible on the ID card?",
-      assets: [
-        {
-          ref: "asset:r1:result:1",
-          label: "generated.pdf / images/id-front.png / image",
-          assetUrl: "https://blob.example/images/id-front.png",
-          sourcePath: "images/id-front.png",
-          source: {
-            documentId: "doc_identity",
-            sourceFileName: "generated.pdf",
-            sectionPath: "images/id-front.png",
-          },
-        },
-      ],
-    });
-    expect(result.manifest.citations.map((citation) => citation.ref)).toEqual([
-      "r1:result:1",
-    ]);
-    expect(result.manifest.artifacts).toEqual([
-      {
-        type: "image",
-        ref: "asset:r1:result:1",
-        display: true,
-        reason: "Requested inspected ID card image.",
-      },
-    ]);
-    expect(result.trace.toolCalls.map((call) => call.tool)).toContain(
-      "inspectImage",
-    );
-    expect(result.trace.validationErrors).toEqual([]);
-  });
-
-  it("lets the agent inspect retrieved page assets before finalizing an OCR answer", async () => {
-    process.env.AI_GATEWAY_API_KEY = "test_gateway_key";
-    vi.spyOn(ToolLoopAgent.prototype, "generate").mockImplementation(
-      async function mockGenerate(
-        this: ToolLoopAgent,
-      ): ReturnType<ToolLoopAgent["generate"]> {
-        const tools = this.tools as unknown as Record<
-          string,
-          { execute: (input: unknown) => Promise<unknown> }
-        >;
-
-        await tools.declareIntent?.execute({
-          task: "answer",
-          dependsOnPreviousTurn: false,
-          retrievalNeeded: "yes",
-          targetModalities: ["text"],
-          constraints: { citationRequired: true, language: "zh-CN" },
-          groundingPolicy: "must_use_sources",
-        });
-        await tools.setContextPolicy?.execute({
-          carryHistory: "none",
-          reason: "The current request is self-contained.",
-          activePriorTurnIds: [],
-        });
-        await tools.knowhere_search?.execute({
-          query: "进度计划 违约金 承包人",
-          targetContent: "text",
-          topK: 6,
-          purpose: "Find the contract clause and page for the liquidated damages amount.",
-        });
-        await tools.inspectImage?.execute({
-          refs: ["asset:r1:referenced:1"],
-          question:
-            "OCR this clause and identify the liquidated damages amount for unauthorized schedule changes.",
-        });
-        await tools.finalize?.execute({
-          text: "承包人自行修改发包人审批的进度计划，应按每次 5000 元赔偿违约金。",
-          citations: [{ pick: 1 }],
-          memoryCitations: [],
-          artifacts: [],
-          unresolved: [],
-        });
-
-        return {
-          text: "ignored",
-        } as Awaited<ReturnType<ToolLoopAgent["generate"]>>;
-      },
-    );
-    const searchSources = vi.fn().mockResolvedValue({
-      results: [],
-      evidenceText: "Root / （6）现场工期进度管理方面的违约责任",
-      referencedChunks: [
-        {
-          chunkId: "chunk_page_8",
-          documentId: "doc_contract",
-          chunkType: "page",
-          sectionPath: "Root / （6）现场工期进度管理方面的违约责任",
-          filePath: null,
-          jobId: "job_contract",
-          metadata: {
-            pageNums: [8],
-            pageAssets: [
-              {
-                pageNum: 8,
-                artifactRef: "page_citation_assets/page-8.png",
-                assetUrl: "https://blob.example/page-8.png",
-                contentType: "image/png",
-              },
-            ],
-          },
-        },
-      ],
-      namespace: "notebook-workspace",
-      query: "进度计划 违约金 承包人",
-      routerUsed: "workflow_single_step",
-      answerText: null,
-      stopReason: "answer_done",
-      failureReason: null,
-    });
-    const inspectImages = vi.fn().mockResolvedValue({
-      analysis: "The clause states 5000 yuan per occurrence.",
-      inspected: [
-        {
-          ref: "asset:r1:referenced:1",
-          label:
-            "Root / （6）现场工期进度管理方面的违约责任 / page_citation_assets/page-8.png / page",
-        },
-      ],
-      skipped: [],
-    });
-
-    const result = await generateAgenticOutputManifest({
-      workspaceId: "workspace_1",
-      question: "承包人自行修改发包人审批的进度时需要赔偿多少违约金？",
-      messages: [],
-      sources: [
-        makeSource({
-          title: "投标书.pdf",
-          knowhereDocumentId: "doc_contract",
-        }),
-      ],
-      excludedSourceIds: [],
-      searchSources,
-      inspectImages,
-    });
-
-    expect(searchSources).toHaveBeenCalledWith({
-      query: "进度计划 违约金 承包人",
-      targetContent: "text",
-      purpose: "Find the contract clause and page for the liquidated damages amount.",
-      topK: 6,
-      signalPaths: undefined,
-      filterMode: undefined,
-      threshold: undefined,
-    });
-    expect(inspectImages).toHaveBeenCalledWith({
-      question:
-        "OCR this clause and identify the liquidated damages amount for unauthorized schedule changes.",
-      assets: [
-        {
-          ref: "asset:r1:referenced:1",
-          label:
-            "Root / （6）现场工期进度管理方面的违约责任 / page_citation_assets/page-8.png / page",
-          assetUrl: "https://blob.example/page-8.png",
-          sourcePath: "page_citation_assets/page-8.png",
-          revisionKey: "job_contract",
-          source: {
-            documentId: "doc_contract",
-            sourceFileName: null,
-            sectionPath: "Root / （6）现场工期进度管理方面的违约责任",
-          },
-        },
-      ],
-    });
-    expect(result.manifest.text).toContain("5000 元");
-    expect(result.manifest.citations.map((citation) => citation.ref)).toEqual([
-      "r1:referenced:1",
-    ]);
-    expect(result.trace.toolCalls.map((call) => call.tool)).toContain(
-      "inspectImage",
-    );
-    expect(result.trace.validationErrors).toEqual([]);
-  });
-
   it("keeps an over-budget manifest after the first generation", async () => {
     process.env.AI_GATEWAY_API_KEY = "test_gateway_key";
     let generateCallCount = 0;
@@ -3104,6 +2878,7 @@ describe("generateAgenticOutputManifest", () => {
             topK: 3,
             purpose: "Find requested identity images.",
           });
+          await tools.retainEvidence?.execute({ picks: [1, 2, 3] });
           await tools.finalize?.execute({
             text: "见下方图片。",
             citations: [{ pick: 1 }],
@@ -3187,6 +2962,7 @@ describe("parseChatRequestBody", () => {
         message: "  What changed?  ",
         threadId: "thread_1",
         excludedSourceIds: ["source_1", 7, "source_2"],
+        folderId: " folder_1 ",
       }),
     ).toEqual({
       ok: true,
@@ -3195,6 +2971,7 @@ describe("parseChatRequestBody", () => {
         threadId: "thread_1",
         useAgentic: true,
         excludedSourceIds: ["source_1", "source_2"],
+        folderId: "folder_1",
       },
     });
   });
@@ -3285,6 +3062,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-06T00:00:00Z"),
     updatedAt: new Date("2026-05-06T00:00:00Z"),
     deletedAt: null,
@@ -3310,6 +3088,8 @@ function makeHarnessRunResult(text: string): HarnessRunResult {
         stopReasons: [],
         failureReasons: [],
         decisionTraces: [],
+        retainedPicks: [],
+        pendingRetention: null,
       },
       finalized: true,
       priorTurnReads: [],
@@ -3362,6 +3142,8 @@ function makeHarnessRunResultWithLedger(
         stopReasons: [],
         failureReasons: [],
         decisionTraces: [],
+        retainedPicks: [],
+        pendingRetention: null,
       },
     },
   };
diff --git a/src/domains/chat/index.ts b/src/domains/chat/index.ts
index 9f73b20..efd0d79 100644
--- a/src/domains/chat/index.ts
+++ b/src/domains/chat/index.ts
@@ -7,6 +7,7 @@ import type {
 
 import { logger } from "@/lib/logger"
 import { getCanonicalImageAssetKey } from "@/agent-harness/image-asset-identity"
+import { hasReferencedChunkEvidence } from "@/agent-harness/referenced-chunks"
 import type {
   ChatArtifactView,
   ChatCitationView,
@@ -32,7 +33,9 @@ import type {
   AnswerQuestionResult,
 } from "./contracts"
 import {
+  emptyFolderSearchMessage,
   getRetrievalDocumentScope,
+  isEmptyFolderScope,
   normalizeRetrievalQuery,
 } from "./retrieval"
 import {
@@ -56,7 +59,6 @@ const MAX_CITATION_RESULTS = 20
 const KNOWHERE_RESPONSE_TEXT_LOG_LIMIT = 200
 const KNOWHERE_CHUNK_LOG_LIMIT = 100
 const KNOWHERE_RESPONSE_LOG_ITEM_LIMIT = 20
-const NO_RESULTS_ANSWER = "I couldn't find that in your sources."
 const RAW_URL_PATTERN = /https?:\/\/[^\s)\]}>"']+/g
 const REDACTED_MEDIA_URL = "[media asset URL hidden]"
 const RETRIEVAL_TARGET_CONTENT_DATA_TYPES: Readonly<
@@ -152,6 +154,9 @@ export const answerQuestionWithRetrieval = (
     const searchSources = async (
       queryInput: AgenticRetrievalQuery,
     ): Promise<AgenticRetrievalResponse> => {
+      if (isEmptyFolderScope(input.folderScopeSourceIds, input.sources)) {
+        throw new Error(emptyFolderSearchMessage)
+      }
       const startedAt = Date.now()
       const retrievalPlan = toAgenticRetrievalPlan(queryInput)
       const namespaces = getRetrievalNamespaces(input)
@@ -245,12 +250,18 @@ export const answerQuestionWithRetrieval = (
         messages: input.messages,
         sources: input.sources,
         excludedSourceIds: input.excludedSourceIds,
+        ...(input.folderScopeSourceIds !== undefined
+          ? { folderScopeSourceIds: input.folderScopeSourceIds }
+          : {}),
         searchSources,
         knowhereTools: notebookKnowhereTools.createRuntime({
           searchSources,
           sources: input.sources,
         }),
-        ...(input.inspectImages ? { inspectImages: input.inspectImages } : {}),
+        ...(input.resolveConnectedAssets
+          ? { resolveConnectedAssets: input.resolveConnectedAssets }
+          : {}),
+        ...(input.readTableHtml ? { readTableHtml: input.readTableHtml } : {}),
       }),
     )
 
@@ -261,6 +272,20 @@ export const answerQuestionWithRetrieval = (
       finalized: generatedAnswer.trace.finalized,
     })
 
+    if (
+      generatedAnswer.manifest.text.trim().length === 0 &&
+      !hasDisplayedManifestArtifacts(generatedAnswer)
+    ) {
+      return yield* Effect.die(
+        new Error(
+          "Agent harness finalized with empty answer text and no displayed " +
+            "artifact. The composed answer context always tells the model " +
+            "when a search found nothing, so this indicates a bug, not a " +
+            "legitimate no-answer case.",
+        ),
+      )
+    }
+
     const rawResults = yield* Effect.tryPromise(() =>
       hydrateMissingCitationPageMetadata({
         results: selectCitationRawResults({
@@ -270,17 +295,6 @@ export const answerQuestionWithRetrieval = (
         knowledge: input.knowledge,
       }),
     )
-    if (
-      rawResults.length === 0 &&
-      generatedAnswer.manifest.text.trim().length === 0 &&
-      !hasDisplayedManifestArtifacts(generatedAnswer)
-    ) {
-      return {
-        answer: NO_RESULTS_ANSWER,
-        citations: [] as ChatCitationView[],
-        artifacts: [] as ChatArtifactView[],
-      }
-    }
 
     const enrichedResults = yield* Effect.tryPromise(() =>
       enrichRetrievalResultsWithAssetUrls({
@@ -338,21 +352,13 @@ function toChatArtifactViewsFromHarness(
       asset,
     ]),
   )
-  const chunksByRef = new Map(
-    result.trace.ledger.chunks.map((chunk): readonly [string, EvidenceChunk] => [
-      chunk.ref,
-      chunk,
-    ]),
-  )
   const highlightsByRef = new Map(
     (result.trace.imageHighlights ?? []).map(
       (page) => [page.ref, page.regions] as const,
     ),
   )
 
-  const displayLimit = getHarnessArtifactDisplayLimit(result)
   const artifacts: ChatArtifactView[] = []
-  let displayedArtifactCount = 0
 
   for (const artifact of result.manifest.artifacts) {
     const artifactView =
@@ -361,23 +367,11 @@ function toChatArtifactViewsFromHarness(
         : resolveHarnessArtifactView({
             artifact,
             assetsByRef,
-            chunksByRef,
             highlightsByRef,
             sources,
           })
     if (!artifactView) continue
-
-    const isDisplayed = artifactView.display !== false
-    if (
-      isDisplayed &&
-      typeof displayLimit === "number" &&
-      displayedArtifactCount >= displayLimit
-    ) {
-      continue
-    }
-
     artifacts.push(artifactView)
-    if (isDisplayed) displayedArtifactCount += 1
   }
 
   return artifacts.length > 0 ? artifacts : undefined
@@ -398,45 +392,20 @@ function toDerivedTableArtifactView(
   }
 }
 
-function getHarnessArtifactDisplayLimit(result: HarnessRunResult): number | null {
-  const constraints = result.trace.intent?.constraints
-  const limits = [constraints?.desiredCount, constraints?.maxCount].filter(
-    (value): value is number =>
-      typeof value === "number" && Number.isSafeInteger(value) && value > 0,
-  )
-  return limits.length > 0 ? Math.min(...limits) : null
-}
-
 function resolveHarnessArtifactView(input: {
   readonly artifact: OutputArtifact
   readonly assetsByRef: ReadonlyMap<string, EvidenceAsset>
-  readonly chunksByRef: ReadonlyMap<string, EvidenceChunk>
   readonly highlightsByRef: ReadonlyMap<string, readonly ChatImageHighlightBox[]>
   readonly sources: readonly AnswerQuestionInput["sources"][number][]
 }): ChatArtifactView | null {
   const asset = input.assetsByRef.get(input.artifact.ref)
-  if (asset) {
-    return toChatArtifactView({
-      artifact: input.artifact,
-      asset,
-      highlightRegions: input.highlightsByRef.get(asset.ref),
-      sources: input.sources,
-    })
-  }
-
-  const chunk = input.chunksByRef.get(input.artifact.ref)
-  const chunkAssetRef = chunk?.assetRef
-  const chunkAsset = chunkAssetRef ? input.assetsByRef.get(chunkAssetRef) : null
-  return chunkAsset
-    ? toChatArtifactView({
-        artifact: input.artifact,
-        asset: chunkAsset,
-        highlightRegions:
-          input.highlightsByRef.get(chunkAsset.ref) ??
-          input.highlightsByRef.get(input.artifact.ref),
-        sources: input.sources,
-      })
-    : null
+  if (!asset) return null
+  return toChatArtifactView({
+    artifact: input.artifact,
+    asset,
+    highlightRegions: input.highlightsByRef.get(asset.ref),
+    sources: input.sources,
+  })
 }
 
 function toChatArtifactView(input: {
@@ -740,6 +709,7 @@ async function queryRetrievalNamespace(input: {
     useAgentic: input.answerInput.useAgentic ?? true,
     sources: input.answerInput.sources,
     excludedSourceIds: input.answerInput.excludedSourceIds,
+    folderScopeSourceIds: input.answerInput.folderScopeSourceIds,
   })
   logger.info("chat-agent: searchSources start", {
     namespace: input.namespace,
@@ -752,6 +722,7 @@ async function queryRetrievalNamespace(input: {
     threshold: retrievalQueryParams.threshold ?? null,
     targetContent: input.retrievalPlan.targetContent,
     purpose: input.retrievalPlan.purpose,
+    gapReason: input.retrievalPlan.gapReason,
     mode: input.mode,
   })
 
@@ -862,10 +833,9 @@ function mergeRetrievalResponses(
     .slice(0, evidenceLimits.resultCount)
   const referencedChunks = responses
     .flatMap((response) =>
-      response.referencedChunks.slice(
-        0,
-        evidenceLimits.referencedChunkCountPerResponse,
-      ),
+      response.referencedChunks
+        .filter(hasReferencedChunkEvidence)
+        .slice(0, evidenceLimits.referencedChunkCountPerResponse),
     )
     .slice(0, evidenceLimits.referencedChunkCount)
   const evidenceTexts = responses
@@ -932,7 +902,7 @@ function getRetrievalStatusResponses(
 function hasRetrievalEvidence(response: RetrievalQueryResponse): boolean {
   return (
     response.results.length > 0 ||
-    response.referencedChunks.length > 0 ||
+    response.referencedChunks.some(hasReferencedChunkEvidence) ||
     Boolean(response.evidenceText?.trim()) ||
     Boolean(response.answerText?.trim())
   )
@@ -958,6 +928,7 @@ function buildRetrievalQueryParams(input: {
   readonly useAgentic: boolean
   readonly sources: AnswerQuestionInput["sources"]
   readonly excludedSourceIds: readonly string[]
+  readonly folderScopeSourceIds?: readonly string[]
 }): RetrievalQueryParams {
   const query = normalizeRetrievalQuery(
     input.input.query,
@@ -977,7 +948,12 @@ function buildRetrievalQueryParams(input: {
     ...(typeof input.input.threshold === "number"
       ? { threshold: input.input.threshold }
       : {}),
-    ...getRetrievalDocumentScope(input.sources, input.excludedSourceIds, input.input),
+    ...getRetrievalDocumentScope(
+      input.sources,
+      input.excludedSourceIds,
+      input.input,
+      input.folderScopeSourceIds,
+    ),
   }
 }
 
@@ -987,6 +963,7 @@ function toAgenticRetrievalPlan(
   return {
     targetContent: normalizeRetrievalTargetContent(input.targetContent),
     purpose: normalizeRetrievalPurpose(input.purpose),
+    gapReason: normalizeRetrievalGapReason(input.gapReason),
   }
 }
 
@@ -996,6 +973,11 @@ function normalizeRetrievalPurpose(value: string | undefined): string | null {
   return normalized.slice(0, 240)
 }
 
+function normalizeRetrievalGapReason(value: string | undefined): string | null {
+  const trimmed = value?.trim()
+  return trimmed ? trimmed : null
+}
+
 function normalizeRetrievalDataType(
   targetContent: AgenticRetrievalTargetContent | undefined,
 ): RetrievalDataType {
@@ -1110,22 +1092,24 @@ function getHighlightRegionsForChunk(
   if (!imageHighlights || imageHighlights.length === 0) return undefined
 
   const candidateRefs = new Set([chunk.ref])
-  const assetRef = resolveCitationImageAssetRef(
+  const assetRefs = resolveCitationImageAssetRefs(
     chunk,
     chunksByRef,
     assetsByRef,
   )
-  if (assetRef) candidateRefs.add(assetRef)
-  const canonicalAssetKey = assetRef
-    ? getCanonicalCitationAssetKey(assetRef, chunksByRef, assetsByRef)
-    : null
+  for (const assetRef of assetRefs) candidateRefs.add(assetRef)
+  const canonicalAssetKeys = new Set(
+    assetRefs.map((assetRef) =>
+      getCanonicalCitationAssetKey(assetRef, chunksByRef, assetsByRef),
+    ),
+  )
 
   for (const page of imageHighlights) {
     const isDirectMatch = candidateRefs.has(page.ref)
     const isCanonicalMatch =
-      canonicalAssetKey !== null &&
-      getCanonicalCitationAssetKey(page.ref, chunksByRef, assetsByRef) ===
-        canonicalAssetKey
+      canonicalAssetKeys.has(
+        getCanonicalCitationAssetKey(page.ref, chunksByRef, assetsByRef),
+      )
     if ((!isDirectMatch && !isCanonicalMatch) || page.regions.length === 0) {
       continue
     }
@@ -1135,25 +1119,32 @@ function getHighlightRegionsForChunk(
   return undefined
 }
 
-function resolveCitationImageAssetRef(
+function resolveCitationImageAssetRefs(
   chunk: EvidenceChunk,
   chunksByRef: ReadonlyMap<string, EvidenceChunk>,
   assetsByRef: ReadonlyMap<string, EvidenceAsset>,
-): string | null {
-  if (chunk.assetRef && assetsByRef.get(chunk.assetRef)?.type === "image") {
-    return chunk.assetRef
-  }
-  if (!chunk.chunkId) return null
-
-  const sibling = Array.from(chunksByRef.values()).find(
-    (candidate) =>
-      candidate.ref !== chunk.ref &&
-      candidate.chunkId === chunk.chunkId &&
-      candidate.source.documentId === chunk.source.documentId &&
-      candidate.assetRef !== undefined &&
-      assetsByRef.get(candidate.assetRef)?.type === "image",
+): string[] {
+  const directRefs = Array.from(assetsByRef.values())
+    .filter((asset) => asset.chunkRef === chunk.ref && asset.type === "image")
+    .map((asset) => asset.ref)
+  if (directRefs.length > 0) return directRefs
+  if (!chunk.chunkId) return []
+
+  const siblingChunkRefs = new Set(
+    Array.from(chunksByRef.values())
+      .filter(
+        (candidate) =>
+          candidate.ref !== chunk.ref &&
+          candidate.chunkId === chunk.chunkId &&
+          candidate.source.documentId === chunk.source.documentId,
+      )
+      .map((candidate) => candidate.ref),
   )
-  return sibling?.assetRef ?? null
+  return Array.from(assetsByRef.values())
+    .filter(
+      (asset) => siblingChunkRefs.has(asset.chunkRef) && asset.type === "image",
+    )
+    .map((asset) => asset.ref)
 }
 
 function getCanonicalCitationAssetKey(
@@ -1184,13 +1175,9 @@ function mapDisplayedManifestArtifactsToResults(
 
   const results: RetrievalResult[] = []
   const seenKeys = new Set<string>()
-  const displayLimit = getHarnessArtifactDisplayLimit(result)
 
   for (const artifact of result.manifest.artifacts) {
     if (!artifact.display) continue
-    if (typeof displayLimit === "number" && results.length >= displayLimit) {
-      break
-    }
 
     if (artifact.type === "derived_table") {
       for (const sourceRef of artifact.sourceRefs) {
diff --git a/src/domains/chat/knowhere-tools.test.ts b/src/domains/chat/knowhere-tools.test.ts
new file mode 100644
index 0000000..32b2413
--- /dev/null
+++ b/src/domains/chat/knowhere-tools.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from "vitest"
+import type { RetrievalQueryResponse } from "@ontos-ai/knowhere-sdk"
+
+import { notebookKnowhereTools } from "./knowhere-tools"
+
+describe("notebookKnowhereTools", () => {
+  it("does not authorize document scope from an ID-only reference", async () => {
+    const searchSources = vi.fn().mockResolvedValue(
+      makeResponse([
+        {
+          documentId: "doc_provenance",
+          chunkId: "chunk_provenance",
+          pageNums: [],
+        },
+      ]),
+    )
+    const runtime = notebookKnowhereTools.createRuntime({
+      searchSources,
+      sources: [],
+    })
+
+    await runtime.search({ query: "first" })
+
+    await expect(
+      runtime.search({
+        query: "second",
+        includeDocumentIds: ["doc_provenance"],
+      }),
+    ).rejects.toThrow("unverified ID")
+  })
+
+  it("authorizes document scope from a structured referenced asset", async () => {
+    const searchSources = vi.fn().mockResolvedValue(
+      makeResponse([
+        {
+          documentId: "doc_asset",
+          chunkId: "chunk_asset",
+          chunkType: "image",
+          filePath: "images/asset.png",
+        },
+      ]),
+    )
+    const runtime = notebookKnowhereTools.createRuntime({
+      searchSources,
+      sources: [],
+    })
+
+    await runtime.search({ query: "first" })
+    await runtime.search({ query: "second", includeDocumentIds: ["doc_asset"] })
+
+    expect(searchSources).toHaveBeenCalledTimes(2)
+  })
+})
+
+function makeResponse(
+  referencedChunks: readonly Record<string, unknown>[],
+): RetrievalQueryResponse {
+  return {
+    namespace: "notebook",
+    query: "query",
+    routerUsed: "agent_explore",
+    answerText: null,
+    evidenceText: null,
+    results: [],
+    referencedChunks:
+      referencedChunks as unknown as RetrievalQueryResponse["referencedChunks"],
+  }
+}
diff --git a/src/domains/chat/knowhere-tools.ts b/src/domains/chat/knowhere-tools.ts
index 49bdbb9..032b599 100644
--- a/src/domains/chat/knowhere-tools.ts
+++ b/src/domains/chat/knowhere-tools.ts
@@ -1,4 +1,5 @@
 import type { KnowhereToolRuntime } from "@/agent-harness"
+import { hasReferencedChunkEvidence } from "@/agent-harness/referenced-chunks"
 import type { SearchSources } from "./contracts"
 import type { Source } from "@/infrastructure/db/schema"
 
@@ -22,7 +23,7 @@ export const notebookKnowhereTools = {
         ]
         if (requestedIds.some((id) => !knownDocumentIds.has(id))) {
           throw new Error(
-            "Document scope contains an unverified ID. Use document IDs from source context or prior search results; otherwise keep the document requirement in query so Knowhere can locate it.",
+            "Document scope contains an unverified ID. Use document IDs from prior search results; otherwise keep the document requirement in query so Knowhere can locate it.",
           )
         }
         const response = await input.searchSources(request)
@@ -30,7 +31,9 @@ export const notebookKnowhereTools = {
           if (result.source.documentId) knownDocumentIds.add(result.source.documentId)
         }
         for (const ref of response.referencedChunks) {
-          if (ref.documentId) knownDocumentIds.add(ref.documentId)
+          if (hasReferencedChunkEvidence(ref) && ref.documentId) {
+            knownDocumentIds.add(ref.documentId)
+          }
         }
         return response
       },
diff --git a/src/domains/chat/media-asset-hardening.test.ts b/src/domains/chat/media-asset-hardening.test.ts
index 2660cfa..462dde0 100644
--- a/src/domains/chat/media-asset-hardening.test.ts
+++ b/src/domains/chat/media-asset-hardening.test.ts
@@ -209,6 +209,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-06T00:00:00Z"),
     updatedAt: new Date("2026-05-06T00:00:00Z"),
     deletedAt: null,
diff --git a/src/domains/chat/media-assets.test.ts b/src/domains/chat/media-assets.test.ts
index 7f15318..46bfd3c 100644
--- a/src/domains/chat/media-assets.test.ts
+++ b/src/domains/chat/media-assets.test.ts
@@ -320,6 +320,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-06-04T00:00:00Z"),
     updatedAt: new Date("2026-06-04T00:00:00Z"),
     deletedAt: null,
diff --git a/src/domains/chat/page-citation-assets.test.ts b/src/domains/chat/page-citation-assets.test.ts
index 65be327..9db56e2 100644
--- a/src/domains/chat/page-citation-assets.test.ts
+++ b/src/domains/chat/page-citation-assets.test.ts
@@ -266,6 +266,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-07-03T00:00:00.000Z"),
     updatedAt: new Date("2026-07-03T00:00:00.000Z"),
     deletedAt: null,
diff --git a/src/domains/chat/prompt.ts b/src/domains/chat/prompt.ts
index 4d24c99..fa2f733 100644
--- a/src/domains/chat/prompt.ts
+++ b/src/domains/chat/prompt.ts
@@ -9,19 +9,23 @@ import {
   type AgentTurn,
   type AgentTurnInput,
   type HarnessRunResult,
-  type InspectImages,
   type KnowhereToolRuntime,
+  type ReadTableHtml,
+  type ResolveConnectedAssets,
 } from "@/agent-harness"
 import type {
   ChatHistoryMessage,
   SearchSources,
 } from "./contracts"
+import {
+  emptyFolderSearchMessage,
+  isEmptyFolderScope,
+} from "./retrieval"
 import { mementoMemoryTools } from "@/integrations/memento/memory-tools"
 import { notebookKnowhereTools } from "./knowhere-tools"
 
 const RECENT_CONTEXT_MESSAGE_LIMIT = 8
 const CONTEXT_CONTENT_CHAR_LIMIT = 900
-const SOURCE_CONTEXT_LIMIT = 12
 
 type GenerateAgenticOutputManifestInput = {
   workspaceId: string
@@ -31,7 +35,9 @@ type GenerateAgenticOutputManifestInput = {
   excludedSourceIds: readonly string[]
   searchSources: SearchSources
   knowhereTools?: KnowhereToolRuntime
-  inspectImages?: InspectImages
+  resolveConnectedAssets?: ResolveConnectedAssets
+  readTableHtml?: ReadTableHtml
+  folderScopeSourceIds?: readonly string[]
 }
 
 export const generateAgenticOutputManifestEffect = (
@@ -69,7 +75,10 @@ export const generateAgenticOutputManifestEffect = (
         memoryTools: mementoMemoryTools.createRuntime({
           workspaceId: input.workspaceId,
         }),
-        ...(input.inspectImages ? { inspectImages: input.inspectImages } : {}),
+        ...(input.resolveConnectedAssets
+          ? { resolveConnectedAssets: input.resolveConnectedAssets }
+          : {}),
+        ...(input.readTableHtml ? { readTableHtml: input.readTableHtml } : {}),
       }),
     )
 
@@ -100,7 +109,9 @@ function buildNotebookHarnessTurn(
     surface: "notebook_chat",
     userText: input.question,
     recentTurns: buildNotebookHarnessRecentTurns(input.messages),
-    sourceContext: formatSourceContext(input.sources, input.excludedSourceIds),
+    ...(isEmptyFolderScope(input.folderScopeSourceIds, input.sources)
+      ? { localContext: emptyFolderSearchMessage }
+      : {}),
     outputCapabilities: {
       text: true,
       image: true,
@@ -130,24 +141,6 @@ function getCitationLabels(
     .filter((label) => label.length > 0)
 }
 
-function formatSourceContext(
-  sources: readonly Source[],
-  excludedSourceIds: readonly string[],
-): string {
-  const excludedSourceIdsSet = new Set(excludedSourceIds)
-  const lines = sources
-    .filter((source): boolean => !excludedSourceIdsSet.has(source.id))
-    .slice(0, SOURCE_CONTEXT_LIMIT)
-    .map((source): string => {
-      const documentId = source.knowhereDocumentId
-        ? `documentId=${source.knowhereDocumentId}`
-        : "documentId=unknown"
-      return `- ${source.title} (${documentId})`
-    })
-
-  return lines.length > 0 ? lines.join("\n") : "- No searchable sources."
-}
-
 function formatCitationContext(
   citations: readonly ChatCitationView[],
 ): string {
diff --git a/src/domains/chat/request.ts b/src/domains/chat/request.ts
index 3e56f06..bb8debe 100644
--- a/src/domains/chat/request.ts
+++ b/src/domains/chat/request.ts
@@ -5,6 +5,7 @@ export type ParsedChatRequest = {
   threadId?: string
   useAgentic: boolean
   excludedSourceIds: string[]
+  folderId?: string
 }
 
 export type ParseChatRequestResult =
@@ -16,6 +17,7 @@ const ChatRequestBody = Schema.Struct({
   threadId: Schema.optional(Schema.String),
   useAgentic: Schema.optional(Schema.Boolean),
   excludedSourceIds: Schema.optional(Schema.Array(Schema.Unknown)),
+  folderId: Schema.optional(Schema.String),
 })
 
 export function parseChatRequestBody(body: unknown): ParseChatRequestResult {
@@ -37,6 +39,7 @@ export function parseChatRequestBody(body: unknown): ParseChatRequestResult {
       const excludedSourceIds = (parsed.excludedSourceIds ?? []).filter(
         (id): id is string => typeof id === "string" && id.trim().length > 0,
       )
+      const folderId = parsed.folderId?.trim()
       return {
         ok: true,
         value: {
@@ -47,6 +50,7 @@ export function parseChatRequestBody(body: unknown): ParseChatRequestResult {
               : undefined,
           useAgentic: parsed.useAgentic ?? true,
           excludedSourceIds,
+          ...(folderId ? { folderId } : {}),
         },
       }
     },
diff --git a/src/domains/chat/retrieval.test.ts b/src/domains/chat/retrieval.test.ts
new file mode 100644
index 0000000..edb881d
--- /dev/null
+++ b/src/domains/chat/retrieval.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest"
+
+import type { Source } from "@/infrastructure/db/schema"
+import { getRetrievalDocumentScope, isEmptyFolderScope } from "./retrieval"
+
+describe("getRetrievalDocumentScope", () => {
+  it("does not add includeDocumentIds at the workspace root", () => {
+    expect(
+      getRetrievalDocumentScope(
+        [makeSource({ id: "source_1", knowhereDocumentId: "doc_1" })],
+        [],
+        {},
+      ),
+    ).toEqual({})
+  })
+
+  it("converts a folder scope into includeDocumentIds", () => {
+    expect(
+      getRetrievalDocumentScope(
+        [
+          makeSource({ id: "source_1", knowhereDocumentId: "doc_1" }),
+          makeSource({ id: "source_2", knowhereDocumentId: "doc_2" }),
+        ],
+        [],
+        {},
+        ["source_1"],
+      ),
+    ).toEqual({
+      includeDocumentIds: ["doc_1"],
+    })
+  })
+
+  it("keeps row exclusions on top of a folder include list", () => {
+    expect(
+      getRetrievalDocumentScope(
+        [
+          makeSource({ id: "source_1", knowhereDocumentId: "doc_1" }),
+          makeSource({ id: "source_2", knowhereDocumentId: "doc_2" }),
+        ],
+        ["source_2"],
+        {},
+        ["source_1", "source_2"],
+      ),
+    ).toEqual({
+      includeDocumentIds: ["doc_1", "doc_2"],
+      excludeDocumentIds: ["doc_2"],
+    })
+  })
+
+  it("treats a missing or empty folder as an empty search scope", () => {
+    expect(isEmptyFolderScope(undefined, [makeSource()])).toBe(false)
+    expect(isEmptyFolderScope([], [makeSource()])).toBe(true)
+    expect(isEmptyFolderScope(["source_missing"], [makeSource()])).toBe(true)
+    expect(isEmptyFolderScope(["source_1"], [makeSource()])).toBe(false)
+    expect(
+      getRetrievalDocumentScope([makeSource()], [], {}, []),
+    ).toEqual({
+      includeDocumentIds: [],
+    })
+  })
+})
+
+function makeSource(overrides: Partial<Source> = {}): Source {
+  return {
+    id: "source_1",
+    workspaceId: "workspace_1",
+    title: "notes.pdf",
+    mimeType: "application/pdf",
+    sizeBytes: 1,
+    status: "ready",
+    failureReason: null,
+    failureStage: null,
+    knowhereJobId: "job_1",
+    knowhereDocumentId: "doc_1",
+    stagedBlobPathname: null,
+    stagedBlobUrl: null,
+    originalBlobPathname: null,
+    originalBlobUrl: null,
+    demoKey: null,
+    chunkCount: null,
+    folderId: null,
+    createdAt: new Date("2026-05-06T00:00:00Z"),
+    updatedAt: new Date("2026-05-06T00:00:00Z"),
+    deletedAt: null,
+    ...overrides,
+  }
+}
diff --git a/src/domains/chat/retrieval.ts b/src/domains/chat/retrieval.ts
index e539113..d166baa 100644
--- a/src/domains/chat/retrieval.ts
+++ b/src/domains/chat/retrieval.ts
@@ -21,10 +21,25 @@ export function normalizeRetrievalQuery(value: string, fallback: string): string
   return normalized.slice(0, RETRIEVAL_QUERY_CHAR_LIMIT)
 }
 
+export const emptyFolderSearchMessage =
+  "The current folder has no documents. Do not call knowhere_search."
+
+export function isEmptyFolderScope(
+  folderScopeSourceIds: readonly string[] | undefined,
+  sources: readonly Source[],
+): boolean {
+  if (folderScopeSourceIds === undefined) return false
+  const scoped = new Set(folderScopeSourceIds)
+  return !sources.some(
+    (source) => scoped.has(source.id) && Boolean(source.knowhereDocumentId),
+  )
+}
+
 export function getRetrievalDocumentScope(
   sources: readonly Source[],
   excludedSourceIds: readonly string[],
   request: Pick<KnowhereSearchRequest, "includeDocumentIds" | "excludeDocumentIds">,
+  folderScopeSourceIds?: readonly string[],
 ): Pick<KnowhereSearchRequest, "includeDocumentIds" | "excludeDocumentIds"> {
   const excluded = new Set(excludedSourceIds)
   const localDocumentIds = sources
@@ -41,15 +56,38 @@ export function getRetrievalDocumentScope(
       ...(request.excludeDocumentIds ?? []),
     ]),
   )
+  const includeDocumentIds = getFolderScopeDocumentIds(
+    sources,
+    folderScopeSourceIds,
+  )
 
   return {
-    ...(request.includeDocumentIds !== undefined
-      ? { includeDocumentIds: [...new Set(request.includeDocumentIds)] }
-      : {}),
+    ...(includeDocumentIds !== undefined
+      ? { includeDocumentIds }
+      : request.includeDocumentIds !== undefined
+        ? { includeDocumentIds: [...new Set(request.includeDocumentIds)] }
+        : {}),
     ...(documentIds.length > 0 ? { excludeDocumentIds: documentIds } : {}),
   }
 }
 
+function getFolderScopeDocumentIds(
+  sources: readonly Source[],
+  folderScopeSourceIds: readonly string[] | undefined,
+): string[] | undefined {
+  if (folderScopeSourceIds === undefined) return undefined
+
+  const scoped = new Set(folderScopeSourceIds)
+  return [
+    ...new Set(
+      sources
+        .filter((source) => scoped.has(source.id))
+        .map((source) => source.knowhereDocumentId)
+        .filter((documentId): documentId is string => Boolean(documentId)),
+    ),
+  ]
+}
+
 function stripWrappingQuotes(value: string): string {
   if (
     (value.startsWith('"') && value.endsWith('"')) ||
diff --git a/src/domains/chat/route-answer.ts b/src/domains/chat/route-answer.ts
index 34cc4d7..5f76eb9 100644
--- a/src/domains/chat/route-answer.ts
+++ b/src/domains/chat/route-answer.ts
@@ -1,28 +1,20 @@
 import { Cause, Effect, Either, Option } from "effect"
 
 import { parseChatRequestBody } from "@/domains/chat"
-import type {
-  ImageInspectionAsset,
-  ImageInspectionRequest,
-  ImageInspectionResponse,
-  ImageInspectionSkippedAsset,
-  InspectImages,
-} from "@/agent-harness"
 import { commitAgenticChatTurn } from "@/domains/chat/commit-turn"
-import { normalizeImageInspectionHighlights } from "@/agent-harness/image-highlights"
-import { generateImageInspectionModelResult } from "@/domains/chat/image-inspection-model"
 import { hardenChatMediaAssetUrls } from "@/domains/chat/media-asset-hardening"
 import {
   type ChatTurnError,
   type ChatTurnValue,
 } from "@/domains/chat/service"
 import { chatTurnPersistence } from "@/domains/chat/chat-turn-persistence"
+import { createConnectedAssetResolver } from "@/domains/chat/connected-assets"
+import { folderWorkflowRuntime } from "@/domains/folders/workflow-runtime"
 import { startBackgroundReconciliation } from "@/domains/sources/background-reconcile"
 import { BlobParsedDocumentStorage } from "@/domains/sources/parsed-document-blob-storage"
 import { sourceWorkflowRuntime } from "@/domains/sources/workflow-runtime"
 import { notebookRequestContext } from "@/domains/workspace/request-context"
 import type { Source } from "@/infrastructure/db/schema"
-import { CHAT_MODEL } from "@/lib/ai"
 import type { HardenChatAssetUrl } from "./media-assets"
 import { isAuthError } from "@/integrations/dashboard/api-key-service"
 import { makeKnowhereClientWithParsedStorage } from "@/integrations/knowhere"
@@ -33,23 +25,6 @@ import { routeResult, type RouteResult } from "@/lib/route-result"
 
 type RouteResponse<TBody> = RouteResult<TBody>
 
-const VISION_MODEL = process.env.VISION_MODEL ?? CHAT_MODEL
-const IMAGE_INSPECTION_URL_REPLACEMENT = "[image URL hidden]"
-const SUPPORTED_IMAGE_CONTENT_TYPES: Readonly<Record<string, string>> = {
-  ".jpeg": "image/jpeg",
-  ".jpg": "image/jpeg",
-  ".png": "image/png",
-  ".webp": "image/webp",
-} as const
-
-type HardenImageInspectionAsset = (input: {
-  readonly documentId: string
-  readonly revisionKey: string
-  readonly sourcePath: string
-  readonly assetUrl?: string | null
-  readonly contentType?: string | null
-}) => Promise<string | null>
-
 type MessageBody = {
   readonly message: string
 }
@@ -115,24 +90,11 @@ const answerChatEffect = (input: AnswerChatInput) =>
         assetUrl,
         contentType,
       })
-    const hardenImageInspectionAsset: HardenImageInspectionAsset = (asset) =>
-      hardenChatAssetByDocument({
-        workspaceId: workspace.id,
-        parsedStorage,
-        documentId: asset.documentId,
-        revisionKey: asset.revisionKey,
-        sourcePath: asset.sourcePath,
-        assetUrl: asset.assetUrl,
-        contentType: asset.contentType,
-      })
-    const inspectImages: InspectImages = (request) =>
-      inspectChatImages({
-        workspaceId: workspace.id,
-        sources,
-        hardenChatAssetUrl,
-        hardenImageInspectionAsset,
-        request,
-      })
+    const readTableHtml = (assetUrl: string): Promise<string> =>
+      readSignedTableHtml(assetUrl)
+    const resolveConnectedAssets = createConnectedAssetResolver(
+      knowhereResources.client.documents,
+    )
 
     const result: Either.Either<ChatTurnValue, ChatAnswerFailure> =
       yield* Effect.tryPromise(() =>
@@ -143,6 +105,9 @@ const answerChatEffect = (input: AnswerChatInput) =>
           threadId: body.value.threadId,
           useAgentic: body.value.useAgentic,
           excludedSourceIds: body.value.excludedSourceIds,
+          folderId: body.value.folderId,
+          resolveFolderScopeSourceIds:
+            folderWorkflowRuntime.resolveDescendantSourceIds,
           retrieval: client.retrieval,
           knowledge: knowhereResources.knowledge,
           hardenChatAssetUrl,
@@ -154,7 +119,8 @@ const answerChatEffect = (input: AnswerChatInput) =>
               artifacts,
               hardenChatAssetUrl,
             }),
-          inspectImages,
+          resolveConnectedAssets,
+          readTableHtml,
           repository: chatTurnPersistence.createRepository(),
         }),
       ).pipe(
@@ -210,310 +176,14 @@ export const chatAnswerRouteService: ChatAnswerRouteService = {
   answerChat,
 }
 
-async function inspectChatImages(input: {
-  readonly workspaceId: string
-  readonly sources: readonly Source[]
-  readonly hardenChatAssetUrl: HardenChatAssetUrl
-  readonly hardenImageInspectionAsset: HardenImageInspectionAsset
-  readonly request: ImageInspectionRequest
-}): Promise<ImageInspectionResponse> {
-  const preparedAssets: PreparedImageInspectionAsset[] = []
-  const skippedAssets: ImageInspectionSkippedAsset[] = []
-
-  for (const asset of input.request.assets) {
-    const preparedAsset = await prepareImageInspectionAsset({
-      asset,
-      sources: input.sources,
-      hardenChatAssetUrl: input.hardenChatAssetUrl,
-      hardenImageInspectionAsset: input.hardenImageInspectionAsset,
-    })
-    if (preparedAsset.ok) {
-      preparedAssets.push(preparedAsset.asset)
-    } else {
-      skippedAssets.push({
-        ref: asset.ref,
-        reason: preparedAsset.reason,
-      })
-    }
-  }
-
-  if (preparedAssets.length === 0) {
-    logger.warn("chat: image inspection skipped all assets", {
-      workspaceId: input.workspaceId,
-      requestedCount: input.request.assets.length,
-      skipped: skippedAssets.map((asset) => ({
-        ref: asset.ref,
-        reason: asset.reason,
-      })),
-    })
-    return {
-      analysis: "",
-      inspected: [],
-      skipped: skippedAssets,
-    }
-  }
-
-  logger.info("chat: image inspection request", {
-    workspaceId: input.workspaceId,
-    model: VISION_MODEL,
-    requestedCount: input.request.assets.length,
-    inspectedCount: preparedAssets.length,
-    skippedCount: skippedAssets.length,
-    refs: preparedAssets.map((asset) => asset.ref),
-  })
-
-  const response = await generateImageInspectionModelResult({
-    workspaceId: input.workspaceId,
-    question: input.request.question,
-    assets: preparedAssets,
-  })
-  const analysis = removeImageInspectionUrls({
-    text: response.analysis,
-    assets: preparedAssets,
-  })
-  const highlights = normalizeImageInspectionHighlights({
-    pages: response.pages,
-    allowedRefs: new Set(preparedAssets.map((asset) => asset.ref)),
-  })
-
-  logger.info("chat: image inspection response", {
-    workspaceId: input.workspaceId,
-    model: VISION_MODEL,
-    inspectedCount: preparedAssets.length,
-    skippedCount: skippedAssets.length,
-    analysisLength: analysis.length,
-    inspectionSource: response.source,
-    highlightPageCount: highlights.length,
-    highlightRegionCount: highlights.reduce(
-      (count, page) => count + page.regions.length,
-      0,
-    ),
-  })
-
-  return {
-    analysis,
-    inspected: preparedAssets.map((asset) => ({
-      ref: asset.ref,
-      label: asset.label,
-    })),
-    skipped: skippedAssets,
-    ...(highlights.length > 0 ? { highlights } : {}),
-  }
-}
-
-type PreparedImageInspectionAsset = {
-  readonly ref: string
-  readonly label: string
-  readonly url: URL
-  readonly body: Uint8Array
-  readonly contentType: string
-  readonly fileName?: string
-}
-
-type PrepareImageInspectionAssetResult =
-  | {
-      readonly ok: true
-      readonly asset: PreparedImageInspectionAsset
-    }
-  | {
-      readonly ok: false
-      readonly reason: string
-    }
-
-async function prepareImageInspectionAsset(input: {
-  readonly asset: ImageInspectionAsset
-  readonly sources: readonly Source[]
-  readonly hardenChatAssetUrl: HardenChatAssetUrl
-  readonly hardenImageInspectionAsset: HardenImageInspectionAsset
-}): Promise<PrepareImageInspectionAssetResult> {
-  const sourcePath = resolveImageInspectionSourcePath(input.asset)
-  if (!sourcePath) {
-    return {
-      ok: false,
-      reason: "The image asset path could not be resolved.",
-    }
-  }
-
-  const contentType = getSupportedImageContentType(sourcePath)
-  if (!contentType) {
-    return {
-      ok: false,
-      reason: "Only PNG, JPEG, and WebP image assets can be inspected.",
-    }
-  }
-
-  const source = resolveImageInspectionSource(input.asset, input.sources)
-  const durableUrlFromSource = source
-    ? await input.hardenChatAssetUrl({
-        source,
-        sourcePath,
-        assetUrl: input.asset.assetUrl,
-        contentType,
-      })
-    : null
-  const durableUrl =
-    durableUrlFromSource ??
-    (await hardenImageInspectionAssetByRef({
-      asset: input.asset,
-      sourcePath,
-      contentType,
-      hardenImageInspectionAsset: input.hardenImageInspectionAsset,
-    }))
-  if (!durableUrl) {
-    return {
-      ok: false,
-      reason: source
-        ? "The image asset was unavailable in Notebook storage."
-        : "No ready Notebook source matched the image asset.",
-    }
-  }
-
-  const url = parseAbsoluteHttpUrl(durableUrl)
-  if (!url) {
-    return {
-      ok: false,
-      reason: "Notebook storage did not return a valid image URL.",
-    }
-  }
-  const image = await fetchPreparedInspectionImage({
-    url,
-    contentType,
-  })
-  if (!image.ok) {
-    return {
-      ok: false,
-      reason: image.reason,
-    }
-  }
-
-  return {
-    ok: true,
-    asset: {
-      ref: input.asset.ref,
-      label: input.asset.label,
-      url,
-      body: image.body,
-      contentType,
-      fileName: getFileNameFromPath(sourcePath),
-    },
-  }
-}
-
-async function fetchPreparedInspectionImage(input: {
-  readonly url: URL
-  readonly contentType: string
-}): Promise<
-  | {
-      readonly ok: true
-      readonly body: Uint8Array
-    }
-  | {
-      readonly ok: false
-      readonly reason: string
-    }
-> {
-  try {
-    const image = await fetchChatAsset({
-      assetUrl: input.url.toString(),
-      fallbackContentType: input.contentType,
-    })
-    return {
-      ok: true,
-      body: image.body,
-    }
-  } catch {
-    return {
-      ok: false,
-      reason: "The Notebook image asset could not be read for inspection.",
-    }
-  }
-}
-
-async function hardenImageInspectionAssetByRef(input: {
-  readonly asset: ImageInspectionAsset
-  readonly sourcePath: string
-  readonly contentType: string
-  readonly hardenImageInspectionAsset: HardenImageInspectionAsset
-}): Promise<string | null> {
-  const documentId = getTrimmedString(input.asset.source.documentId)
-  const revisionKey = getTrimmedString(input.asset.revisionKey)
-  if (!documentId || !revisionKey) return null
-
-  return input.hardenImageInspectionAsset({
-    documentId,
-    revisionKey,
-    sourcePath: input.sourcePath,
-    assetUrl: input.asset.assetUrl,
-    contentType: input.contentType,
-  })
-}
-
-function resolveImageInspectionSource(
-  asset: ImageInspectionAsset,
-  sources: readonly Source[],
-): Source | undefined {
-  const documentId = getTrimmedString(asset.source.documentId)
-  if (!documentId) return undefined
-
-  return sources.find(
-    (source) =>
-      source.status === "ready" && source.knowhereDocumentId === documentId,
-  )
-}
-
-function resolveImageInspectionSourcePath(
-  asset: ImageInspectionAsset,
-): string | null {
-  const candidates = [
-    asset.sourcePath,
-    asset.source.sectionPath,
-    getAssetUrlPathname(asset.assetUrl),
-  ]
-  for (const candidate of candidates) {
-    const sourcePath = getSupportedImageAssetPath(candidate)
-    if (sourcePath) return sourcePath
-  }
-
-  return null
-}
-
-function getSupportedImageAssetPath(
-  value: string | null | undefined,
-): string | null {
-  const normalizedText = normalizeSourcePathCandidate(value)
-  if (!normalizedText) return null
-
-  const match =
-    /(?:^|\/)((?:images|pages|page_citation_assets)\/[^?#]+)(?:[?#]|$)?/i.exec(
-      normalizedText,
+async function readSignedTableHtml(assetUrl: string): Promise<string> {
+  const response = await fetch(assetUrl)
+  if (!response.ok) {
+    throw new Error(
+      `Unable to read table HTML: ${response.status} ${response.statusText}`,
     )
-  const matchedPath = match?.[1]
-  return matchedPath ? matchedPath.trim() : null
-}
-
-function getSupportedImageContentType(sourcePath: string): string | null {
-  const lowerPath = sourcePath.toLowerCase()
-  const extension = Object.keys(SUPPORTED_IMAGE_CONTENT_TYPES).find((candidate) =>
-    lowerPath.endsWith(candidate),
-  )
-  return extension ? SUPPORTED_IMAGE_CONTENT_TYPES[extension] ?? null : null
-}
-
-function removeImageInspectionUrls(input: {
-  readonly text: string
-  readonly assets: readonly PreparedImageInspectionAsset[]
-}): string {
-  const knownUrls = input.assets.map((asset) => asset.url.toString())
-  const withoutKnownUrls = knownUrls.reduce(
-    (text, assetUrl) =>
-      text.replaceAll(assetUrl, IMAGE_INSPECTION_URL_REPLACEMENT),
-    input.text,
-  )
-
-  return withoutKnownUrls
-    .replace(/https?:\/\/[^\s)\]}>"']+/g, IMAGE_INSPECTION_URL_REPLACEMENT)
-    .replace(/[ \t]{2,}/g, " ")
-    .trim()
+  }
+  return response.text()
 }
 
 async function hardenSingleChatAsset(input: {
@@ -675,54 +345,6 @@ function inferContentTypeFromPath(sourcePath: string): string {
   return "application/octet-stream"
 }
 
-function getAssetUrlPathname(assetUrl: string | null | undefined): string | null {
-  const normalizedAssetUrl = getTrimmedString(assetUrl)
-  if (!normalizedAssetUrl) return null
-
-  try {
-    return new URL(normalizedAssetUrl).pathname
-  } catch {
-    return normalizedAssetUrl.split("?")[0] ?? normalizedAssetUrl
-  }
-}
-
-function normalizeSourcePathCandidate(
-  value: string | null | undefined,
-): string | null {
-  const trimmedValue = getTrimmedString(value)
-  if (!trimmedValue) return null
-
-  const normalized = decodeUrlText(trimmedValue)
-    .replaceAll("\\", "/")
-    .replace(/\s*\/\s*/g, "/")
-    .replace(/\s+/g, " ")
-    .trim()
-
-  return normalized.length > 0 ? normalized : null
-}
-
-function decodeUrlText(value: string): string {
-  try {
-    return decodeURIComponent(value)
-  } catch {
-    return value
-  }
-}
-
-function parseAbsoluteHttpUrl(assetUrl: string): URL | null {
-  try {
-    const url = new URL(assetUrl)
-    return url.protocol === "http:" || url.protocol === "https:" ? url : null
-  } catch {
-    return null
-  }
-}
-
-function getFileNameFromPath(sourcePath: string): string | undefined {
-  const fileName = sourcePath.replaceAll("\\", "/").split("/").pop()?.trim()
-  return fileName && fileName.length > 0 ? fileName : undefined
-}
-
 function triggerBackgroundReconciliationForParsingSources(input: {
   readonly workspaceId: string
   readonly sources: readonly Source[]
diff --git a/src/domains/chat/route-service.test.ts b/src/domains/chat/route-service.test.ts
index 1db1e94..7c0e196 100644
--- a/src/domains/chat/route-service.test.ts
+++ b/src/domains/chat/route-service.test.ts
@@ -6,6 +6,7 @@ import type { ChatMessage, ChatThread, Source, Workspace } from "@/infrastructur
 const mocks = vi.hoisted(() => ({
   appendMessageToThread: vi.fn(),
   createChatThread: vi.fn(),
+  documentListChunks: vi.fn(),
   ensureDefaultChatThread: vi.fn(),
   findChatThreadInWorkspace: vi.fn(),
   generateAgenticOutputManifest: vi.fn(),
@@ -120,9 +121,15 @@ describe("chat route services", () => {
     mocks.parsedStorageGetAssetUrl.mockResolvedValue(null)
     mocks.parsedStorageWriteAsset.mockResolvedValue({ url: null })
     mocks.makeKnowhereClientWithParsedStorage.mockReturnValue({
-      client: {},
+      client: { documents: { listChunks: mocks.documentListChunks } },
       knowledge: {},
     })
+    mocks.documentListChunks.mockResolvedValue({
+      documentId: "doc_1",
+      namespace: "default",
+      chunks: [],
+      pagination: { page: 1, pageSize: 200, total: 0, totalPages: 1 },
+    })
     mocks.generateObject.mockResolvedValue({
       object: {
         analysis: "The image shows a chart.",
@@ -195,6 +202,8 @@ describe("chat route services", () => {
         retrieval: client.retrieval,
         generateAnswer: expect.any(Function),
         hardenChatAssetUrl: expect.any(Function),
+        resolveConnectedAssets: expect.any(Function),
+        readTableHtml: expect.any(Function),
         repository: expect.objectContaining({
           appendMessageToThread: expect.any(Function),
           ensureDefaultChatThread: expect.any(Function),
@@ -205,45 +214,28 @@ describe("chat route services", () => {
     )
   })
 
-  it("hardens one chat asset through Notebook Blob for a ready source", async () => {
+  it("injects a reader that returns the complete signed table HTML", async () => {
     const workspace = makeWorkspace()
     const client = { retrieval: { query: vi.fn() } }
-    const readySource = makeSource({
-      status: "ready",
-      knowhereDocumentId: "doc_legacy",
-      knowhereJobId: "job_1",
-    })
-    const rawUrl = "https://knowhere-storage.example/results/job_1/pages/page-1.png"
-    const durableUrl =
-      "https://fake.public.blob.vercel-storage.com/workspaces/workspace_1/parsed-documents/doc_legacy/job_1/pages/page-1.png"
-    mocks.parsedStorageWriteAsset.mockResolvedValue({ url: durableUrl })
+    const signedUrl = "https://knowhere-storage.example/tables/revenue.html?signature=valid"
+    const tableHtml = "<table><tr><td>Q4</td><td>24.9</td></tr></table>"
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(tableHtml)))
     mocks.getAuthenticatedWithClient.mockResolvedValue({
       user: { id: "user_1" },
       workspace,
       apiKey: "jwt_123",
       client,
     })
-    mocks.listSourcesForWorkspace.mockResolvedValue([readySource])
+    mocks.listSourcesForWorkspace.mockResolvedValue([makeSource()])
     mocks.handleChatTurn.mockImplementation(
       async (input: {
-        readonly hardenChatAssetUrl?: (assetInput: {
-          readonly source: Source
-          readonly sourcePath: string
-          readonly assetUrl?: string | null
-          readonly contentType?: string | null
-        }) => Promise<string | null>
+        readonly readTableHtml?: (assetUrl: string) => Promise<string>
       }) => {
-        const assetUrl = await input.hardenChatAssetUrl?.({
-          source: readySource,
-          sourcePath: "pages/page-1.png",
-          assetUrl: rawUrl,
-          contentType: "image/png",
-        })
-        expect(assetUrl).toBe(durableUrl)
+        expect(await input.readTableHtml?.(signedUrl)).toBe(tableHtml)
         return Either.right({
           threadId: "thread_1",
           messages: [
-            { id: "message_user", role: "user", content: "Show the page" },
+            { id: "message_user", role: "user", content: "Read the table" },
             { id: "message_assistant", role: "assistant", content: "Answer" },
           ],
         })
@@ -251,43 +243,30 @@ describe("chat route services", () => {
     )
 
     const result = await chatAnswerRouteService.answerChat({
-      body: { message: "Show the page" },
+      body: { message: "Read the table" },
     })
 
     expect(result.status).toBe(200)
-    expect(mocks.parsedStorageGetAssetUrl).toHaveBeenCalledWith({
-      documentId: "doc_legacy",
-      revisionKey: "job_1",
-      sourcePath: "pages/page-1.png",
-    })
-    expect(fetch).toHaveBeenCalledWith(rawUrl)
-    expect(mocks.parsedStorageWriteAsset).toHaveBeenCalledWith({
-      documentId: "doc_legacy",
-      revisionKey: "job_1",
-      sourcePath: "pages/page-1.png",
-      body: new Uint8Array([1, 2, 3]),
-      contentType: "image/png",
-    })
+    expect(fetch).toHaveBeenCalledWith(signedUrl)
   })
 
-  it("hardens image inspection assets before sending Notebook URLs to Gemini", async () => {
+  it("injects a resolver that matches connected assets by parser chunk id", async () => {
     const workspace = makeWorkspace()
     const client = { retrieval: { query: vi.fn() } }
-    const readySource = makeSource({
-      status: "ready",
-      knowhereDocumentId: "doc_identity",
-      knowhereJobId: "job_1",
-    })
-    const rawUrl =
-      "https://knowhere-storage.example/results/job_1/images/id-front.png?AWSAccessKeyId=test"
-    const durableUrl =
-      "https://fake.public.blob.vercel-storage.com/workspaces/workspace_1/parsed-documents/doc_identity/job_1/images/id-front.png"
-    mocks.parsedStorageWriteAsset.mockResolvedValue({ url: durableUrl })
-    mocks.generateObject.mockResolvedValue({
-      object: {
-        analysis: `The card number is visible. ${durableUrl} ${rawUrl}`,
-        pages: [],
-      },
+    mocks.documentListChunks.mockResolvedValue({
+      documentId: "doc_1",
+      namespace: "default",
+      chunks: [
+        {
+          id: "dchk_1",
+          chunkId: "parser_image_1",
+          chunkType: "image",
+          sortOrder: 1,
+          metadata: {},
+          assetUrl: "https://assets.example/image.jpg",
+        },
+      ],
+      pagination: { page: 1, pageSize: 200, total: 1, totalPages: 1 },
     })
     mocks.getAuthenticatedWithClient.mockResolvedValue({
       user: { id: "user_1" },
@@ -295,62 +274,31 @@ describe("chat route services", () => {
       apiKey: "jwt_123",
       client,
     })
-    mocks.listSourcesForWorkspace.mockResolvedValue([readySource])
+    mocks.listSourcesForWorkspace.mockResolvedValue([makeSource()])
     mocks.handleChatTurn.mockImplementation(
       async (input: {
-        readonly inspectImages?: (request: {
-          readonly question: string
-          readonly assets: readonly {
-            readonly ref: string
-            readonly label: string
-            readonly assetUrl: string
-            readonly source: {
-              readonly documentId?: string | null
-              readonly sourceFileName?: string | null
-              readonly sectionPath?: string | null
-            }
-          }[]
-        }) => Promise<{
-          readonly analysis: string
-          readonly inspected: readonly {
-            readonly ref: string
-            readonly label: string
-          }[]
-          readonly skipped: readonly {
-            readonly ref: string
-            readonly reason: string
-          }[]
-        }>
+        readonly resolveConnectedAssets?: (
+          lookups: readonly {
+            documentId: string
+            chunkId: string
+            type: "image" | "table"
+          }[],
+        ) => Promise<readonly unknown[]>
       }) => {
-        const inspection = await input.inspectImages?.({
-          question: "Read the ID card text.",
-          assets: [
-            {
-              ref: "asset:r1:result:1",
-              label: "identity.pdf / images/id-front.png / image",
-              assetUrl: rawUrl,
-              source: {
-                documentId: "doc_identity",
-                sourceFileName: "identity.pdf",
-                sectionPath: "images/id-front.png",
-              },
-            },
-          ],
-        })
-        expect(inspection).toEqual({
-          analysis: "The card number is visible. [image URL hidden] [image URL hidden]",
-          inspected: [
-            {
-              ref: "asset:r1:result:1",
-              label: "identity.pdf / images/id-front.png / image",
-            },
-          ],
-          skipped: [],
-        })
+        expect(await input.resolveConnectedAssets?.([
+          { documentId: "doc_1", chunkId: "parser_image_1", type: "image" },
+        ])).toEqual([
+          {
+            documentId: "doc_1",
+            chunkId: "parser_image_1",
+            type: "image",
+            assetUrl: "https://assets.example/image.jpg",
+          },
+        ])
         return Either.right({
           threadId: "thread_1",
           messages: [
-            { id: "message_user", role: "user", content: "Inspect it" },
+            { id: "message_user", role: "user", content: "Show the image" },
             { id: "message_assistant", role: "assistant", content: "Answer" },
           ],
         })
@@ -358,162 +306,30 @@ describe("chat route services", () => {
     )
 
     const result = await chatAnswerRouteService.answerChat({
-      body: { message: "Inspect the ID card image" },
+      body: { message: "Show the image" },
     })
 
     expect(result.status).toBe(200)
-    expect(fetch).toHaveBeenCalledWith(rawUrl)
-    expect(fetch).toHaveBeenCalledWith(durableUrl)
-    expect(mocks.parsedStorageWriteAsset).toHaveBeenCalledWith({
-      documentId: "doc_identity",
-      revisionKey: "job_1",
-      sourcePath: "images/id-front.png",
-      body: new Uint8Array([1, 2, 3]),
-      contentType: "image/png",
+    expect(mocks.documentListChunks).toHaveBeenCalledWith("doc_1", {
+      page: 1,
+      pageSize: 200,
+      chunkType: "image",
+      includeAssetUrls: true,
     })
-    const generateInput = mocks.generateObject.mock.calls[0]?.[0]
-    expect(generateInput).toMatchObject({
-      model: "deepseek/deepseek-v4.1-flash",
-    })
-    expect(JSON.stringify(generateInput)).not.toContain(
-      "knowhere-storage.example",
-    )
-    const content = generateInput.messages[0].content
-    const imagePart = content.find(
-      (part: { readonly type: string }) => part.type === "image",
-    )
-    expect(imagePart.image).toEqual(new Uint8Array([1, 2, 3]))
-    expect(imagePart.mediaType).toBe("image/png")
   })
 
-  it("hardens materialized demo page assets for image inspection", async () => {
-    const workspace = makeWorkspace()
-    const client = { retrieval: { query: vi.fn() } }
-    const readySource = makeSource({
-      title: "TSLA-Q4-2025-Update.pdf",
-      demoKey: "demo-tsla-q4-2025",
-      knowhereDocumentId: "doc_materialized_tesla",
-      knowhereJobId: null,
-    })
-    const demoAssetUrl =
-      "https://demo.example/api/v1/demo/sources/demo-tsla-q4-2025/assets/page_citation_assets/page-6.png"
-    const durableUrl =
-      "https://fake.public.blob.vercel-storage.com/workspaces/workspace_1/parsed-documents/doc_materialized_tesla/doc_materialized_tesla/page_citation_assets/page-6.png"
-    mocks.parsedStorageWriteAsset.mockResolvedValue({ url: durableUrl })
-    mocks.generateObject.mockResolvedValue({
-      object: {
-        analysis: "The total production row is visible.",
-        pages: [],
-      },
-    })
-    mocks.getAuthenticatedWithClient.mockResolvedValue({
-      user: { id: "user_1" },
-      workspace,
-      apiKey: "jwt_123",
-      client,
-    })
-    mocks.listSourcesForWorkspace.mockResolvedValue([readySource])
-    mocks.handleChatTurn.mockImplementation(
-      async (input: {
-        readonly inspectImages?: (request: {
-          readonly question: string
-          readonly assets: readonly {
-            readonly ref: string
-            readonly label: string
-            readonly sourcePath?: string | null
-            readonly source: {
-              readonly documentId?: string | null
-              readonly sourceFileName?: string | null
-              readonly sectionPath?: string | null
-            }
-          }[]
-        }) => Promise<{
-          readonly analysis: string
-          readonly inspected: readonly {
-            readonly ref: string
-            readonly label: string
-          }[]
-          readonly skipped: readonly {
-            readonly ref: string
-            readonly reason: string
-          }[]
-        }>
-      }) => {
-        const inspection = await input.inspectImages?.({
-          question: "Locate total production.",
-          assets: [
-            {
-              ref: "asset:r1:result:1",
-              label:
-                "TSLA-Q4-2025-Update.pdf / page_citation_assets/page-6.png",
-              sourcePath: "page_citation_assets/page-6.png",
-              source: {
-                documentId: "doc_materialized_tesla",
-                sourceFileName: "TSLA-Q4-2025-Update.pdf",
-                sectionPath: "OPERATIONAL SUMMARY",
-              },
-            },
-          ],
-        })
-        expect(inspection).toEqual({
-          analysis: "The total production row is visible.",
-          inspected: [
-            {
-              ref: "asset:r1:result:1",
-              label:
-                "TSLA-Q4-2025-Update.pdf / page_citation_assets/page-6.png",
-            },
-          ],
-          skipped: [],
-        })
-        return Either.right({
-          threadId: "thread_1",
-          messages: [
-            { id: "message_user", role: "user", content: "Inspect it" },
-            { id: "message_assistant", role: "assistant", content: "Answer" },
-          ],
-        })
-      },
-    )
-
-    const result = await chatAnswerRouteService.answerChat({
-      body: { message: "What was Tesla total production?" },
-    })
-
-    expect(result.status).toBe(200)
-    expect(mocks.parsedStorageGetAssetUrl).toHaveBeenCalledWith({
-      documentId: "doc_materialized_tesla",
-      revisionKey: "doc_materialized_tesla",
-      sourcePath: "page_citation_assets/page-6.png",
-    })
-    expect(fetch).toHaveBeenCalledWith(demoAssetUrl)
-    expect(fetch).toHaveBeenCalledWith(durableUrl)
-    expect(mocks.parsedStorageWriteAsset).toHaveBeenCalledWith({
-      documentId: "doc_materialized_tesla",
-      revisionKey: "doc_materialized_tesla",
-      sourcePath: "page_citation_assets/page-6.png",
-      body: new Uint8Array([1, 2, 3]),
-      contentType: "image/png",
-    })
-  })
-
-  it("uses image inspection source paths for retrieved page assets", async () => {
+  it("hardens one chat asset through Notebook Blob for a ready source", async () => {
     const workspace = makeWorkspace()
     const client = { retrieval: { query: vi.fn() } }
     const readySource = makeSource({
       status: "ready",
-      knowhereDocumentId: "doc_contract",
+      knowhereDocumentId: "doc_legacy",
       knowhereJobId: "job_1",
     })
+    const rawUrl = "https://knowhere-storage.example/results/job_1/pages/page-1.png"
     const durableUrl =
-      "https://fake.public.blob.vercel-storage.com/workspaces/workspace_1/parsed-documents/doc_contract/job_1/page_citation_assets/page-8.png"
-    mocks.parsedStorageGetAssetUrl.mockResolvedValue(durableUrl)
-    mocks.generateObject.mockResolvedValue({
-      object: {
-        analysis: "The page states 5000 yuan per occurrence.",
-        pages: [],
-      },
-    })
+      "https://fake.public.blob.vercel-storage.com/workspaces/workspace_1/parsed-documents/doc_legacy/job_1/pages/page-1.png"
+    mocks.parsedStorageWriteAsset.mockResolvedValue({ url: durableUrl })
     mocks.getAuthenticatedWithClient.mockResolvedValue({
       user: { id: "user_1" },
       workspace,
@@ -523,62 +339,24 @@ describe("chat route services", () => {
     mocks.listSourcesForWorkspace.mockResolvedValue([readySource])
     mocks.handleChatTurn.mockImplementation(
       async (input: {
-        readonly inspectImages?: (request: {
-          readonly question: string
-          readonly assets: readonly {
-            readonly ref: string
-            readonly label: string
-            readonly assetUrl?: string | null
-            readonly sourcePath?: string | null
-            readonly source: {
-              readonly documentId?: string | null
-              readonly sourceFileName?: string | null
-              readonly sectionPath?: string | null
-            }
-          }[]
-        }) => Promise<{
-          readonly analysis: string
-          readonly inspected: readonly {
-            readonly ref: string
-            readonly label: string
-          }[]
-          readonly skipped: readonly {
-            readonly ref: string
-            readonly reason: string
-          }[]
-        }>
+        readonly hardenChatAssetUrl?: (assetInput: {
+          readonly source: Source
+          readonly sourcePath: string
+          readonly assetUrl?: string | null
+          readonly contentType?: string | null
+        }) => Promise<string | null>
       }) => {
-        const inspection = await input.inspectImages?.({
-          question: "Read the damages amount.",
-          assets: [
-            {
-              ref: "asset:r1:referenced:1",
-              label:
-                "Root / （6）现场工期进度管理方面的违约责任 / page_citation_assets/page-8.png / page",
-              sourcePath: "page_citation_assets/page-8.png",
-              source: {
-                documentId: "doc_contract",
-                sourceFileName: "投标书.pdf",
-                sectionPath: "Root / （6）现场工期进度管理方面的违约责任",
-              },
-            },
-          ],
-        })
-        expect(inspection).toEqual({
-          analysis: "The page states 5000 yuan per occurrence.",
-          inspected: [
-            {
-              ref: "asset:r1:referenced:1",
-              label:
-                "Root / （6）现场工期进度管理方面的违约责任 / page_citation_assets/page-8.png / page",
-            },
-          ],
-          skipped: [],
+        const assetUrl = await input.hardenChatAssetUrl?.({
+          source: readySource,
+          sourcePath: "pages/page-1.png",
+          assetUrl: rawUrl,
+          contentType: "image/png",
         })
+        expect(assetUrl).toBe(durableUrl)
         return Either.right({
           threadId: "thread_1",
           messages: [
-            { id: "message_user", role: "user", content: "Inspect it" },
+            { id: "message_user", role: "user", content: "Show the page" },
             { id: "message_assistant", role: "assistant", content: "Answer" },
           ],
         })
@@ -586,243 +364,23 @@ describe("chat route services", () => {
     )
 
     const result = await chatAnswerRouteService.answerChat({
-      body: { message: "Inspect the clause page" },
+      body: { message: "Show the page" },
     })
 
     expect(result.status).toBe(200)
     expect(mocks.parsedStorageGetAssetUrl).toHaveBeenCalledWith({
-      documentId: "doc_contract",
+      documentId: "doc_legacy",
       revisionKey: "job_1",
-      sourcePath: "page_citation_assets/page-8.png",
-    })
-    expect(fetch).toHaveBeenCalledWith(durableUrl)
-    expect(mocks.parsedStorageWriteAsset).not.toHaveBeenCalled()
-    const generateInput = mocks.generateObject.mock.calls[0]?.[0]
-    const content = generateInput.messages[0].content
-    const imagePart = content.find(
-      (part: { readonly type: string }) => part.type === "image",
-    )
-    expect(imagePart.image).toEqual(new Uint8Array([1, 2, 3]))
-    expect(imagePart.mediaType).toBe("image/png")
-  })
-
-  it("hardens remote page inspection assets by document revision when no local source matches", async () => {
-    const workspace = makeWorkspace()
-    const client = { retrieval: { query: vi.fn() } }
-    const rawUrl =
-      "https://knowhere-storage.example/results/job_remote/page_citation_assets/page-8.png?AWSAccessKeyId=test"
-    const durableUrl =
-      "https://fake.public.blob.vercel-storage.com/workspaces/workspace_1/parsed-documents/doc_remote/job_remote/page_citation_assets/page-8.png"
-    mocks.parsedStorageWriteAsset.mockResolvedValue({ url: durableUrl })
-    mocks.generateObject.mockResolvedValue({
-      object: {
-        analysis: "The page states 5000 yuan per occurrence.",
-        pages: [],
-      },
-    })
-    mocks.getAuthenticatedWithClient.mockResolvedValue({
-      user: { id: "user_1" },
-      workspace,
-      apiKey: "jwt_123",
-      client,
-    })
-    mocks.listSourcesForWorkspace.mockResolvedValue([])
-    mocks.handleChatTurn.mockImplementation(
-      async (input: {
-        readonly inspectImages?: (request: {
-          readonly question: string
-          readonly assets: readonly {
-            readonly ref: string
-            readonly label: string
-            readonly assetUrl?: string | null
-            readonly sourcePath?: string | null
-            readonly revisionKey?: string | null
-            readonly source: {
-              readonly documentId?: string | null
-              readonly sourceFileName?: string | null
-              readonly sectionPath?: string | null
-            }
-          }[]
-        }) => Promise<{
-          readonly analysis: string
-          readonly inspected: readonly {
-            readonly ref: string
-            readonly label: string
-          }[]
-          readonly skipped: readonly {
-            readonly ref: string
-            readonly reason: string
-          }[]
-        }>
-      }) => {
-        const inspection = await input.inspectImages?.({
-          question: "Read the damages amount.",
-          assets: [
-            {
-              ref: "asset:r1:referenced:5",
-              label:
-                "Root / （6）现场工期进度管理方面的违约责任 / page_citation_assets/page-8.png / page",
-              assetUrl: rawUrl,
-              sourcePath: "page_citation_assets/page-8.png",
-              revisionKey: "job_remote",
-              source: {
-                documentId: "doc_remote",
-                sourceFileName: null,
-                sectionPath: "Root / （6）现场工期进度管理方面的违约责任",
-              },
-            },
-          ],
-        })
-        expect(inspection).toEqual({
-          analysis: "The page states 5000 yuan per occurrence.",
-          inspected: [
-            {
-              ref: "asset:r1:referenced:5",
-              label:
-                "Root / （6）现场工期进度管理方面的违约责任 / page_citation_assets/page-8.png / page",
-            },
-          ],
-          skipped: [],
-        })
-        return Either.right({
-          threadId: "thread_1",
-          messages: [
-            { id: "message_user", role: "user", content: "Inspect it" },
-            { id: "message_assistant", role: "assistant", content: "Answer" },
-          ],
-        })
-      },
-    )
-
-    const result = await chatAnswerRouteService.answerChat({
-      body: { message: "Inspect the remote clause page" },
-    })
-
-    expect(result.status).toBe(200)
-    expect(mocks.parsedStorageGetAssetUrl).toHaveBeenCalledWith({
-      documentId: "doc_remote",
-      revisionKey: "job_remote",
-      sourcePath: "page_citation_assets/page-8.png",
+      sourcePath: "pages/page-1.png",
     })
     expect(fetch).toHaveBeenCalledWith(rawUrl)
-    expect(fetch).toHaveBeenCalledWith(durableUrl)
     expect(mocks.parsedStorageWriteAsset).toHaveBeenCalledWith({
-      documentId: "doc_remote",
-      revisionKey: "job_remote",
-      sourcePath: "page_citation_assets/page-8.png",
+      documentId: "doc_legacy",
+      revisionKey: "job_1",
+      sourcePath: "pages/page-1.png",
       body: new Uint8Array([1, 2, 3]),
       contentType: "image/png",
     })
-    const generateInput = mocks.generateObject.mock.calls[0]?.[0]
-    expect(JSON.stringify(generateInput)).not.toContain(
-      "knowhere-storage.example",
-    )
-    const content = generateInput.messages[0].content
-    const imagePart = content.find(
-      (part: { readonly type: string }) => part.type === "image",
-    )
-    expect(imagePart.image).toEqual(new Uint8Array([1, 2, 3]))
-    expect(imagePart.mediaType).toBe("image/png")
-  })
-
-  it("skips unsupported or unavailable image inspection assets without failing chat", async () => {
-    const workspace = makeWorkspace()
-    const client = { retrieval: { query: vi.fn() } }
-    const readySource = makeSource({
-      status: "ready",
-      knowhereDocumentId: "doc_identity",
-      knowhereJobId: "job_1",
-    })
-    mocks.getAuthenticatedWithClient.mockResolvedValue({
-      user: { id: "user_1" },
-      workspace,
-      apiKey: "jwt_123",
-      client,
-    })
-    mocks.listSourcesForWorkspace.mockResolvedValue([readySource])
-    mocks.handleChatTurn.mockImplementation(
-      async (input: {
-        readonly inspectImages?: (request: {
-          readonly question: string
-          readonly assets: readonly {
-            readonly ref: string
-            readonly label: string
-            readonly assetUrl: string
-            readonly source: {
-              readonly documentId?: string | null
-              readonly sourceFileName?: string | null
-              readonly sectionPath?: string | null
-            }
-          }[]
-        }) => Promise<{
-          readonly analysis: string
-          readonly inspected: readonly {
-            readonly ref: string
-            readonly label: string
-          }[]
-          readonly skipped: readonly {
-            readonly ref: string
-            readonly reason: string
-          }[]
-        }>
-      }) => {
-        const inspection = await input.inspectImages?.({
-          question: "Inspect these.",
-          assets: [
-            {
-              ref: "asset:r1:result:1",
-              label: "identity.pdf / images/animated.gif / image",
-              assetUrl: "https://knowhere-storage.example/results/job_1/images/animated.gif",
-              source: {
-                documentId: "doc_identity",
-                sourceFileName: "identity.pdf",
-                sectionPath: "images/animated.gif",
-              },
-            },
-            {
-              ref: "asset:r1:result:2",
-              label: "missing.pdf / images/missing.png / image",
-              assetUrl: "https://knowhere-storage.example/results/job_2/images/missing.png",
-              source: {
-                documentId: "doc_missing",
-                sourceFileName: "missing.pdf",
-                sectionPath: "images/missing.png",
-              },
-            },
-          ],
-        })
-        expect(inspection).toEqual({
-          analysis: "",
-          inspected: [],
-          skipped: [
-            {
-              ref: "asset:r1:result:1",
-              reason: "Only PNG, JPEG, and WebP image assets can be inspected.",
-            },
-            {
-              ref: "asset:r1:result:2",
-              reason: "No ready Notebook source matched the image asset.",
-            },
-          ],
-        })
-        return Either.right({
-          threadId: "thread_1",
-          messages: [
-            { id: "message_user", role: "user", content: "Inspect it" },
-            { id: "message_assistant", role: "assistant", content: "Answer" },
-          ],
-        })
-      },
-    )
-
-    const result = await chatAnswerRouteService.answerChat({
-      body: { message: "Inspect images" },
-    })
-
-    expect(result.status).toBe(200)
-    expect(mocks.generateObject).not.toHaveBeenCalled()
-    expect(mocks.generateText).not.toHaveBeenCalled()
-    expect(fetch).not.toHaveBeenCalled()
   })
 
   it("triggers background reconciliation for parsing sources without blocking chat", async () => {
@@ -1085,6 +643,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-06T00:00:00Z"),
     updatedAt: new Date("2026-05-06T00:00:00Z"),
     deletedAt: null,
diff --git a/src/domains/chat/service.test.ts b/src/domains/chat/service.test.ts
index 620fa9f..dfaf6bb 100644
--- a/src/domains/chat/service.test.ts
+++ b/src/domains/chat/service.test.ts
@@ -252,6 +252,87 @@ describe("handleChatTurn", () => {
       dataType: 1,
     });
   });
+
+  it("answers in an empty folder without searching", async () => {
+    const retrieval = { query: vi.fn() };
+    const repository = makeRepository();
+    const generateAnswer = vi.fn(async ({ searchSources, folderScopeSourceIds }) => {
+      expect(folderScopeSourceIds).toEqual([]);
+      await expect(searchSources({ query: "What is in this folder?" })).rejects.toThrow(
+        "The current folder has no documents. Do not call knowhere_search.",
+      );
+      return makeHarnessRunResult("This folder has no documents.");
+    });
+
+    const result = await handleChatTurn({
+      workspace: makeWorkspace(),
+      sources: [makeSource({ id: "source_elsewhere" })],
+      question: "hello",
+      excludedSourceIds: [],
+      folderId: "folder_empty",
+      resolveFolderScopeSourceIds: vi.fn().mockResolvedValue([]),
+      retrieval,
+      generateAnswer,
+      repository,
+    });
+
+    expect(Either.isRight(result)).toBe(true);
+    expect(retrieval.query).not.toHaveBeenCalled();
+    expect(repository.appendMessageToThread).toHaveBeenCalled();
+  });
+
+  it("scopes retrieval to the ready documents in the current folder", async () => {
+    const retrieval = {
+      query: vi.fn().mockResolvedValue({
+        results: [makeRetrievalResult()],
+        evidenceText: "Grounding content",
+        referencedChunks: [],
+        namespace: "notebook-namespace",
+        query: "What is in this folder?",
+        routerUsed: "workflow_single_step",
+        answerText: null,
+      }),
+    };
+    const repository = makeRepository();
+    const generateAnswer = vi.fn(async ({ searchSources }) => {
+      await searchSources({ query: "What is in this folder?" });
+      return makeHarnessRunResult("Grounded answer.");
+    });
+    const sources = [
+      makeSource({
+        id: "source_in_folder",
+        knowhereDocumentId: "doc_in_folder",
+      }),
+      makeSource({
+        id: "source_elsewhere",
+        knowhereDocumentId: "doc_elsewhere",
+      }),
+    ];
+
+    const result = await handleChatTurn({
+      workspace: makeWorkspace(),
+      sources,
+      question: "What is in this folder?",
+      excludedSourceIds: [],
+      folderId: "folder_1",
+      resolveFolderScopeSourceIds: vi
+        .fn()
+        .mockResolvedValue(["source_in_folder"]),
+      retrieval,
+      generateAnswer,
+      repository,
+    });
+
+    expect(Either.isRight(result)).toBe(true);
+    expect(retrieval.query).toHaveBeenCalledWith({
+      namespace: "default",
+      query: "What is in this folder?",
+      topK: 8,
+      useAgentic: true,
+      dataType: 1,
+      includeDocumentIds: ["doc_in_folder"],
+    });
+  });
 });
 
 function makeRepository(
@@ -306,6 +387,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-06T00:00:00Z"),
     updatedAt: new Date("2026-05-06T00:00:00Z"),
     deletedAt: null,
@@ -373,6 +455,8 @@ function makeHarnessRunResult(text: string): HarnessRunResult {
         stopReasons: [],
         failureReasons: [],
         decisionTraces: [],
+        retainedPicks: [],
+        pendingRetention: null,
       },
       finalized: true,
       priorTurnReads: [],
diff --git a/src/domains/chat/service.ts b/src/domains/chat/service.ts
index 8139a42..1f3fb56 100644
--- a/src/domains/chat/service.ts
+++ b/src/domains/chat/service.ts
@@ -66,12 +66,18 @@ type ChatTurnInput = {
   threadId?: string
   useAgentic?: boolean
   excludedSourceIds: readonly string[]
+  folderId?: string
+  resolveFolderScopeSourceIds?: (
+    workspaceId: string,
+    folderId: string,
+  ) => Promise<readonly string[]>
   retrieval: RetrievalClient
   knowledge?: AnswerQuestionInput["knowledge"]
   generateAnswer: GenerateAnswer
   hardenChatAssetUrl?: AnswerQuestionInput["hardenChatAssetUrl"]
   hardenMediaAssetUrls?: AnswerQuestionInput["hardenMediaAssetUrls"]
-  inspectImages?: AnswerQuestionInput["inspectImages"]
+  resolveConnectedAssets?: AnswerQuestionInput["resolveConnectedAssets"]
+  readTableHtml?: AnswerQuestionInput["readTableHtml"]
   repository: ChatRepository
 }
 
@@ -88,6 +94,8 @@ export const handleChatTurnEffect = (input: ChatTurnInput) =>
       return yield* Effect.fail(noReadySources)
     }
 
+    const folderScopeSourceIds = yield* resolveFolderScopeSourceIdsEffect(input)
+
     const thread = input.threadId
       ? yield* tryPromiseOrDie(() =>
           input.repository.findChatThreadInWorkspace(
@@ -128,12 +136,16 @@ export const handleChatTurnEffect = (input: ChatTurnInput) =>
       sources: readySources,
       useAgentic: input.useAgentic ?? true,
       excludedSourceIds: input.excludedSourceIds,
+      folderScopeSourceIds,
       retrieval: input.retrieval,
       knowledge: input.knowledge,
       generateAnswer: input.generateAnswer,
       hardenChatAssetUrl: input.hardenChatAssetUrl,
       hardenMediaAssetUrls: input.hardenMediaAssetUrls,
-      inspectImages: input.inspectImages,
+      ...(input.resolveConnectedAssets
+        ? { resolveConnectedAssets: input.resolveConnectedAssets }
+        : {}),
+      readTableHtml: input.readTableHtml,
       messages: chatHistoryMessages,
     }).pipe(Effect.catchAllCause(Effect.die))
 
@@ -169,6 +181,15 @@ export async function handleChatTurn(
   return Effect.runPromise(Effect.either(handleChatTurnEffect(input)))
 }
 
+const resolveFolderScopeSourceIdsEffect = (input: ChatTurnInput) =>
+  Effect.gen(function* () {
+    if (!input.folderId) return undefined
+    if (!input.resolveFolderScopeSourceIds) return []
+    return yield* tryPromiseOrDie(() =>
+      input.resolveFolderScopeSourceIds!(input.workspace.id, input.folderId!),
+    )
+  })
+
 function toChatHistoryMessages(
   messages: readonly ChatMessage[],
 ): ChatHistoryMessage[] {
diff --git a/src/domains/chunks/index.test.ts b/src/domains/chunks/index.test.ts
index 91f3021..f301fd7 100644
--- a/src/domains/chunks/index.test.ts
+++ b/src/domains/chunks/index.test.ts
@@ -705,6 +705,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-06T00:00:00Z"),
     updatedAt: new Date("2026-05-06T00:00:00Z"),
     deletedAt: null,
diff --git a/src/domains/folders/repository.ts b/src/domains/folders/repository.ts
new file mode 100644
index 0000000..d082a41
--- /dev/null
+++ b/src/domains/folders/repository.ts
@@ -0,0 +1,428 @@
+import "server-only"
+
+import { and, eq, isNull, sql } from "drizzle-orm"
+import { Effect } from "effect"
+
+import { DbClient, type Db } from "@/infrastructure/db"
+import { folders, sources, type Folder } from "@/infrastructure/db/schema"
+import type { FolderMutationError, FolderWriteResult } from "./types"
+
+const FOLDER_ID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu
+// MARK: magic number — max folder name length (kept on purpose)
+const FOLDER_NAME_MAX_LENGTH = 80
+
+type FolderRepository = {
+  readonly listForWorkspaceEffect: (
+    workspaceId: string,
+  ) => Effect.Effect<Folder[], never, DbClient>
+  readonly findInWorkspaceEffect: (
+    workspaceId: string,
+    folderId: string,
+  ) => Effect.Effect<Folder | null, never, DbClient>
+  readonly createFolderEffect: (
+    workspaceId: string,
+    parentId: string | null,
+    name: string,
+  ) => Effect.Effect<FolderWriteResult<Folder>, never, DbClient>
+  readonly renameFolderEffect: (
+    workspaceId: string,
+    folderId: string,
+    name: string,
+  ) => Effect.Effect<FolderWriteResult<Folder>, never, DbClient>
+  readonly moveFolderEffect: (
+    workspaceId: string,
+    folderId: string,
+    parentId: string | null,
+  ) => Effect.Effect<FolderWriteResult<Folder>, never, DbClient>
+  readonly softDeleteFolderEffect: (
+    workspaceId: string,
+    folderId: string,
+  ) => Effect.Effect<FolderWriteResult<true>, never, DbClient>
+  readonly resolveDescendantSourceIdsEffect: (
+    workspaceId: string,
+    folderId: string,
+  ) => Effect.Effect<readonly string[], never, DbClient>
+}
+
+const listForWorkspaceEffect: FolderRepository["listForWorkspaceEffect"] = (
+  workspaceId: string,
+) =>
+  Effect.gen(function* () {
+    const db = yield* DbClient
+    return yield* Effect.promise(() =>
+      db
+        .select()
+        .from(folders)
+        .where(
+          and(eq(folders.workspaceId, workspaceId), isNull(folders.deletedAt)),
+        ),
+    )
+  })
+
+const findInWorkspaceEffect: FolderRepository["findInWorkspaceEffect"] = (
+  workspaceId: string,
+  folderId: string,
+) =>
+  Effect.gen(function* () {
+    const db = yield* DbClient
+    return yield* Effect.promise(() =>
+      findFolderInWorkspace(db, workspaceId, folderId),
+    )
+  })
+
+const createFolderEffect: FolderRepository["createFolderEffect"] = (
+  workspaceId: string,
+  parentId: string | null,
+  name: string,
+) =>
+  Effect.gen(function* () {
+    const db = yield* DbClient
+    const normalizedName = normalizeFolderName(name)
+    if (!normalizedName) return fail("folder-name-invalid")
+
+    const parentCheck = yield* Effect.promise(() =>
+      assertParentFolder(db, workspaceId, parentId),
+    )
+    if (!parentCheck.ok) return parentCheck
+
+    const conflict = yield* Effect.promise(() =>
+      findSiblingNameConflict(db, workspaceId, parentId, normalizedName),
+    )
+    if (conflict) return fail("folder-name-conflict")
+
+    const [folder] = yield* Effect.promise(() =>
+      db
+        .insert(folders)
+        .values({
+          workspaceId,
+          parentId,
+          name: normalizedName,
+        })
+        .returning(),
+    )
+    if (!folder) {
+      return yield* Effect.die(new Error("createFolder: insert did not return a row."))
+    }
+
+    return succeed(folder)
+  })
+
+const renameFolderEffect: FolderRepository["renameFolderEffect"] = (
+  workspaceId: string,
+  folderId: string,
+  name: string,
+) =>
+  Effect.gen(function* () {
+    const db = yield* DbClient
+    const normalizedName = normalizeFolderName(name)
+    if (!normalizedName) return fail("folder-name-invalid")
+
+    const folder = yield* Effect.promise(() =>
+      findFolderInWorkspace(db, workspaceId, folderId),
+    )
+    if (!folder) return fail("folder-not-found")
+
+    const conflict = yield* Effect.promise(() =>
+      findSiblingNameConflict(
+        db,
+        workspaceId,
+        folder.parentId,
+        normalizedName,
+        folderId,
+      ),
+    )
+    if (conflict) return fail("folder-name-conflict")
+
+    const [updated] = yield* Effect.promise(() =>
+      db
+        .update(folders)
+        .set({ name: normalizedName, updatedAt: sql`now()` })
+        .where(
+          and(
+            eq(folders.id, folderId),
+            eq(folders.workspaceId, workspaceId),
+            isNull(folders.deletedAt),
+          ),
+        )
+        .returning(),
+    )
+    if (!updated) return fail("folder-not-found")
+    return succeed(updated)
+  })
+
+const moveFolderEffect: FolderRepository["moveFolderEffect"] = (
+  workspaceId: string,
+  folderId: string,
+  parentId: string | null,
+) =>
+  Effect.gen(function* () {
+    const db = yield* DbClient
+    const folder = yield* Effect.promise(() =>
+      findFolderInWorkspace(db, workspaceId, folderId),
+    )
+    if (!folder) return fail("folder-not-found")
+    if (parentId === folderId) return fail("folder-cycle")
+
+    const parentCheck = yield* Effect.promise(() =>
+      assertParentFolder(db, workspaceId, parentId),
+    )
+    if (!parentCheck.ok) return parentCheck
+
+    if (parentId) {
+      const isCycle = yield* Effect.promise(() =>
+        isFolderInSubtree(db, workspaceId, folderId, parentId),
+      )
+      if (isCycle) return fail("folder-cycle")
+    }
+
+    const conflict = yield* Effect.promise(() =>
+      findSiblingNameConflict(
+        db,
+        workspaceId,
+        parentId,
+        folder.name,
+        folderId,
+      ),
+    )
+    if (conflict) return fail("folder-name-conflict")
+
+    const [updated] = yield* Effect.promise(() =>
+      db
+        .update(folders)
+        .set({ parentId, updatedAt: sql`now()` })
+        .where(
+          and(
+            eq(folders.id, folderId),
+            eq(folders.workspaceId, workspaceId),
+            isNull(folders.deletedAt),
+          ),
+        )
+        .returning(),
+    )
+    if (!updated) return fail("folder-not-found")
+    return succeed(updated)
+  })
+
+const softDeleteFolderEffect: FolderRepository["softDeleteFolderEffect"] = (
+  workspaceId: string,
+  folderId: string,
+) =>
+  Effect.gen(function* () {
+    const db = yield* DbClient
+    const folder = yield* Effect.promise(() =>
+      findFolderInWorkspace(db, workspaceId, folderId),
+    )
+    if (!folder) return fail("folder-not-found")
+
+    const [childFolder] = yield* Effect.promise(() =>
+      db
+        .select({ id: folders.id })
+        .from(folders)
+        .where(
+          and(
+            eq(folders.workspaceId, workspaceId),
+            eq(folders.parentId, folderId),
+            isNull(folders.deletedAt),
+          ),
+        )
+        .limit(1),
+    )
+    if (childFolder) return fail("folder-not-empty")
+
+    const [childSource] = yield* Effect.promise(() =>
+      db
+        .select({ id: sources.id })
+        .from(sources)
+        .where(
+          and(
+            eq(sources.workspaceId, workspaceId),
+            eq(sources.folderId, folderId),
+            isNull(sources.deletedAt),
+          ),
+        )
+        .limit(1),
+    )
+    if (childSource) return fail("folder-not-empty")
+
+    const [deleted] = yield* Effect.promise(() =>
+      db
+        .update(folders)
+        .set({ deletedAt: sql`now()`, updatedAt: sql`now()` })
+        .where(
+          and(
+            eq(folders.id, folderId),
+            eq(folders.workspaceId, workspaceId),
+            isNull(folders.deletedAt),
+          ),
+        )
+        .returning({ id: folders.id }),
+    )
+    if (!deleted) return fail("folder-not-found")
+    return succeed(true as const)
+  })
+
+const resolveDescendantSourceIdsEffect: FolderRepository["resolveDescendantSourceIdsEffect"] =
+  (workspaceId: string, folderId: string) =>
+    Effect.gen(function* () {
+      const db = yield* DbClient
+      if (!isFolderId(folderId)) return []
+
+      const rows = yield* Effect.promise(() =>
+        db.execute<{ id: string }>(sql`
+          WITH RECURSIVE folder_tree AS (
+            SELECT id
+            FROM folders
+            WHERE id = ${folderId}::uuid
+              AND workspace_id = ${workspaceId}::uuid
+              AND deleted_at IS NULL
+            UNION ALL
+            SELECT folders.id
+            FROM folders
+            INNER JOIN folder_tree ON folders.parent_id = folder_tree.id
+            WHERE folders.workspace_id = ${workspaceId}::uuid
+              AND folders.deleted_at IS NULL
+          )
+          SELECT sources.id
+          FROM sources
+          INNER JOIN folder_tree ON sources.folder_id = folder_tree.id
+          WHERE sources.workspace_id = ${workspaceId}::uuid
+            AND sources.deleted_at IS NULL
+        `),
+      )
+
+      return readExecuteIds(rows)
+    })
+
+function isFolderId(folderId: string): boolean {
+  return FOLDER_ID_PATTERN.test(folderId)
+}
+
+function normalizeFolderName(value: string): string | null {
+  const name = value.replace(/\s+/g, " ").trim()
+  if (name.length === 0 || name.length > FOLDER_NAME_MAX_LENGTH) return null
+  return name
+}
+
+async function findFolderInWorkspace(
+  db: Db,
+  workspaceId: string,
+  folderId: string,
+): Promise<Folder | null> {
+  if (!isFolderId(folderId)) return null
+
+  const [folder] = await db
+    .select()
+    .from(folders)
+    .where(
+      and(
+        eq(folders.id, folderId),
+        eq(folders.workspaceId, workspaceId),
+        isNull(folders.deletedAt),
+      ),
+    )
+    .limit(1)
+
+  return folder ?? null
+}
+
+async function assertParentFolder(
+  db: Db,
+  workspaceId: string,
+  parentId: string | null,
+): Promise<FolderWriteResult<true>> {
+  if (parentId === null) return succeed(true)
+  const parent = await findFolderInWorkspace(db, workspaceId, parentId)
+  if (!parent) return fail("invalid-parent-folder")
+  return succeed(true)
+}
+
+async function findSiblingNameConflict(
+  db: Db,
+  workspaceId: string,
+  parentId: string | null,
+  name: string,
+  excludeFolderId?: string,
+): Promise<Folder | null> {
+  const parentCondition =
+    parentId === null ? isNull(folders.parentId) : eq(folders.parentId, parentId)
+  const conditions = [
+    eq(folders.workspaceId, workspaceId),
+    parentCondition,
+    eq(folders.name, name),
+    isNull(folders.deletedAt),
+  ]
+  if (excludeFolderId) {
+    conditions.push(sql`${folders.id} <> ${excludeFolderId}::uuid`)
+  }
+  const [conflict] = await db
+    .select()
+    .from(folders)
+    .where(and(...conditions))
+    .limit(1)
+
+  return conflict ?? null
+}
+
+async function isFolderInSubtree(
+  db: Db,
+  workspaceId: string,
+  folderId: string,
+  candidateId: string,
+): Promise<boolean> {
+  const rows = await db.execute<{ id: string }>(sql`
+    WITH RECURSIVE descendants AS (
+      SELECT id
+      FROM folders
+      WHERE id = ${folderId}::uuid
+        AND workspace_id = ${workspaceId}::uuid
+        AND deleted_at IS NULL
+      UNION ALL
+      SELECT folders.id
+      FROM folders
+      INNER JOIN descendants ON folders.parent_id = descendants.id
+      WHERE folders.workspace_id = ${workspaceId}::uuid
+        AND folders.deleted_at IS NULL
+    )
+    SELECT id
+    FROM descendants
+    WHERE id = ${candidateId}::uuid
+    LIMIT 1
+  `)
+
+  return readExecuteIds(rows).length > 0
+}
+
+function readExecuteIds(result: unknown): string[] {
+  const rows = Array.isArray(result)
+    ? result
+    : result &&
+        typeof result === "object" &&
+        "rows" in result &&
+        Array.isArray(result.rows)
+      ? result.rows
+      : []
+
+  return rows.flatMap((row) => {
+    if (!row || typeof row !== "object" || !("id" in row)) return []
+    return typeof row.id === "string" ? [row.id] : []
+  })
+}
+
+function succeed<Value>(value: Value): FolderWriteResult<Value> {
+  return { ok: true, value }
+}
+
+function fail(error: FolderMutationError): FolderWriteResult<never> {
+  return { ok: false, error }
+}
+
+export const folderRepository: FolderRepository = {
+  listForWorkspaceEffect,
+  findInWorkspaceEffect,
+  createFolderEffect,
+  renameFolderEffect,
+  moveFolderEffect,
+  softDeleteFolderEffect,
+  resolveDescendantSourceIdsEffect,
+}
diff --git a/src/domains/folders/route-request.ts b/src/domains/folders/route-request.ts
new file mode 100644
index 0000000..669a56e
--- /dev/null
+++ b/src/domains/folders/route-request.ts
@@ -0,0 +1,112 @@
+import { Schema } from "effect"
+
+import { routeResult, type RouteResult } from "@/lib/route-result"
+
+type FolderRequestInput = {
+  readonly request: Request
+}
+
+type CreateFolderReadResult =
+  | {
+      readonly ok: true
+      readonly parentId: string | null
+      readonly name: string
+    }
+  | {
+      readonly ok: false
+      readonly result: RouteResult<{ readonly message: string }>
+    }
+
+type UpdateFolderReadResult =
+  | {
+      readonly ok: true
+      readonly name?: string
+      readonly parentId?: string | null
+    }
+  | {
+      readonly ok: false
+      readonly result: RouteResult<{ readonly message: string }>
+    }
+
+const CreateFolderRequest = Schema.Struct({
+  name: Schema.String,
+  parentId: Schema.optional(Schema.NullOr(Schema.String)),
+})
+
+const UpdateFolderRequest = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  parentId: Schema.optional(Schema.NullOr(Schema.String)),
+})
+
+async function readCreateFolder({
+  request,
+}: FolderRequestInput): Promise<CreateFolderReadResult> {
+  const body = await routeResult.readJson(request)
+  if (!body.ok) {
+    return {
+      ok: false,
+      result: routeResult.badRequest("Invalid request body."),
+    }
+  }
+
+  const decoded = Schema.decodeUnknownEither(CreateFolderRequest)(body.value)
+  if (decoded._tag === "Left") {
+    return {
+      ok: false,
+      result: routeResult.badRequest("Request body must include a folder name."),
+    }
+  }
+
+  return {
+    ok: true,
+    name: decoded.right.name,
+    parentId: decoded.right.parentId ?? null,
+  }
+}
+
+async function readUpdateFolder({
+  request,
+}: FolderRequestInput): Promise<UpdateFolderReadResult> {
+  const body = await routeResult.readJson(request)
+  if (!body.ok) {
+    return {
+      ok: false,
+      result: routeResult.badRequest("Invalid request body."),
+    }
+  }
+
+  const decoded = Schema.decodeUnknownEither(UpdateFolderRequest)(body.value)
+  if (decoded._tag === "Left") {
+    return {
+      ok: false,
+      result: routeResult.badRequest(
+        "Request body must include a folder name or parentId.",
+      ),
+    }
+  }
+
+  if (
+    decoded.right.name === undefined &&
+    decoded.right.parentId === undefined
+  ) {
+    return {
+      ok: false,
+      result: routeResult.badRequest(
+        "Request body must include a folder name or parentId.",
+      ),
+    }
+  }
+
+  return {
+    ok: true,
+    ...(decoded.right.name !== undefined ? { name: decoded.right.name } : {}),
+    ...(decoded.right.parentId !== undefined
+      ? { parentId: decoded.right.parentId }
+      : {}),
+  }
+}
+
+export const folderRouteRequest = {
+  readCreateFolder,
+  readUpdateFolder,
+}
diff --git a/src/domains/folders/route-service.ts b/src/domains/folders/route-service.ts
new file mode 100644
index 0000000..44f2ae3
--- /dev/null
+++ b/src/domains/folders/route-service.ts
@@ -0,0 +1,178 @@
+import "server-only"
+
+import { notebookRequestContext } from "@/domains/workspace/request-context"
+import { routeResult, type RouteResult } from "@/lib/route-result"
+import { toFolderView } from "./tree"
+import type { FolderMutationError, FolderView, FolderWriteResult } from "./types"
+import { folderWorkflowRuntime } from "./workflow-runtime"
+
+type ListFoldersBody = {
+  readonly folders: readonly FolderView[]
+}
+
+type FolderBody =
+  | {
+      readonly folder: FolderView
+    }
+  | {
+      readonly message: string
+    }
+
+type DeleteFolderBody =
+  | {
+      readonly id: string
+      readonly archived: true
+    }
+  | {
+      readonly message: string
+    }
+
+type FolderRouteService = {
+  readonly listFolders: () => Promise<RouteResult<ListFoldersBody>>
+  readonly createFolder: (input: {
+    readonly name: string
+    readonly parentId: string | null
+  }) => Promise<RouteResult<FolderBody>>
+  readonly updateFolder: (input: {
+    readonly folderId: string
+    readonly name?: string
+    readonly parentId?: string | null
+  }) => Promise<RouteResult<FolderBody>>
+  readonly deleteFolder: (input: {
+    readonly folderId: string
+  }) => Promise<RouteResult<DeleteFolderBody>>
+}
+
+async function listFolders(): Promise<RouteResult<ListFoldersBody>> {
+  const { workspace } = await notebookRequestContext.getAuthenticated()
+  const folders = await folderWorkflowRuntime.listForWorkspace(workspace.id)
+  return routeResult.ok({
+    folders: folders.map(toFolderView),
+  })
+}
+
+async function createFolder(input: {
+  readonly name: string
+  readonly parentId: string | null
+}): Promise<RouteResult<FolderBody>> {
+  const { workspace } = await notebookRequestContext.getAuthenticated()
+  const result = await folderWorkflowRuntime.createFolder(
+    workspace.id,
+    input.parentId,
+    input.name,
+  )
+  return toFolderBody(result)
+}
+
+async function updateFolder(input: {
+  readonly folderId: string
+  readonly name?: string
+  readonly parentId?: string | null
+}): Promise<RouteResult<FolderBody>> {
+  const { workspace } = await notebookRequestContext.getAuthenticated()
+  let current = await folderWorkflowRuntime.findInWorkspace(
+    workspace.id,
+    input.folderId,
+  )
+  if (!current) {
+    return routeResult.error(404, folderErrorMessage("folder-not-found"))
+  }
+
+  if (input.name !== undefined) {
+    const renamed = await folderWorkflowRuntime.renameFolder(
+      workspace.id,
+      input.folderId,
+      input.name,
+    )
+    if (!renamed.ok) return toFolderBody(renamed)
+    current = renamed.value
+  }
+
+  if (input.parentId !== undefined) {
+    const moved = await folderWorkflowRuntime.moveFolder(
+      workspace.id,
+      input.folderId,
+      input.parentId,
+    )
+    if (!moved.ok) return toFolderBody(moved)
+    current = moved.value
+  }
+
+  return routeResult.ok({ folder: toFolderView(current) })
+}
+
+async function deleteFolder(input: {
+  readonly folderId: string
+}): Promise<RouteResult<DeleteFolderBody>> {
+  const { workspace } = await notebookRequestContext.getAuthenticated()
+  const result = await folderWorkflowRuntime.softDeleteFolder(
+    workspace.id,
+    input.folderId,
+  )
+  if (!result.ok) {
+    return routeResult.error(
+      folderErrorStatus(result.error),
+      folderErrorMessage(result.error),
+    )
+  }
+
+  return routeResult.ok({
+    id: input.folderId,
+    archived: true as const,
+  })
+}
+
+function toFolderBody(
+  result: FolderWriteResult<{
+    readonly id: string
+    readonly parentId: string | null
+    readonly name: string
+  }>,
+): RouteResult<FolderBody> {
+  if (!result.ok) {
+    return routeResult.error(
+      folderErrorStatus(result.error),
+      folderErrorMessage(result.error),
+    )
+  }
+
+  return routeResult.ok({ folder: toFolderView(result.value) })
+}
+
+function folderErrorStatus(error: FolderMutationError): number {
+  switch (error) {
+    case "folder-not-found":
+    case "invalid-parent-folder":
+      return 404
+    case "folder-name-conflict":
+    case "folder-not-empty":
+    case "folder-cycle":
+      return 409
+    case "folder-name-invalid":
+      return 400
+  }
+}
+
+function folderErrorMessage(error: FolderMutationError): string {
+  switch (error) {
+    case "folder-not-found":
+      return "Folder not found."
+    case "folder-name-invalid":
+      return "Enter a folder name up to 80 characters."
+    case "folder-name-conflict":
+      return "A folder with this name already exists here."
+    case "folder-not-empty":
+      return "Move or delete the folder contents first."
+    case "folder-cycle":
+      return "A folder cannot be moved into itself."
+    case "invalid-parent-folder":
+      return "Parent folder not found."
+  }
+}
+
+export const folderRouteService: FolderRouteService = {
+  listFolders,
+  createFolder,
+  updateFolder,
+  deleteFolder,
+}
diff --git a/src/domains/folders/tree.test.ts b/src/domains/folders/tree.test.ts
new file mode 100644
index 0000000..6492583
--- /dev/null
+++ b/src/domains/folders/tree.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest"
+
+import type { SourceView } from "@/domains/sources/types"
+import {
+  canAssignSourceToFolder,
+  getDescendantFolderIds,
+  getFolderPath,
+  listChildFolders,
+  listSourcesInFolder,
+} from "./tree"
+import type { FolderView } from "./types"
+
+describe("folder tree", () => {
+  const folders: FolderView[] = [
+    { id: "folder_cardio", parentId: null, name: "Cardio" },
+    { id: "folder_2024", parentId: "folder_cardio", name: "2024" },
+    { id: "folder_other", parentId: null, name: "Other" },
+  ]
+
+  it("lists child folders in name order", () => {
+    expect(listChildFolders(folders, null).map((folder) => folder.id)).toEqual([
+      "folder_cardio",
+      "folder_other",
+    ])
+    expect(
+      listChildFolders(folders, "folder_cardio").map((folder) => folder.id),
+    ).toEqual(["folder_2024"])
+  })
+
+  it("builds the breadcrumb path from root to the current folder", () => {
+    expect(getFolderPath(folders, "folder_2024").map((folder) => folder.name)).toEqual(
+      ["Cardio", "2024"],
+    )
+    expect(getFolderPath(folders, null)).toEqual([])
+  })
+
+  it("includes a folder and its descendants", () => {
+    expect(new Set(getDescendantFolderIds(folders, "folder_cardio"))).toEqual(
+      new Set(["folder_cardio", "folder_2024"]),
+    )
+  })
+
+  it("lists sources sitting in one folder", () => {
+    const sources: SourceView[] = [
+      makeSource({ id: "source_root" }),
+      makeSource({ id: "source_cardio", folderId: "folder_cardio" }),
+      makeSource({ id: "source_2024", folderId: "folder_2024" }),
+    ]
+
+    expect(listSourcesInFolder(sources, null).map((source) => source.id)).toEqual([
+      "source_root",
+    ])
+    expect(
+      listSourcesInFolder(sources, "folder_cardio").map((source) => source.id),
+    ).toEqual(["source_cardio"])
+  })
+
+  it("keeps demo and remote sources out of folder assignment", () => {
+    expect(canAssignSourceToFolder(makeSource({ id: "source_workspace" }))).toBe(
+      true,
+    )
+    expect(
+      canAssignSourceToFolder(
+        makeSource({ id: "source_demo", demoSourceId: "demo-1" }),
+      ),
+    ).toBe(false)
+    expect(
+      canAssignSourceToFolder(makeSource({ id: "source_remote", kind: "remote" })),
+    ).toBe(false)
+  })
+})
+
+function makeSource(overrides: Partial<SourceView> = {}): SourceView {
+  return {
+    id: "source_1",
+    title: "notes.pdf",
+    mimeType: "application/pdf",
+    status: "ready",
+    ...overrides,
+  }
+}
diff --git a/src/domains/folders/tree.ts b/src/domains/folders/tree.ts
new file mode 100644
index 0000000..c3afc0b
--- /dev/null
+++ b/src/domains/folders/tree.ts
@@ -0,0 +1,86 @@
+import type { SourceView } from "@/domains/sources/types"
+import type { FolderView } from "./types"
+
+export function listChildFolders(
+  folders: readonly FolderView[],
+  parentId: string | null,
+): FolderView[] {
+  return folders
+    .filter((folder) => folder.parentId === parentId)
+    .slice()
+    .sort((left, right) => left.name.localeCompare(right.name))
+}
+
+export function getFolderPath(
+  folders: readonly FolderView[],
+  folderId: string | null,
+): FolderView[] {
+  if (!folderId) return []
+
+  const foldersById = new Map(folders.map((folder) => [folder.id, folder]))
+  const path: FolderView[] = []
+  const seen = new Set<string>()
+  let current = foldersById.get(folderId)
+
+  while (current && !seen.has(current.id)) {
+    seen.add(current.id)
+    path.unshift(current)
+    current = current.parentId
+      ? foldersById.get(current.parentId)
+      : undefined
+  }
+
+  return path
+}
+
+export function getDescendantFolderIds(
+  folders: readonly FolderView[],
+  folderId: string,
+): readonly string[] {
+  const childrenByParent = new Map<string | null, FolderView[]>()
+  for (const folder of folders) {
+    const siblings = childrenByParent.get(folder.parentId) ?? []
+    siblings.push(folder)
+    childrenByParent.set(folder.parentId, siblings)
+  }
+
+  const folderIds: string[] = []
+  const stack = [folderId]
+  while (stack.length > 0) {
+    const currentId = stack.pop()
+    if (!currentId) continue
+    folderIds.push(currentId)
+    for (const child of childrenByParent.get(currentId) ?? []) {
+      stack.push(child.id)
+    }
+  }
+
+  return folderIds
+}
+
+export function listSourcesInFolder(
+  sources: readonly SourceView[],
+  folderId: string | null,
+): SourceView[] {
+  return sources.filter((source) => (source.folderId ?? null) === folderId)
+}
+
+export function canAssignSourceToFolder(source: SourceView): boolean {
+  return (
+    source.kind !== "remote" &&
+    source.officialLibrary === undefined &&
+    source.demoSourceId === undefined
+  )
+}
+
+export function toFolderView(folder: {
+  readonly id: string
+  readonly parentId: string | null
+  readonly name: string
+}): FolderView {
+  return {
+    id: folder.id,
+    parentId: folder.parentId,
+    name: folder.name,
+  }
+}
diff --git a/src/domains/folders/types.ts b/src/domains/folders/types.ts
new file mode 100644
index 0000000..3bf0162
--- /dev/null
+++ b/src/domains/folders/types.ts
@@ -0,0 +1,23 @@
+export type FolderView = {
+  readonly id: string
+  readonly parentId: string | null
+  readonly name: string
+}
+
+export type FolderMutationError =
+  | "folder-not-found"
+  | "folder-name-invalid"
+  | "folder-name-conflict"
+  | "folder-not-empty"
+  | "folder-cycle"
+  | "invalid-parent-folder"
+
+export type FolderWriteResult<Value> =
+  | {
+      readonly ok: true
+      readonly value: Value
+    }
+  | {
+      readonly ok: false
+      readonly error: FolderMutationError
+    }
diff --git a/src/domains/folders/workflow-runtime.ts b/src/domains/folders/workflow-runtime.ts
new file mode 100644
index 0000000..adbf195
--- /dev/null
+++ b/src/domains/folders/workflow-runtime.ts
@@ -0,0 +1,100 @@
+import "server-only"
+
+import { databaseRuntime } from "@/domains/workspace/database-runtime"
+import type { Folder } from "@/infrastructure/db/schema"
+import { folderRepository } from "./repository"
+import type { FolderWriteResult } from "./types"
+
+type FolderWorkflowRuntime = {
+  readonly listForWorkspace: (workspaceId: string) => Promise<Folder[]>
+  readonly findInWorkspace: (
+    workspaceId: string,
+    folderId: string,
+  ) => Promise<Folder | null>
+  readonly createFolder: (
+    workspaceId: string,
+    parentId: string | null,
+    name: string,
+  ) => Promise<FolderWriteResult<Folder>>
+  readonly renameFolder: (
+    workspaceId: string,
+    folderId: string,
+    name: string,
+  ) => Promise<FolderWriteResult<Folder>>
+  readonly moveFolder: (
+    workspaceId: string,
+    folderId: string,
+    parentId: string | null,
+  ) => Promise<FolderWriteResult<Folder>>
+  readonly softDeleteFolder: (
+    workspaceId: string,
+    folderId: string,
+  ) => Promise<FolderWriteResult<true>>
+  readonly resolveDescendantSourceIds: (
+    workspaceId: string,
+    folderId: string,
+  ) => Promise<readonly string[]>
+}
+
+const listForWorkspace: FolderWorkflowRuntime["listForWorkspace"] = (
+  workspaceId: string,
+) => databaseRuntime.runPromise(folderRepository.listForWorkspaceEffect(workspaceId))
+
+const findInWorkspace: FolderWorkflowRuntime["findInWorkspace"] = (
+  workspaceId: string,
+  folderId: string,
+) =>
+  databaseRuntime.runPromise(
+    folderRepository.findInWorkspaceEffect(workspaceId, folderId),
+  )
+
+const createFolder: FolderWorkflowRuntime["createFolder"] = (
+  workspaceId: string,
+  parentId: string | null,
+  name: string,
+) =>
+  databaseRuntime.runPromise(
+    folderRepository.createFolderEffect(workspaceId, parentId, name),
+  )
+
+const renameFolder: FolderWorkflowRuntime["renameFolder"] = (
+  workspaceId: string,
+  folderId: string,
+  name: string,
+) =>
+  databaseRuntime.runPromise(
+    folderRepository.renameFolderEffect(workspaceId, folderId, name),
+  )
+
+const moveFolder: FolderWorkflowRuntime["moveFolder"] = (
+  workspaceId: string,
+  folderId: string,
+  parentId: string | null,
+) =>
+  databaseRuntime.runPromise(
+    folderRepository.moveFolderEffect(workspaceId, folderId, parentId),
+  )
+
+const softDeleteFolder: FolderWorkflowRuntime["softDeleteFolder"] = (
+  workspaceId: string,
+  folderId: string,
+) =>
+  databaseRuntime.runPromise(
+    folderRepository.softDeleteFolderEffect(workspaceId, folderId),
+  )
+
+const resolveDescendantSourceIds: FolderWorkflowRuntime["resolveDescendantSourceIds"] =
+  (workspaceId: string, folderId: string) =>
+    databaseRuntime.runPromise(
+      folderRepository.resolveDescendantSourceIdsEffect(workspaceId, folderId),
+    )
+
+export const folderWorkflowRuntime: FolderWorkflowRuntime = {
+  listForWorkspace,
+  findInWorkspace,
+  createFolder,
+  renameFolder,
+  moveFolder,
+  softDeleteFolder,
+  resolveDescendantSourceIds,
+}
diff --git a/src/domains/sources/reconcile.test.ts b/src/domains/sources/reconcile.test.ts
index 9e255a0..4e96eb7 100644
--- a/src/domains/sources/reconcile.test.ts
+++ b/src/domains/sources/reconcile.test.ts
@@ -29,6 +29,7 @@ function makeSource(overrides: Partial<Source>): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-06T00:00:00Z"),
     updatedAt: new Date("2026-05-06T00:00:00Z"),
     deletedAt: null,
diff --git a/src/domains/sources/remote-library.test.ts b/src/domains/sources/remote-library.test.ts
index fea5026..b9e3bb9 100644
--- a/src/domains/sources/remote-library.test.ts
+++ b/src/domains/sources/remote-library.test.ts
@@ -24,6 +24,7 @@ const localSource: Source = {
   originalBlobUrl: null,
   demoKey: null,
   chunkCount: null,
+    folderId: null,
   createdAt: new Date("2026-05-10T00:00:00Z"),
   updatedAt: new Date("2026-05-10T00:00:00Z"),
   deletedAt: null,
diff --git a/src/domains/sources/repository.ts b/src/domains/sources/repository.ts
index 1e9a608..3b92508 100644
--- a/src/domains/sources/repository.ts
+++ b/src/domains/sources/repository.ts
@@ -17,6 +17,7 @@ type SourceRepository = {
   readonly markReadyEffect: typeof sourceRowRepository.markReadyEffect
   readonly updateRevisionKeyEffect: typeof sourceRowRepository.updateRevisionKeyEffect
   readonly recordChunkCountEffect: typeof sourceRowRepository.recordChunkCountEffect
+  readonly assignFolderEffect: typeof sourceRowRepository.assignFolderEffect
   readonly markFailedEffect: typeof sourceRowRepository.markFailedEffect
   readonly clearStagedBlobEffect: typeof sourceRowRepository.clearStagedBlobEffect
   readonly softDeleteEffect: typeof sourceRowRepository.softDeleteEffect
@@ -44,6 +45,7 @@ export const sourceRepository: SourceRepository = {
   markReadyEffect: sourceRowRepository.markReadyEffect,
   updateRevisionKeyEffect: sourceRowRepository.updateRevisionKeyEffect,
   recordChunkCountEffect: sourceRowRepository.recordChunkCountEffect,
+  assignFolderEffect: sourceRowRepository.assignFolderEffect,
   markFailedEffect: sourceRowRepository.markFailedEffect,
   clearStagedBlobEffect: sourceRowRepository.clearStagedBlobEffect,
   softDeleteEffect: sourceRowRepository.softDeleteEffect,
diff --git a/src/domains/sources/retry.test.ts b/src/domains/sources/retry.test.ts
index c930dce..6ff0384 100644
--- a/src/domains/sources/retry.test.ts
+++ b/src/domains/sources/retry.test.ts
@@ -135,6 +135,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
       "https://store.public.blob.vercel-storage.com/source-uploads/upload_1/document.pdf",
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-10T00:00:00Z"),
     updatedAt: new Date("2026-05-10T00:00:00Z"),
     deletedAt: null,
diff --git a/src/domains/sources/route-assign-folder.ts b/src/domains/sources/route-assign-folder.ts
new file mode 100644
index 0000000..0e68da3
--- /dev/null
+++ b/src/domains/sources/route-assign-folder.ts
@@ -0,0 +1,79 @@
+import { Effect } from "effect"
+
+import { folderWorkflowRuntime } from "@/domains/folders/workflow-runtime"
+import { routeResult } from "@/lib/route-result"
+import { toSourceView } from "./view"
+import { sourceWorkflowRuntime } from "./workflow-runtime"
+import type {
+  AssignSourceFolderBody,
+  AssignSourceFolderInput,
+  JsonRouteResult,
+  SourceRouteServiceDependencies,
+} from "./route-types"
+
+type RouteAssignFolderDependencies = Pick<
+  SourceRouteServiceDependencies,
+  "ensureWorkspace" | "requireUser" | "sourceService"
+>
+
+type RouteAssignFolder = {
+  readonly assignSourceFolder: (
+    input: AssignSourceFolderInput,
+  ) => Promise<JsonRouteResult<AssignSourceFolderBody>>
+}
+
+function createRouteAssignFolder(
+  deps: RouteAssignFolderDependencies,
+): RouteAssignFolder {
+  return {
+    assignSourceFolder: (input: AssignSourceFolderInput) =>
+      Effect.runPromise(assignSourceFolderEffect(input, deps)),
+  }
+}
+
+const assignSourceFolderEffect = (
+  input: AssignSourceFolderInput,
+  deps: RouteAssignFolderDependencies,
+) =>
+  Effect.gen(function* () {
+    const user = yield* Effect.tryPromise(() => deps.requireUser())
+    const workspace = yield* Effect.tryPromise(() =>
+      deps.ensureWorkspace(user.id),
+    )
+    const source = yield* Effect.tryPromise(() =>
+      deps.sourceService.findInWorkspace(workspace.id, input.sourceId),
+    )
+    if (!source) {
+      return routeResult.error(404, "Source not found.")
+    }
+    if (source.demoKey) {
+      return routeResult.error(
+        409,
+        "Demo sources cannot be moved into folders.",
+      )
+    }
+
+    if (input.folderId !== null) {
+      const folder = yield* Effect.tryPromise(() =>
+        folderWorkflowRuntime.findInWorkspace(workspace.id, input.folderId!),
+      )
+      if (!folder) {
+        return routeResult.error(404, "Folder not found.")
+      }
+    }
+
+    const updated = yield* Effect.tryPromise(() =>
+      sourceWorkflowRuntime.assignFolder(
+        workspace.id,
+        input.sourceId,
+        input.folderId,
+      ),
+    )
+    if (!updated) {
+      return routeResult.error(404, "Source not found.")
+    }
+
+    return routeResult.ok({ source: toSourceView(updated) })
+  })
+
+export { createRouteAssignFolder }
diff --git a/src/domains/sources/route-request.test.ts b/src/domains/sources/route-request.test.ts
index 9fa3a44..f3e237a 100644
--- a/src/domains/sources/route-request.test.ts
+++ b/src/domains/sources/route-request.test.ts
@@ -44,6 +44,29 @@ describe("sourceRouteRequest", () => {
     });
   });
 
+  it("reads a folder assignment into route service input", async () => {
+    const result = await sourceRouteRequest.readSourceMutation({
+      cookieHeader: "session=abc",
+      request: new Request("http://localhost/api/sources/source_1", {
+        method: "PATCH",
+        body: JSON.stringify({ folderId: "folder_1" }),
+      }),
+      sourceId: "source_1",
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      mutation: {
+        kind: "assignFolder",
+        input: {
+          cookieHeader: "session=abc",
+          sourceId: "source_1",
+          folderId: "folder_1",
+        },
+      },
+    });
+  });
+
   it("returns route-ready errors for invalid archive requests", async () => {
     const result = await sourceRouteRequest.readSourceMutation({
       cookieHeader: "",
@@ -59,7 +82,7 @@ describe("sourceRouteRequest", () => {
       result: {
         status: 400,
         body: {
-          message: "Request body must include `archived: true` or `retry: true`.",
+          message: "Request body must include `archived: true`, `retry: true`, or `folderId`.",
         },
       },
     });
diff --git a/src/domains/sources/route-request.ts b/src/domains/sources/route-request.ts
index 46fb057..fdb9df0 100644
--- a/src/domains/sources/route-request.ts
+++ b/src/domains/sources/route-request.ts
@@ -2,6 +2,7 @@ import { Schema } from "effect"
 
 import type {
   ArchiveSourceInput,
+  AssignSourceFolderInput,
   JsonRouteResult,
   RetrySourceInput,
 } from "./route-types"
@@ -35,6 +36,10 @@ type SourceMutationReadResult =
             readonly kind: "retry"
             readonly input: RetrySourceInput
           }
+        | {
+            readonly kind: "assignFolder"
+            readonly input: AssignSourceFolderInput
+          }
     }
   | {
       readonly ok: false
@@ -58,6 +63,10 @@ const RetryRequest = Schema.Struct({
   retry: Schema.Literal(true),
 })
 
+const AssignFolderRequest = Schema.Struct({
+  folderId: Schema.NullOr(Schema.String),
+})
+
 async function readArchiveSource({
   cookieHeader,
   request,
@@ -119,10 +128,36 @@ async function readSourceMutation({
     }
   }
 
+  const assignFolder = Schema.decodeUnknownEither(AssignFolderRequest)(
+    body.value,
+  )
+  if (assignFolder._tag === "Right") {
+    const folderId = assignFolder.right.folderId
+    if (folderId !== null && folderId.trim().length === 0) {
+      return {
+        ok: false,
+        result: routeResult.badRequest(
+          "Request body must include `archived: true`, `retry: true`, or `folderId`.",
+        ),
+      }
+    }
+    return {
+      ok: true,
+      mutation: {
+        kind: "assignFolder",
+        input: {
+          cookieHeader,
+          sourceId,
+          folderId,
+        },
+      },
+    }
+  }
+
   return {
     ok: false,
     result: routeResult.badRequest(
-      "Request body must include `archived: true` or `retry: true`.",
+      "Request body must include `archived: true`, `retry: true`, or `folderId`.",
     ),
   }
 }
diff --git a/src/domains/sources/route-retry.test.ts b/src/domains/sources/route-retry.test.ts
index 5ecba81..b9ff38a 100644
--- a/src/domains/sources/route-retry.test.ts
+++ b/src/domains/sources/route-retry.test.ts
@@ -28,6 +28,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-10T00:00:00.000Z"),
     updatedAt: new Date("2026-05-10T00:00:00.000Z"),
     deletedAt: null,
diff --git a/src/domains/sources/route-service.test.ts b/src/domains/sources/route-service.test.ts
index 35c72dc..bd079b3 100644
--- a/src/domains/sources/route-service.test.ts
+++ b/src/domains/sources/route-service.test.ts
@@ -30,6 +30,7 @@ const source: Source = {
   originalBlobUrl: null,
   demoKey: null,
   chunkCount: null,
+    folderId: null,
   createdAt: new Date("2026-05-10T00:00:00Z"),
   updatedAt: new Date("2026-05-10T00:00:00Z"),
   deletedAt: null,
diff --git a/src/domains/sources/route-service.ts b/src/domains/sources/route-service.ts
index 9a19bef..2281b47 100644
--- a/src/domains/sources/route-service.ts
+++ b/src/domains/sources/route-service.ts
@@ -1,6 +1,7 @@
 import "server-only"
 
 import { createRouteArchive } from "./route-archive"
+import { createRouteAssignFolder } from "./route-assign-folder"
 import { createRouteChunks } from "./route-chunks"
 import { createSourceRouteDependencies } from "./route-dependencies"
 import { createRouteListing } from "./route-listing"
@@ -8,6 +9,7 @@ import { createRouteRetry } from "./route-retry"
 import { createRouteUpload } from "./route-upload"
 import type {
   ArchiveSourceInput,
+  AssignSourceFolderInput,
   ListSourcesInput,
   LoadSourceChunksInput,
   RetrySourceInput,
@@ -24,6 +26,7 @@ export function createSourceRouteService(
   const upload = createRouteUpload(deps)
   const archive = createRouteArchive(deps)
   const retry = createRouteRetry(deps)
+  const assignFolder = createRouteAssignFolder(deps)
   const chunks = createRouteChunks(deps)
 
   return {
@@ -31,6 +34,8 @@ export function createSourceRouteService(
     uploadSource: (input: UploadSourceInput) => upload.uploadSource(input),
     archiveSource: (input: ArchiveSourceInput) => archive.archiveSource(input),
     retrySource: (input: RetrySourceInput) => retry.retrySource(input),
+    assignSourceFolder: (input: AssignSourceFolderInput) =>
+      assignFolder.assignSourceFolder(input),
     loadSourceChunks: (input: LoadSourceChunksInput) =>
       chunks.loadSourceChunks(input),
   }
diff --git a/src/domains/sources/route-types.ts b/src/domains/sources/route-types.ts
index 7907d31..548a8fb 100644
--- a/src/domains/sources/route-types.ts
+++ b/src/domains/sources/route-types.ts
@@ -139,6 +139,20 @@ type RetrySourceInput = {
   readonly sourceId: string
 }
 
+type AssignSourceFolderInput = {
+  readonly cookieHeader: string
+  readonly sourceId: string
+  readonly folderId: string | null
+}
+
+type AssignSourceFolderBody =
+  | {
+      readonly source: SourceView
+    }
+  | {
+      readonly message: string
+    }
+
 type LoadSourceChunksInput = {
   readonly cookieHeader: string
   readonly sourceId: string
@@ -159,6 +173,9 @@ type SourceRouteService = {
   readonly retrySource: (
     input: RetrySourceInput,
   ) => Promise<JsonRouteResult<RetrySourceBody>>
+  readonly assignSourceFolder: (
+    input: AssignSourceFolderInput,
+  ) => Promise<JsonRouteResult<AssignSourceFolderBody>>
   readonly loadSourceChunks: (
     input: LoadSourceChunksInput,
   ) => Promise<JsonRouteResult<SourceChunksBody>>
@@ -260,6 +277,8 @@ type SourceRouteServiceOverrides = Partial<
 export type {
   ArchiveSourceBody,
   ArchiveSourceInput,
+  AssignSourceFolderBody,
+  AssignSourceFolderInput,
   JsonRouteResult,
   ListSourcesBody,
   ListSourcesInput,
diff --git a/src/domains/sources/source-reconcile-workflow.test.ts b/src/domains/sources/source-reconcile-workflow.test.ts
index f5aa7ad..517b0c1 100644
--- a/src/domains/sources/source-reconcile-workflow.test.ts
+++ b/src/domains/sources/source-reconcile-workflow.test.ts
@@ -33,6 +33,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-06T00:00:00Z"),
     updatedAt: new Date("2026-05-06T00:00:00Z"),
     deletedAt: null,
diff --git a/src/domains/sources/source-row-repository.test.ts b/src/domains/sources/source-row-repository.test.ts
index 7693cde..1f58ad6 100644
--- a/src/domains/sources/source-row-repository.test.ts
+++ b/src/domains/sources/source-row-repository.test.ts
@@ -99,6 +99,7 @@ async function captureLocalizeConflictSet(input: {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-06-26T00:00:00Z"),
     updatedAt: new Date("2026-06-26T00:00:00Z"),
     deletedAt: null,
diff --git a/src/domains/sources/source-row-repository.ts b/src/domains/sources/source-row-repository.ts
index d4fc778..a33e5ee 100644
--- a/src/domains/sources/source-row-repository.ts
+++ b/src/domains/sources/source-row-repository.ts
@@ -34,6 +34,7 @@ type SourceUpdate = Partial<
     | "originalBlobPathname"
     | "originalBlobUrl"
     | "chunkCount"
+    | "folderId"
   >
 >
 
@@ -89,6 +90,11 @@ type SourceRowRepository = {
     sourceId: string,
     chunkCount: number,
   ) => Effect.Effect<Source | null, never, DbClient>
+  readonly assignFolderEffect: (
+    workspaceId: string,
+    sourceId: string,
+    folderId: string | null,
+  ) => Effect.Effect<Source | null, never, DbClient>
   readonly markFailedEffect: (
     workspaceId: string,
     sourceId: string,
@@ -248,6 +254,15 @@ const recordChunkCountEffect: SourceRowRepository["recordChunkCountEffect"] = (
     chunkCount,
   }, "ready")
 
+const assignFolderEffect: SourceRowRepository["assignFolderEffect"] = (
+  workspaceId: string,
+  sourceId: string,
+  folderId: string | null,
+) =>
+  updateInWorkspaceEffect(workspaceId, sourceId, {
+    folderId,
+  })
+
 const markFailedEffect: SourceRowRepository["markFailedEffect"] = (
   workspaceId: string,
   sourceId: string,
@@ -473,6 +488,7 @@ export const sourceRowRepository: SourceRowRepository = {
   markReadyEffect,
   updateRevisionKeyEffect,
   recordChunkCountEffect,
+  assignFolderEffect,
   markFailedEffect,
   clearStagedBlobEffect,
   softDeleteEffect,
diff --git a/src/domains/sources/types.ts b/src/domains/sources/types.ts
index e0ff9be..cdfd33a 100644
--- a/src/domains/sources/types.ts
+++ b/src/domains/sources/types.ts
@@ -62,6 +62,8 @@ export type SourceView = {
   readonly officialLibrary?: SourceOfficialLibraryView
   /** Count from the Notebook parsed snapshot manifest when available. */
   readonly chunkCount?: number
+  /** Notebook folder this source sits in. Missing means the workspace root. */
+  readonly folderId?: string
   /**
    * Preferred source content presentation. Missing values are treated as
    * parsed chunks so older views and cached responses remain compatible.
diff --git a/src/domains/sources/upload.test.ts b/src/domains/sources/upload.test.ts
index f217e5b..8939b81 100644
--- a/src/domains/sources/upload.test.ts
+++ b/src/domains/sources/upload.test.ts
@@ -32,6 +32,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-06T00:00:00Z"),
     updatedAt: new Date("2026-05-06T00:00:00Z"),
     deletedAt: null,
diff --git a/src/domains/sources/view.test.ts b/src/domains/sources/view.test.ts
index 9da3e98..c7bdebb 100644
--- a/src/domains/sources/view.test.ts
+++ b/src/domains/sources/view.test.ts
@@ -21,6 +21,7 @@ function makeSource(overrides: Partial<Source> = {}): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-06T00:00:00Z"),
     updatedAt: new Date("2026-05-06T00:00:00Z"),
     deletedAt: null,
@@ -37,6 +38,7 @@ describe("toSourceView", () => {
           originalBlobUrl:
             "https://store.public.blob.vercel-storage.com/source-uploads/upload_1/document.pdf",
           chunkCount: 7,
+          folderId: "folder_1",
         }),
       ),
     ).toEqual({
@@ -47,6 +49,7 @@ describe("toSourceView", () => {
       status: "ready",
       documentId: "doc_1",
       chunkCount: 7,
+      folderId: "folder_1",
       originalFile: {
         url: "https://store.public.blob.vercel-storage.com/source-uploads/upload_1/document.pdf",
         mimeType: "application/pdf",
diff --git a/src/domains/sources/view.ts b/src/domains/sources/view.ts
index bac67e0..a9b5892 100644
--- a/src/domains/sources/view.ts
+++ b/src/domains/sources/view.ts
@@ -38,6 +38,7 @@ export function toSourceView(
     ...(failureMessage ? { failureMessage } : {}),
     ...(originalFile ? { originalFile } : {}),
     ...(chunkCount !== undefined ? { chunkCount } : {}),
+    ...(source.folderId ? { folderId: source.folderId } : {}),
     ...(options.documentPresentation !== undefined
       ? { documentPresentation: options.documentPresentation }
       : {}),
diff --git a/src/domains/sources/workflow-runtime.test.ts b/src/domains/sources/workflow-runtime.test.ts
index 785e781..2d34152 100644
--- a/src/domains/sources/workflow-runtime.test.ts
+++ b/src/domains/sources/workflow-runtime.test.ts
@@ -40,6 +40,7 @@ function makeSource(status: Source["status"]): Source {
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-10T00:00:00.000Z"),
     updatedAt: new Date("2026-05-10T00:00:00.000Z"),
     deletedAt: null,
diff --git a/src/domains/sources/workflow-runtime.ts b/src/domains/sources/workflow-runtime.ts
index 376dda6..ba428de 100644
--- a/src/domains/sources/workflow-runtime.ts
+++ b/src/domains/sources/workflow-runtime.ts
@@ -100,6 +100,11 @@ type SourceWorkflowRuntime = UploadRepositoryRuntime & {
     sourceId: string,
     chunkCount: number,
   ) => Promise<Source | null>
+  readonly assignFolder: (
+    workspaceId: string,
+    sourceId: string,
+    folderId: string | null,
+  ) => Promise<Source | null>
   readonly saveParseResult: (
     workspaceId: string,
     sourceId: string,
@@ -224,6 +229,15 @@ const recordChunkCount: SourceWorkflowRuntime["recordChunkCount"] = (
     ),
   )
 
+const assignFolder: SourceWorkflowRuntime["assignFolder"] = (
+  workspaceId: string,
+  sourceId: string,
+  folderId: string | null,
+) =>
+  databaseRuntime.runPromise(
+    sourceRepository.assignFolderEffect(workspaceId, sourceId, folderId),
+  )
+
 const markFailed: SourceWorkflowRuntime["markFailed"] = (
   workspaceId: string,
   sourceId: string,
@@ -360,6 +374,7 @@ export const sourceWorkflowRuntime: SourceWorkflowRuntime = {
   markReady,
   updateRevisionKey,
   recordChunkCount,
+  assignFolder,
   mergeParseAssetUrls,
   saveParseResult,
   softDelete,
diff --git a/src/domains/workspace/client.ts b/src/domains/workspace/client.ts
index 1f6fbf4..2a30edf 100644
--- a/src/domains/workspace/client.ts
+++ b/src/domains/workspace/client.ts
@@ -4,6 +4,7 @@ import type {
   ChatThreadView,
 } from "@/domains/chat/types"
 import type { ParsedChunkView } from "@/domains/chunks/types"
+import type { FolderView } from "@/domains/folders/types"
 import type {
   SourceView,
 } from "@/domains/sources/types"
@@ -15,8 +16,10 @@ const workspaceClientKeys = {
   chatDiagram: "/api/chat/diagram",
   chat: "/api/chat",
   materializeDemoSources: "/api/demo-sources/materialize",
+  folders: "/api/folders",
   archiveSource: "archive-source",
   retrySource: "retry-source",
+  assignSourceFolder: "assign-source-folder",
   archiveChatThread: "archive-chat-thread",
 } as const
 
@@ -57,6 +60,7 @@ type ChatMessageRequest = {
   threadId?: string
   useAgentic: boolean
   excludedSourceIds: string[]
+  folderId?: string
 }
 
 type MaterializeDemoSourcesRequest = {
@@ -67,6 +71,25 @@ type SourcesResponse = {
   sources?: SourceView[]
 }
 
+type FoldersResponse = {
+  folders?: FolderView[]
+}
+
+type FolderResponse = {
+  folder?: FolderView
+  message?: string
+}
+
+type CreateFolderRequest = {
+  name: string
+  parentId: string | null
+}
+
+type UpdateFolderRequest = {
+  name?: string
+  parentId?: string | null
+}
+
 type ChatThreadsResponse = {
   threads?: ChatThreadView[]
 }
@@ -101,6 +124,11 @@ export const workspaceClient = {
   fetchChunks,
   fetchChunkPage,
   fetchSources,
+  fetchFolders,
+  createFolder,
+  updateFolder,
+  deleteFolder,
+  assignSourceFolder,
   fetchChatThreads,
   fetchChatThread,
   createChatThread,
@@ -303,3 +331,61 @@ function archiveChatThread(threadId: string): Promise<ArchiveResponse> {
     },
   )
 }
+
+async function fetchFolders(): Promise<FolderView[]> {
+  const body = await workspaceRouteClient.getJson<FoldersResponse>(
+    workspaceClientKeys.folders,
+  )
+  return Array.isArray(body.folders) ? body.folders : []
+}
+
+async function createFolder(
+  input: CreateFolderRequest,
+): Promise<FolderView> {
+  const response = await workspaceRouteClient.postJsonWithStatus<FolderResponse>(
+    workspaceClientKeys.folders,
+    input,
+  )
+  if (response.status < 200 || response.status >= 300 || !response.body.folder) {
+    throw new Error(response.body.message ?? "Folder could not be created.")
+  }
+  return response.body.folder
+}
+
+async function updateFolder(
+  folderId: string,
+  input: UpdateFolderRequest,
+): Promise<FolderView> {
+  const response = await workspaceRouteClient.patchJsonWithStatus<FolderResponse>(
+    `/api/folders/${encodeURIComponent(folderId)}`,
+    input,
+  )
+  if (response.status < 200 || response.status >= 300 || !response.body.folder) {
+    throw new Error(response.body.message ?? "Folder could not be updated.")
+  }
+  return response.body.folder
+}
+
+async function deleteFolder(folderId: string): Promise<void> {
+  const body = await workspaceRouteClient.deleteJson<{
+    readonly archived?: boolean
+    readonly message?: string
+  }>(`/api/folders/${encodeURIComponent(folderId)}`, {})
+  if (body.archived !== true) {
+    throw new Error(body.message ?? "Folder could not be deleted.")
+  }
+}
+
+async function assignSourceFolder(
+  sourceId: string,
+  folderId: string | null,
+): Promise<SourceView> {
+  const response = await workspaceRouteClient.patchJsonWithStatus<RetrySourceResponse>(
+    `/api/sources/${encodeURIComponent(sourceId)}`,
+    { folderId },
+  )
+  if (response.status < 200 || response.status >= 300 || !response.body.source) {
+    throw new Error(response.body.message ?? "Source could not be moved.")
+  }
+  return response.body.source
+}
diff --git a/src/domains/workspace/initial-state.test.ts b/src/domains/workspace/initial-state.test.ts
index 67d8b8a..405bfe7 100644
--- a/src/domains/workspace/initial-state.test.ts
+++ b/src/domains/workspace/initial-state.test.ts
@@ -490,6 +490,7 @@ function createDependencies(
     listChatThreads: vi.fn(async () => []),
     listHiddenDemoSourceIds: vi.fn(async () => []),
     listMessages: vi.fn(async () => []),
+    listFoldersForWorkspace: vi.fn(async () => []),
     listSourcesForWorkspace: vi.fn(async () => []),
     reconcileSourcesForWorkspace: vi.fn(async () => []),
     ...overrides,
@@ -615,6 +616,7 @@ function makeSource(
     originalBlobUrl: null,
     demoKey: null,
     chunkCount: null,
+    folderId: null,
     createdAt: new Date("2026-05-10T00:00:00.000Z"),
     updatedAt: new Date("2026-05-10T00:00:00.000Z"),
     deletedAt: null,
diff --git a/src/domains/workspace/initial-state.ts b/src/domains/workspace/initial-state.ts
index 7e7e040..3d6ce4d 100644
--- a/src/domains/workspace/initial-state.ts
+++ b/src/domains/workspace/initial-state.ts
@@ -16,6 +16,9 @@ import {
 } from "@/domains/sources/background-reconcile"
 import { sourceWorkflowRuntime } from "@/domains/sources/workflow-runtime"
 
+import { toFolderView } from "@/domains/folders/tree"
+import type { FolderView } from "@/domains/folders/types"
+import { folderWorkflowRuntime } from "@/domains/folders/workflow-runtime"
 import type {
   OfficialLibrarySourceView,
   SourceView,
@@ -25,6 +28,7 @@ import type { AuthUser } from "@/infrastructure/auth"
 import type {
   ChatMessage,
   ChatThread,
+  Folder,
   Source,
   Workspace,
 } from "@/infrastructure/db/schema"
@@ -46,6 +50,7 @@ type WorkspaceShellInitialState = {
   readonly isGuest?: boolean
   readonly loginUrl?: string
   readonly officialLibrarySources?: OfficialLibrarySourceView[]
+  readonly folders?: FolderView[]
   readonly sources?: SourceView[]
   readonly user?: {
     readonly id: string
@@ -132,6 +137,9 @@ type WorkspaceShellInitialStateDependencies = {
     workspaceId: string,
     threadId: string,
   ) => Promise<readonly ChatMessage[] | null>
+  readonly listFoldersForWorkspace: (
+    workspaceId: string,
+  ) => Promise<readonly Folder[]>
   readonly listSourcesForWorkspace: (
     workspaceId: string,
   ) => Promise<readonly Source[]>
@@ -151,6 +159,7 @@ const defaultDependencies: WorkspaceShellInitialStateDependencies = {
   listChatThreads: chatThreadService.listForWorkspace,
   listHiddenDemoSourceIds: sourceService.listHiddenDemoSourceIds,
   listMessages: chatThreadService.listMessages,
+  listFoldersForWorkspace: folderWorkflowRuntime.listForWorkspace,
   listSourcesForWorkspace: sourceWorkflowRuntime.listForWorkspace,
   reconcileSourcesForWorkspace: reconcileDefaultSourcesForWorkspace,
   startBackgroundReconciliation: defaultStartBackgroundReconciliation,
@@ -214,6 +223,7 @@ export const loadWorkspaceShellInitialStateEffect = (
       return {
         isGuest: true,
         officialLibrarySources: toOfficialLibrarySourceViews(demoCatalog),
+        folders: [],
         sources: demoCatalog.sources.map(demoView.toSourceView),
         chatMessages: demoView.toChatMessages(demoCatalog),
         dashboardUrl: resolveDashboardUrl(),
@@ -230,6 +240,13 @@ export const loadWorkspaceShellInitialStateEffect = (
       },
       () => knowhereDemoApi.fetchOptionalCatalog(deps.fetchDemoCatalog),
     )
+    const listedFolders = yield* effectOperation.tryPromise(
+      {
+        context: workspaceInitialStateContext,
+        operation: "listFoldersForWorkspace",
+      },
+      () => deps.listFoldersForWorkspace(workspace.id),
+    )
     const listedSources = yield* effectOperation.tryPromise(
       {
         context: workspaceInitialStateContext,
@@ -348,6 +365,7 @@ export const loadWorkspaceShellInitialStateEffect = (
         ...remoteSourceViews,
       ],
       officialLibrarySources: toOfficialLibrarySourceViews(demoCatalog),
+      folders: listedFolders.map(toFolderView),
       chatThreads: chatThreads.map(toChatThreadView),
       activeChatThreadId: activeChatThread?.id ?? null,
       chatMessages,
diff --git a/src/infrastructure/db/schema.ts b/src/infrastructure/db/schema.ts
index 8a8466c..1ef8c9c 100644
--- a/src/infrastructure/db/schema.ts
+++ b/src/infrastructure/db/schema.ts
@@ -1,5 +1,6 @@
 import { sql } from "drizzle-orm";
 import {
+  type AnyPgColumn,
   bigint,
   index,
   integer,
@@ -56,6 +57,49 @@ export const workspaces = pgTable(
 export type Workspace = typeof workspaces.$inferSelect;
 export type NewWorkspace = typeof workspaces.$inferInsert;
 
+/**
+ * Notebook-owned folder tree for organizing workspace sources.
+ *
+ * Folders are an optional path used by the sidebar and by chat retrieval
+ * scope. Knowhere never sees folder rows; retrieval converts a folder
+ * (and its descendants) into document IDs.
+ *
+ * `parent_id` is null at the workspace root. Rename/move do not rewrite
+ * a materialized path string — readers walk the adjacency list.
+ */
+export const folders = pgTable(
+  "folders",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    workspaceId: uuid("workspace_id")
+      .notNull()
+      .references(() => workspaces.id, { onDelete: "cascade" }),
+    parentId: uuid("parent_id").references((): AnyPgColumn => folders.id, {
+      onDelete: "restrict",
+    }),
+    name: text("name").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    deletedAt: timestamp("deleted_at", { withTimezone: true }),
+  },
+  (t) => [
+    index("folders_workspace_parent_idx").on(t.workspaceId, t.parentId),
+    uniqueIndex("folders_workspace_parent_name_idx")
+      .on(t.workspaceId, t.parentId, t.name)
+      .where(sql`deleted_at IS NULL AND parent_id IS NOT NULL`),
+    uniqueIndex("folders_workspace_root_name_idx")
+      .on(t.workspaceId, t.name)
+      .where(sql`deleted_at IS NULL AND parent_id IS NULL`),
+  ],
+);
+
+export type Folder = typeof folders.$inferSelect;
+export type NewFolder = typeof folders.$inferInsert;
+
 /**
  * One row per user-uploaded source. The row is the Notebook-owned record
  * of a Knowhere parse + index job; the actual chunks / file bytes live
@@ -82,6 +126,9 @@ export type NewWorkspace = typeof workspaces.$inferInsert;
  *   - `chunk_count`  — Knowhere document total written when parse completes
  *                      (or when a demo is materialized); homepage reads this
  *                      locally and does not refetch chunks for the sidebar
+ *   - `folder_id`    — optional Notebook folder; null means the source sits
+ *                      at the workspace root. Demo, Official Library, and
+ *                      remote rows stay unfiled in v1.
  *   - `deleted_at`   — soft delete timestamp; reads filter it out
  *
  * Indexes:
@@ -110,6 +157,9 @@ export const sources = pgTable(
     originalBlobUrl: text("original_blob_url"),
     demoKey: text("demo_key"),
     chunkCount: integer("chunk_count"),
+    folderId: uuid("folder_id").references(() => folders.id, {
+      onDelete: "set null",
+    }),
     createdAt: timestamp("created_at", { withTimezone: true })
       .notNull()
       .defaultNow(),
@@ -127,6 +177,9 @@ export const sources = pgTable(
     uniqueIndex("sources_workspace_document_idx")
       .on(t.workspaceId, t.knowhereDocumentId)
       .where(sql`knowhere_document_id IS NOT NULL AND deleted_at IS NULL`),
+    index("sources_workspace_folder_idx")
+      .on(t.workspaceId, t.folderId)
+      .where(sql`deleted_at IS NULL`),
   ],
 );