Dev

docs/features/authentication-access/rbac/groups.md

@@ -84,3 +84,18 @@ For example, granting the "Marketing" group read access and a specific editor us
 
 *   **Read**: Users can view and use the resource.
 *   **Write**: Users can update or delete the resource.
+
+### Previewing Access (Audit)
+
+When access grants span many groups and resources, it's easy to lose track of who can see what. Open WebUI ships an admin-only **Preview Access** view that resolves every access grant for a specific user or group and lists the result in one place — no need to crawl through individual resource pages.
+
+**For a user** — In **Admin Panel > Users**, hover over a non-admin user row and click the eye-style **Preview Access** button. The modal shows every model, knowledge base, and tool the user can read, aggregated across all of their group memberships and any direct user grants.
+
+**For a group** — In **Admin Panel > Users > Groups**, open the group editor and use the **Preview Group Access** panel. The output is the same shape (models, knowledge, tools), scoped to just that group's grants.
+
+Both views are admin-only and read-only — they reflect what the access-grant table currently says without modifying it. Use them after a permission change to confirm the result matches intent, or as part of a periodic RBAC audit.
+
+Programmatic equivalents:
+
+- `GET /api/v1/users/{user_id}/preview` — user view (admin auth required)
+- `GET /api/v1/groups/id/{id}/preview` — group view (admin auth required)

docs/features/extensibility/plugin/tools/index.mdx

@@ -229,8 +229,10 @@ Default Mode is **not** a supported workaround even for DeepSeek — it is legac
 | `search_knowledge_bases` | Text search over KB names/descriptions. |
 | `query_knowledge_files` | Search file contents via the RAG retrieval pipeline (hybrid + rerank when enabled). Main tool for finding answers in docs. |
 | `search_knowledge_files` | Search files by filename. |
-| `view_file` | Read a user-accessible file by ID with pagination (`offset`, `max_chars`). |
+| `grep_knowledge_files` | Exact text / regex search across knowledge file content. Returns matching lines with line numbers. Complements `query_knowledge_files` (semantic) when you need literal matches. |
+| `view_file` | Read a user-accessible file by ID with character pagination (`offset`, `max_chars`) or line range (`start_line`, `end_line`, optional `line_numbers`). |
 | `view_knowledge_file` | Read a knowledge-base file by ID with pagination (`offset`, `max_chars`). |
