Files
Upload, browse, search, tag, and version documents in the file library.
The file library is a central place to keep documents, attachments, and other assets alongside the rest of your workspace data. You can upload files, search and filter them, tag them, and keep version history. The data model also relates files to the contacts and conversations they belong to. You can link a file to contacts manually (at upload or on its detail page); only the conversation-thread link isn't wired up yet (see below). Open it from Files in the dashboard (/dashboard/files).
The Files pages are available to any signed-in team member. Uploading, editing, and deleting files require an admin role — viewing and searching do not.
The file library
The library lists your files newest-first. A toolbar across the top gives you three controls:
- Search — type in the search box to find files by name (and the title you set when uploading). Search uses a full-text index and updates as you type. Note that tags, summaries, and extracted content are not part of the search index today (see the search section below), so searching matches on filename and upload-time title only.
- Source filter — chips for All sources, Uploads, Email attachments, and AI generated narrow the list to a single origin.
- View toggle — switch between a grid of cards and a compact list table.
Each file shows its name (or title, if you've set one), type, size, source, and creation date. Click any file to open its detail page.
File source
Every file records where it came from. The source is shown as a badge in the list and on the detail page:
| Source | Badge | Meaning |
|---|---|---|
upload | Upload | Added by a team member through the upload dialog. |
email_attachment | Tagged as originating from an inbound email attachment. | |
agent_generated | AI | Tagged as produced by the AI agent. |
The source is a label you choose in the upload dialog. Today every file is added through that dialog, so even an "AI generated" file is one you uploaded and labelled yourself. Inbound email attachments, however, ARE captured automatically into the library (source email_attachment) on delivery; only agent output is not yet auto-captured.
Uploading files
Click Upload to open the upload dialog, then:
Choose a file
Drag a file onto the drop zone or click to browse. Any file type is accepted. The dialog enforces a 50 MB limit; oversized files are rejected by the server's create mutation, not just hidden behind a UI hint.
Add a title and tags (optional)
Give the file a descriptive title (otherwise the original filename is used as its display name) and a comma-separated list of tags to label and organise it. The title is searchable; tags are shown on the file but aren't part of the search index today (see Search).
Pick a source
Choose Manual Upload, Email Attachment, or AI Generated to label where the file came from. This only sets the source badge — it doesn't change how the file is processed.
Upload
The file is stored and added to the library immediately. You'll land back in the list with the new file at the top.
File detail
Opening a file shows everything Owlat knows about it. The left column holds the file's content sections; the right column holds metadata.
- Title — click the title to rename it inline. The original filename is always shown beneath.
- Download — opens the stored file in a new tab.
- Details — MIME type, size, creation date, source badge, and a Linked Thread link if one is set.
- Tags — edit the comma-separated tags with the pencil button. Auto-detected tags, when present, appear in a separate group.
- Linked Contacts — contacts this file is associated with, each linking to its contact record.
AI summary, extracted text, and auto-tags
The detail page has collapsible sections for an AI Summary, the file's Extracted Text, and an Auto-detected tag group. These only appear when the underlying file actually has that data.
A processing pipeline (apps/api/convex/semanticFileProcessing.ts) extracts text, writes an AI summary, generates auto-tags, and computes a search embedding for each file. It is scheduled on upload (semanticFileProcessing.processFile, kicked off by the create mutation) and a safety-net cron re-runs it every 15 minutes for recent files still missing an embedding. The summary, auto-tags, and embedding are only produced when an LLM and embedding provider are configured — without them those sections stay hidden. Note that plain text, HTML, JSON, CSV, and PDF are text-extracted, but Word, Excel, and images yield only a filename placeholder, and images are not OCR'd.
Once a file has real extracted text, the pipeline also mines it into the Knowledge Graph (source File), so facts in your documents become typed entries you can browse and search alongside knowledge captured from email. Binary stubs (a Word/Excel/image placeholder) carry no text, so they don't produce knowledge entries.
Version history
Each file tracks a version number and a pointer to its previous version, and the detail page renders the full version chain as a timeline. The current version is marked.
The data model supports versions (a new upload can reference a previousVersionId), but the upload dialog doesn't yet offer a "replace / new version" option, so in practice every upload is a standalone file at version 1.
Linking files to contacts and conversations
A file can be associated with one or more contacts and with a single conversation thread:
- Contacts — linked contacts appear in the file's right column and link straight to each contact record. On a contact's own page, the Files tab lists every file linked to that contact (uploads and attachments alike). See Contacts and Audience Data.
- Conversation — when a file is tied to a thread, the Linked Thread field links to that conversation in the Team Inbox.
You set the contact links in two places:
- At upload — the upload dialog has a Linked contacts picker. Search a contact by name or email and add as many as apply; they're saved with the file.
- After upload — the file detail page's Linked Contacts panel has an edit (pencil) control that opens the same picker, so you can add or remove links at any time.
Inbound email attachments are captured to the org-general library and carry the source message's Message-ID as provenance, but they are NOT linked automatically to a contact or thread today.
The Linked Thread field is not set automatically on captured attachments today — no path currently populates a file's thread link. Manually choosing a thread for an uploaded file isn't offered in the UI yet either.
Search
The search box runs a full-text search over each file's searchable text. It's fast and forgiving of partial words, and it respects the active source filter.
The searchable text for a file is built once, when it's created, from its filename and the title you give it in the upload dialog. Tags, summaries, and extracted content are not folded into the full-text search index. Editing a file's title or tags after upload also doesn't rebuild its searchable text. So in practice you can find a file by its filename or its original title, but not by its tags or content.
The library supports semantic (vector) search — files carry an embedding field and the table has a vector index. Real vector search lives in the semanticFileProcessing.semanticSearch action (used by the agent pipeline). The dashboard search box, however, calls full-text search, and the placeholder semanticSearch query returns your most recent files rather than similarity matches — because Convex vector search runs only on an action ctx, not in a query, not because embeddings aren't generated. Use the text search box for now.
Current limitations
A quick summary of what's shipped versus planned, so you know what to expect:
| Capability | Status |
|---|---|
| Upload, browse, grid/list views, source filter | Available |
| Full-text search by filename and upload-time title | Available |
| Search by tags, summary, or extracted content | Not yet active (not indexed) |
| Manual tags, inline title editing | Available |
| Version history timeline (chain display, current marked, per-version download) | Available (no "new version" upload action) |
| Manual file→contact linking (upload picker + detail-page editor) | Available |
| Linking files to conversation threads | Not yet active (no path sets the thread link) |
| Text extraction for plain text, HTML, JSON, CSV, PDF | Available |
| Text extraction for Word / Excel, image OCR | Not yet active |
| AI summaries and auto-tags on upload | Available (requires a configured LLM provider) |
| Semantic / vector search | Not yet active |
| Automatic capture of email attachments | Available |
| Automatic capture of agent output | Not yet active |