feat(knowledge): export knowledge bases as bundle archives (#7620)

* feat(knowledge): export knowledge bases as bundle archives

Adds a streaming zip export for a knowledge base across the v2 API, the
internal API, the CLI, and the UI. The bundle carries the base's
configuration and tag definitions, each workspace-visible document's original
file and chunk text, and optionally the chunk vectors so an import into a
deployment with the same embedding model can reuse them. Access-control lists,
connector links, credentials, uploader identity, and storage keys never leave.

- knowledge.export operation gated by a new Knowledge Base Export permission
  group setting; exports record an audit event
- entries are appended one at a time so a large base never fans out storage
  reads and the manifest is written last with the counts actually produced
- sim knowledge export <knowledgeBaseId> --output-file kb.zip [--no-vectors]
- Export in the knowledge base row menu and base page header

* fix(knowledge): expose authorize on knowledge use cases and gate export on describable bundles

- defineAuthorizedKnowledgeUseCase now answers authorize() through the same
  resolution execute() uses, which headSafe: false routes require at module
  init; defineAuthorizedWorkspaceUseCase's return type states that authorize
  is always present
- the export use case validates the stored base against the bundle manifest
  schema before any byte streams, so a value the import side would refuse
  surfaces as a 409 rather than a truncated archive
- Export is hidden in the base menu and header when a permission group
  withholds knowledge.export
- operations id snapshot includes knowledge.export

* chore(docs): count the knowledge export path in the OpenAPI download test

* improvement(knowledge): read inline document payloads lazily and scope chunk reads to the base

Follow-ups from an independent review pass over the export path.

- the document listing no longer selects fileUrl: a data: document can hold
  megabytes in that column, so the listing carries a flag and the archive
  reads one payload at a time when it reaches that entry
- iterateDocumentChunks filters on knowledgeBaseId as well as documentId, so
  a future caller cannot reach another base's chunks through the bundle
- tag definitions are validated by the single bundle gate, which answers 409
  like every other undescribable value rather than throwing a bare ZodError
- a consumer that abandons the download aborts the append loop and destroys
  the in-flight source instead of leaving it pending
- direct tests for the knowledge use-case builder's authorize() on the
  workspace, organization, and legacy personal branches

* improvement(knowledge): validate stored chunk counts and scope inline reads to the base

- the bundle gate checks each document's stored chunk count against the
  format's per-document ceiling, so a base holding more chunks than a bundle
  can describe is refused up front rather than written into an invalid manifest
- the inline payload read carries its knowledge base id, matching the chunk
  reads, so neither can reach a row outside the base being exported
- an append is refused once the consumer has aborted, since a destroyed
  archive has no listener left to receive the error it would emit

* improvement(knowledge): bound the streamed chunks and validate the written manifest

Findings from a reuse, simplification, efficiency, and altitude review.

- the chunk stream stops at the per-document ceiling and raises afterwards, and
  the manifest that actually ships is the one validated: chunkCount is
  denormalized, so a document re-chunked mid-export could previously pass the
  pre-flight gate and land in a manifest no importer would accept
- a real archive failure is no longer mistaken for the consumer walking away;
  archiver emits close for both, so only the abort's own error is swallowed
- the inline-file probe reads a 5-byte prefix instead of matching the whole
  column, which was detoasting every document's fileUrl and defeating the
  optimization the listing exists for
- storedChunkCount replaces the redundant hasChunks pair
- the CLI reads the RFC 5987 filename first, so a knowledge base named
  "Suporte tecnico" no longer saves under a mangled ASCII name
- drops three bundle ceilings the import half will introduce, breaks a
  circular type import, and states the authorize guarantee in the type so a
  headSafe route is proven at compile time rather than at module load

Author: waleedlatif1

apps/docs/content/docs/cli/knowledge.mdx

@@ -1099,6 +1099,34 @@ sim knowledge mv <knowledgeBaseId> <folder>
 
 </CommandTable>
 
+## Export a knowledge base as a .simkb.zip bundle
+
+```bash
+sim knowledge export <knowledgeBaseId> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `knowledgeBaseId` | Yes | Knowledge base to export |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `-o, --output-file <path>` | No | Write the bundle to this path instead of the name the server suggests; pass - to stream it to stdout. |
+| `--force` | No | Overwrite --output-file if it already exists. |
+| `--no-vectors` | No | Leave chunk vectors out of the bundle, so an import re-embeds every chunk. |
+
+</CommandTable>
+
 ## List knowledge resources and child folders together
 
 ```bash

apps/docs/content/docs/cli/reference.mdx

@@ -2405,6 +2405,36 @@ sim knowledge mv <knowledgeBaseId> <folder>
 
 </CommandTable>
 
+### sim knowledge export
+
+Export a knowledge base as a .simkb.zip bundle
+
+```bash
+sim knowledge export <knowledgeBaseId> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `knowledgeBaseId` | Yes | Knowledge base to export |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `-o, --output-file <path>` | No | Write the bundle to this path instead of the name the server suggests; pass - to stream it to stdout. |
+| `--force` | No | Overwrite --output-file if it already exists. |
+| `--no-vectors` | No | Leave chunk vectors out of the bundle, so an import re-embeds every chunk. |
+
+</CommandTable>
+
 ### sim knowledge ls
 
 List knowledge resources and child folders together

apps/docs/content/docs/knowledgebase/export-import.mdx

@@ -0,0 +1,63 @@
+---
+title: Export
+description: Download a knowledge base as one archive of its documents, chunks, tags, and settings.
+---
+
+An **export** is a single archive that holds a knowledge base: every document, the chunks Sim split it into, the tag definitions and values, and the chunking settings. Use it to keep a copy of a base outside Sim.
+
+To export, right-click a base in the knowledge base list and choose **Export**, or open the base and click the **Export** button in the header. The download is named `<base name>.simkb.zip`.
+
+## What the archive contains
+
+```text
+<base name>.simkb.zip
+├── manifest.json
+├── files/
+│   └── <documentId>/<filename>
+└── chunks/
+    └── <documentId>.ndjson
+```
+
+- **`manifest.json`** describes the export (format version 1): the base name, description, and chunking config; the embedding model and dimension and whether vectors are included; the tag definitions; and a document list with each document's filename, MIME type, size, enabled flag, tag values, entry paths, and chunk, token, and character counts.
+- **`files/`** holds each document's original file, when it has one.
+- **`chunks/`** holds one NDJSON file per document, with one JSON line per chunk: its index, content, token count, start and end offsets, enabled flag, and the vector when vectors are included.
+
+The export includes every document a workspace member can read, its file and its chunk text. Documents synced from a [connector](/knowledgebase/connectors) export as plain documents: their text and, where Sim stored it, their file.
+
+## What stays behind
+
+An export never includes:
+
+- Access-control lists
+- Connector links and credentials
+- Who uploaded each document
+- Internal storage keys
+
+Organization-wide search indexes cannot be exported.
+
+## Vectors
+
+Vectors are embeddings, the numbers a model produces so search can compare chunks. They are included by default. Each chunk's vector is stored as base64-encoded float32 values in its NDJSON line.
+
+Vectors are only valid for a deployment that uses the same embedding model and dimension. The manifest records both for the base you exported. To skip vectors, set `vectors=false` on the API or pass `--no-vectors` to the CLI.
+
+## Limits and governance
+
+A base with more than 2,000 documents cannot be exported. The request returns `413`.
+
+Organization admins can withhold export through the permission group setting **Knowledge Base Export** (enterprise). Every export records an audit event.
+
+## API
+
+```http
+GET /api/v2/knowledge/{knowledgeBaseId}/export?workspaceId={workspaceId}&vectors=true
+```
+
+The response is the archive. See the [API reference](/api-reference/getting-started) for authentication.
+
+## CLI
+
+```bash
+sim knowledge export <knowledgeBaseId> --output-file kb.zip
+sim knowledge export <knowledgeBaseId> --output-file kb.zip --no-vectors
+```

apps/docs/content/docs/knowledgebase/meta.json

@@ -5,6 +5,7 @@
     "connectors",
     "tags",
     "debugging-retrieval",
-    "chunking-strategies"
+    "chunking-strategies",
+    "export-import"
   ]
 }

apps/docs/lib/openapi-download.test.ts

@@ -33,7 +33,7 @@ describe('OpenAPI download', () => {
     const tags = document.tags as Array<{ name: string }>
 
     expect(document.openapi).toBe('3.1.0')
-    expect(Object.keys(paths)).toHaveLength(132)
+    expect(Object.keys(paths)).toHaveLength(133)
     expect(tags.map((tag) => tag.name)).toEqual([
       'Workflows',
       'Workflow Runs',

apps/docs/openapi-v2-knowledge.json

@@ -502,6 +502,105 @@
         }
       }
     },
+    "/api/v2/knowledge/{knowledgeBaseId}/export": {
+      "get": {
+        "operationId": "exportKnowledgeBase",
+        "summary": "Export Knowledge Base",
+        "description": "Stream a knowledge base as a bundle archive: its configuration, tag definitions, each workspace-visible document's file and chunk text, and optionally chunk vectors. Access-control lists, connector links, and credentials never leave. More than 2000 documents returns `413`. Exports record an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length`; use file metadata to size downloads.\n\nOAuth scope: `api:read`.",
+        "x-sim-operation": "knowledge.export",
+        "x-oauth-scope": "api:read",
+        "tags": ["Knowledge Bases"],
+        "parameters": [
+          {
+            "name": "knowledgeBaseId",
+            "in": "path",
+            "required": true,
+            "description": "Unique knowledge base identifier.",
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Unique knowledge base identifier."
+            }
+          },
+          {
+            "name": "workspaceId",
+            "in": "query",
+            "required": true,
+            "description": "Workspace that owns the knowledge base.",
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128,
+              "description": "Workspace that owns the knowledge base."
+            }
+          },
+          {
+            "name": "vectors",
+            "in": "query",
+            "required": false,
+            "description": "Include chunk vectors so an import into a deployment with the same embedding model reuses them instead of re-embedding.",
+            "schema": {
+              "description": "Include chunk vectors so an import into a deployment with the same embedding model reuses them instead of re-embedding.",
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The knowledge base as a zip archive.",
+            "headers": {
+              "Content-Type": {
+                "$ref": "#/components/headers/Content-Type"
+              },
+              "Content-Disposition": {
+                "$ref": "#/components/headers/Content-Disposition"
+              },
+              "X-RateLimit-Limit": {
+                "$ref": "#/components/headers/X-RateLimit-Limit"
+              },
+              "X-RateLimit-Remaining": {
+                "$ref": "#/components/headers/X-RateLimit-Remaining"
+              },
+              "X-RateLimit-Reset": {
+                "$ref": "#/components/headers/X-RateLimit-Reset"
+              }
+            },
+            "content": {
+              "application/zip": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "413": {
+            "$ref": "#/components/responses/PayloadTooLarge"
+          },
+          "429": {
+            "$ref": "#/components/responses/RateLimited"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalError"
+          },
+          "503": {
+            "$ref": "#/components/responses/ServiceUnavailable"
+          }
+        }
+      }
+    },
     "/api/v2/knowledge/{knowledgeBaseId}/connectors": {
       "get": {
         "operationId": "listKnowledgeConnectors",
@@ -4339,6 +4438,31 @@
       }
     },
     "headers": {
+      "Content-Type": {
+        "description": "MIME type of the file, defaulting to application/octet-stream when the stored type is unavailable.",
+        "schema": {
+          "type": "string",
+          "title": "Content type",
+          "description": "MIME type of the file, defaulting to application/octet-stream when the stored type is unavailable."
+        }
+      },
+      "Content-Disposition": {
+        "description": "Attachment disposition containing sanitized and RFC 5987 encoded filenames.",
+        "schema": {
+          "type": "string",
+          "title": "Content disposition",
+          "description": "Attachment disposition containing sanitized and RFC 5987 encoded filenames."
+        }
+      },
+      "Content-Length": {
+        "description": "File size in bytes.",
+        "schema": {
+          "type": "string",
+          "pattern": "^(0|[1-9]\\d*)$",
+          "title": "Content length",
+          "description": "File size in bytes."
+        }
+      },
       "X-RateLimit-Limit": {
         "description": "Maximum requests allowed in the current window.",
         "schema": {