+| `kb_exec` *(opt-in)* | Filesystem-style command interface for knowledge bases (`ls`, `tree`, `cat`, `head`, `tail`, `sed`, `grep`, `find`, `wc`, `stat`, with pipe support). Directory-aware: `ls docs/`, `tree`, `grep "x" docs/`, and path-based file refs (`docs/api/auth.md`). Replaces the discovery/read tools above when [`ENABLE_KB_EXEC`](/reference/env-configuration#enable_kb_exec) is set. |
 | **Image Gen** | *Requires image generation enabled (per-tool) AND per-chat "Image Generation" toggle enabled.* |
 | `generate_image` | Generates a new image based on a prompt. Requires `ENABLE_IMAGE_GENERATION`. |
 | `edit_image` | Edits existing images based on a prompt and image URLs. Requires `ENABLE_IMAGE_EDIT`. |
@@ -287,12 +289,17 @@ Use this quick matrix instead of memorizing per-row caveats.
 | `query_knowledge_bases` | ❌ | ✅ |
 | `search_knowledge_files` | ✅ (auto-scoped) | ✅ (all accessible KBs) |
 | `query_knowledge_files` | ✅ (auto-scoped) | ✅ |
+| `grep_knowledge_files` | ✅ (auto-scoped) | ✅ |
 | `view_file` | ✅ (when attached items include files/collections) | ❌ |
 | `view_knowledge_file` | ✅ (when attached items include files/collections) | ✅ |
 | `view_note` | ✅ (when attached items include notes) | ❌ |
 
 Quick rule: `list_knowledge` and `list_knowledge_bases` are mutually exclusive.
 
+:::info `kb_exec` replaces the matrix when enabled
+When [`ENABLE_KB_EXEC`](/reference/env-configuration#enable_kb_exec) is set, Open WebUI injects `kb_exec` instead of the file-oriented tools listed above. Still injected alongside it: `query_knowledge_files` (always), `view_note` (when notes are attached), and `query_knowledge_bases` + `search_knowledge_bases` (when no KB is attached). The model interacts with files through familiar shell commands. See the [Knowledge feature page](/features/workspace/knowledge#filesystem-style-access-kb_exec) for details.
+:::
+
 #### Tool Reference
 
 | Tool | Parameters | Output |
@@ -307,8 +314,10 @@ Quick rule: `list_knowledge` and `list_knowledge_bases` are mutually exclusive.
 | `search_knowledge_bases` | `query` (required), `count` (default: 5), `skip` (default: 0) | Array of `{id, name, description, file_count}` |
 | `query_knowledge_files` | `query` (required), `knowledge_ids` (optional), `count` (default: 5) | Array of chunks like `{content, source, file_id, distance?}`; note hits include `{note_id, type: "note"}` |
 | `search_knowledge_files` | `query` (required), `knowledge_id` (optional), `count` (default: 5), `skip` (default: 0) | Array of `{id, filename, knowledge_id, knowledge_name}` |
-| `view_file` | `file_id` (required), `offset` (default: 0), `max_chars` (default: 10000, cap: 100000) | `{id, filename, content, updated_at, created_at}` — includes `truncated`, `total_chars`, `next_offset` when paginated |
+| `grep_knowledge_files` | `pattern` (required; regex auto-detected), `file_id` (optional — single-file mode), `case_insensitive` (default: false), `count_only` (default: false) | Matching lines with file IDs, filenames, and 1-indexed line numbers (capped at 50 matches) |
+| `view_file` | `file_id` (required), `offset` (default: 0), `max_chars` (default: 10000, cap: 100000), `line_numbers` (default: false), `start_line` / `end_line` (optional — line-based addressing overrides `offset`/`max_chars`) | `{id, filename, content, updated_at, created_at}` — includes `truncated`, `total_chars`, `next_offset` when paginated, or `total_lines`, `showing_lines`, `next_start_line` in line mode |
 | `view_knowledge_file` | `file_id` (required), `offset` (default: 0), `max_chars` (default: 10000, cap: 100000) | `{id, filename, content, knowledge_id, knowledge_name}` — includes pagination metadata when truncated |
+| `kb_exec` | `command` (required) — filesystem-style command: `ls` (root) / `ls <dir>/` / `ls -a` (flat with paths), `tree` / `tree <dir>/`, `cat -n <file>`, `head -N <file>`, `tail -N <file>`, `sed -n '<a>,<b>p' <file>`, `grep [-i\|-l\|-c] "<pattern>" [<dir>/\|<file>\|*.ext]`, `find [<dir>/] "<glob>"`, `wc <file>`, `stat <file>`; supports pipes (`grep "auth" \| head -5`); files referenced by path (`docs/api/auth.md`), filename, or file ID | Plain text command output (matches/listing/tree/file content as appropriate) |
 | **Image Gen** | | |
 | `generate_image` | `prompt` (required) | `{status, message, images}` — auto-displayed |
 | `edit_image` | `prompt` (required), `image_urls` (required) | `{status, message, images}` — auto-displayed |
@@ -443,7 +452,7 @@ When the **Builtin Tools** capability is enabled, you can further control which
 | **Memory** | `search_memories`, `add_memory`, `replace_memory_content`, `delete_memory`, `list_memories` | Search and manage user memories |
 | **Chat History** | `search_chats`, `view_chat` | Search and view user chat history |
 | **Notes** | `search_notes`, `view_note`, `write_note`, `replace_note_content` | Search, view, and manage user notes |
-| **Knowledge Base** | `list_knowledge`, `list_knowledge_bases`, `search_knowledge_bases`, `query_knowledge_bases`, `search_knowledge_files`, `query_knowledge_files`, `view_file`, `view_knowledge_file` | Browse and query knowledge bases |
+| **Knowledge Base** | `list_knowledge`, `list_knowledge_bases`, `search_knowledge_bases`, `query_knowledge_bases`, `search_knowledge_files`, `query_knowledge_files`, `grep_knowledge_files`, `view_file`, `view_knowledge_file` (or `kb_exec` + `query_knowledge_files` + `view_note`/`query_knowledge_bases`/`search_knowledge_bases` as applicable when [`ENABLE_KB_EXEC`](/reference/env-configuration#enable_kb_exec) is set) | Browse and query knowledge bases |
 | **Web Search** | `search_web`, `fetch_url` | Search the web and fetch URL content |
 | **Image Generation** | `generate_image`, `edit_image` | Generate and edit images |
 | **Code Interpreter** | `execute_code` | Execute code in a sandboxed environment |

docs/features/workspace/knowledge.md

@@ -42,6 +42,7 @@ Attach specific knowledge bases to a model so it only searches what's relevant.
 | 📑 **5 extraction engines** | Tika, Docling, Azure, Mistral OCR, custom loaders |
 | 🤖 **Agentic retrieval** | Models browse, search, and read your documents autonomously |
 | 📄 **Full context mode** | Inject entire documents with no chunking |
+| 🗂️ **Nested directories** | Organize files into subdirectories with drag-and-drop reordering |
 | 📦 **Export and API** | Back up knowledge bases as zip files, manage via REST API |
 
 ---
@@ -76,12 +77,93 @@ With [native function calling](/features/extensibility/plugin/tools#tool-calling
 | `query_knowledge_bases` | ❌ | ✅ | Search KB names/descriptions by semantic similarity |
 | `search_knowledge_files` | ✅ (scoped) | ✅ (all) | Search files by filename |
 | `query_knowledge_files` | ✅ (scoped) | ✅ | Search file contents using the RAG pipeline |
-| `view_file` | ✅ | ❌ | Read file content with pagination (default 10K chars, cap 100K) |
+| `grep_knowledge_files` | ✅ (scoped) | ✅ | Exact text / regex search across knowledge files (returns matching lines with line numbers; auto-detects regex like `error|warn`) |
+| `view_file` | ✅ | ❌ | Read file content with pagination (`offset`/`max_chars`) or by line range (`start_line`/`end_line`, optional `line_numbers`) |
 | `view_knowledge_file` | ✅ | ✅ | Read file content from any accessible KB |
 | `view_note` | ✅ | ❌ | Read attached notes |
 
 The key split: `list_knowledge` and `list_knowledge_bases` are mutually exclusive. Attaching a KB scopes the model to only those documents. Leaving it unscoped lets the model discover everything the user has access to.
 
+#### When to prefer `grep_knowledge_files` over `query_knowledge_files`
+
+The two search tools complement each other:
+
+| | `query_knowledge_files` | `grep_knowledge_files` |
+|---|---|---|
+| **How it matches** | Semantic / vector retrieval (with optional BM25 + rerank when [`ENABLE_RAG_HYBRID_SEARCH`](/reference/env-configuration#enable_rag_hybrid_search) is on) | Exact string match — regex auto-detected (e.g. `error\|warn`, `version \d+`) |
+| **Returns** | Relevant chunks of content | Matching lines with file ID, filename, and 1-indexed line number |
+| **Use when** | "What does the documentation say about X?" — paraphrased questions, conceptual lookups | "Find every place we mention `OPENAI_API_KEY`" — literal identifiers, error strings, version numbers |
+| **Result cap** | Top K (default 5) | 50 matches |
+| **Flags** | — | `case_insensitive`, `count_only`, `file_id` (single-file mode) |
+
+In agentic flows, a typical pattern is: `query_knowledge_files` to locate the relevant document, then `grep_knowledge_files` to pinpoint exact lines, then `view_file` (line-range mode below) to read the surrounding context.
+
+#### Reading with `view_file`
+
+`view_file` supports two addressing modes:
+
+- **Character pagination** — `offset` + `max_chars` (default `10000`, hard cap `100000`). Best for streaming through a long document; the response includes `next_offset` when the file is truncated.
+- **Line range** — `start_line` + optional `end_line` (1-indexed, inclusive). Overrides `offset`/`max_chars` when set; pairs naturally with `grep_knowledge_files`' line numbers. Pass `line_numbers: true` to also get a `<n>: <line>` prefix on each returned line.
+
+The line-range response includes `total_lines`, `showing_lines`, and `next_start_line` for follow-up reads.
+
+### Filesystem-style access (`kb_exec`)
+
+When [`ENABLE_KB_EXEC=True`](/reference/env-configuration#enable_kb_exec) is set, Open WebUI exposes a `kb_exec` tool that gives the model a filesystem-style interface over knowledge bases.
+
+**Tools that go away**, because their function is now covered by `kb_exec` commands:
+
+- `list_knowledge` — replaced by `ls`
+- `search_knowledge_files` — replaced by `find "<glob>"`
+- `grep_knowledge_files` — replaced by `grep "<pattern>"`
+- `view_file` and `view_knowledge_file` — replaced by `cat`, `head`, `tail`, `sed -n '<a>,<b>p'`
+
+**Tools that stay injected alongside `kb_exec`**, because they do something `kb_exec` can't:
+
+- **`query_knowledge_files`** — semantic / RAG search (always)
+- **`view_note`** — when notes are attached to the model (`kb_exec` is file-only, so notes need a dedicated reader)
+- **`query_knowledge_bases`** and **`search_knowledge_bases`** — when no KB is attached to the model, so the model can still discover and search across knowledge bases by name/description
+
+This is experimental and **off by default**. It targets frontier models that already "think in shell" — they tend to chain `ls`, `grep`, and `cat` more reliably than they orchestrate a fan-out of specialized tools.
+
+**Supported commands**
+
+| Command | Purpose |
+|---------|---------|
+| `ls`, `ls <dir>/`, `ls -a` | List the current level / a subdirectory / a flat view of every file with full paths |
+| `tree`, `tree <dir>/` | Recursive directory tree |
+| `cat -n <file>` | Read a file (optionally with line numbers) |
+| `head -N <file>` / `tail -N <file>` | First or last N lines |
+| `sed -n '<a>,<b>p' <file>` | Print lines `<a>` through `<b>` |
+| `grep "<pattern>" [<dir>/\|<file>\|*.ext]` | Exact / regex search; flags `-i` (case-insensitive), `-l` (filenames only), `-c` (counts) |
+| `find [<dir>/] "<glob>"` | Find files by glob |
+| `wc <file>` | Line / word / char counts |
+| `stat <file>` | File metadata |
+
+**Pipes**
+
+`kb_exec` parses a single pipeline, so commands compose:
+
+```text
+grep "auth" | head -5
+grep -l "TODO" docs/
+find docs/ "*.md" | head -10
+```
+
+**File references**
+
+Files can be addressed three ways — pick whichever is unambiguous:
+
+- **Path** — `docs/api/auth.md` (relative to the knowledge base root; resolves through the directory tree)
+- **Filename** — `auth.md` (errors with an "ambiguous filename" hint when the same name exists in multiple directories or KBs)
+- **File ID** — the UUID returned by `ls`, `find`, or `grep`
+
+**Behavior notes**
+
+- `kb_exec` respects the same access control as the other knowledge tools — files the user can't read are silently excluded from results.
+- The model still has `query_knowledge_files` for semantic search; reach for it when literal commands won't find a paraphrased concept.
+- Built on top of the directory model — `kb_exec` is the only tool that fully reflects the directory structure created in the UI.
+
 Autonomous exploration works best with frontier models that can intelligently chain search, browse, and synthesize. Smaller models may struggle with multi-step retrieval. Administrators can disable the **Knowledge Base** tool category per-model in **Workspace > Models > Edit > Builtin Tools**.
 
 For the full list of built-in agentic tools, see the [Native/Agentic Mode Tools Guide](/features/extensibility/plugin/tools#built-in-system-tools-nativeagentic-mode).
@@ -104,6 +186,37 @@ When native function calling is enabled, attached knowledge is **not automatical
 3. Upload files or add existing documents.
 4. Attach the knowledge base to a model in **Workspace > Models > Edit**, or reference it in chat with `#`.
 
+### Organizing into directories
+
+Knowledge bases support nested **directories** so larger document sets stay navigable. Create them from the **Add Content** menu (**+ New Directory**), then reorganize freely.
+
+**Creating and navigating**
+
+- **+ New Directory** lives next to file upload in the **Add Content** menu. Name uniqueness is enforced per parent — two siblings can't share a name, but you can reuse names in different parents.
+- Click a directory to descend into it; the **breadcrumb trail** at the top of the view always reflects the current path and lets you jump back to any ancestor in one click.
+- Directories can be **renamed** or **moved to a different parent** without affecting the files inside them.
+
+**Drag-and-drop**
+
+You can move items by dragging:
+
+- **Files** onto a directory row, into the empty area of an open directory, or onto any breadcrumb crumb (including the root crumb to send a file back to the top level).
+- **Directories** onto another directory to nest them, or onto a breadcrumb crumb to move them up the tree. Moving a directory into itself or one of its descendants is blocked server-side.
+
+**Deletion semantics**
+
+Deleting a non-empty directory prompts for the action to take with its contents:
+
+- **Move files to parent** (default) — the directory is removed but its files and subdirectories are re-parented one level up.
+- **Delete everything** — the directory and all files/subdirectories underneath it are permanently removed.
+
+**Effect on retrieval and tools**
+
+- **Retrieval and standard RAG** still span the entire knowledge base. Directories don't shard the vector index; chunks from any subdirectory remain reachable in a single search.
+- **Agentic tools** are directory-aware:
+  - `kb_exec` (when enabled) treats subdirectories like a filesystem: `ls docs/`, `tree`, `grep "x" docs/`, and path-style refs (`docs/api/auth.md`) all work — see [Filesystem-Style Access (`kb_exec`)](#filesystem-style-access-kb_exec) below.
+  - The other knowledge tools (`query_knowledge_files`, `grep_knowledge_files`, `search_knowledge_files`) ignore directory boundaries and return matches from the whole KB.
+
 ### Exporting
 
 Admins can export an entire knowledge base as a zip file via the item menu (three dots) > **Export**. Files are converted to `.txt` for universal compatibility. Regular users will not see the Export option.
@@ -112,9 +225,19 @@ Admins can export an entire knowledge base as a zip file via the item menu (thre
 
 Knowledge bases can be managed programmatically:
 
-- `POST /api/v1/files/` - Upload files
-- `GET /api/v1/files/{id}/process/status` - Check processing status
-- `POST /api/v1/knowledge/{id}/file/add` - Add files to a knowledge base
+**Files**
+
+- `POST /api/v1/files/` — Upload files
+- `GET /api/v1/files/{id}/process/status` — Check processing status
+- `POST /api/v1/files/{id}/rename` — Rename a file
+- `POST /api/v1/knowledge/{id}/file/add` — Add files to a knowledge base
+- `POST /api/v1/knowledge/{id}/file/move` — Move a file between directories within the same KB (body: `file_id`, `directory_id` — `null` moves to the KB root)
+
+**Directories**
+
+- `POST /api/v1/knowledge/{id}/dirs/create` — Create a directory (body: `name`, optional `parent_id`)
+- `POST /api/v1/knowledge/{id}/dirs/{dir_id}/update` — Rename or re-parent a directory (body: `name` and/or `parent_id`)
+- `DELETE /api/v1/knowledge/{id}/dirs/{dir_id}/delete?move_files=true` — Delete a directory. With `move_files=true` (default), contained files are re-parented; with `move_files=false`, they're deleted along with the directory.
 
 File processing happens asynchronously. You must poll the status endpoint until processing completes before adding files to a knowledge base, or you'll get an "empty content" error. See [API Endpoints](/reference/api-endpoints#-retrieval-augmented-generation-rag) for workflow examples.