> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wittify.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Chat Canvas
> The single-session chat view: header, message log, composer, attachments, scope filter, streamed answers.
**Chat Canvas** is the page where you actually chat. Each session has its own canvas at `/chat-with-docs/{project}/chats/{session id}`. The composer takes plain language, accepts dropped files, and exposes a per-turn **Scope** filter that narrows which sources the next answer draws from.
## Reaching this page
You land here whenever you click a session row in the **Chats** list, click any past session in the sidebar, click the **Chats** parent (which auto-creates a fresh session), or follow a deep link from the dashboard. The topbar breadcrumb reads **Chat with Your Documents / `{project name}` / Chats / `{session title}`**.
## Page layout
The canvas is a single column with three vertical regions: the **header** at the top (sticky), the **message log** in the middle (scrolls), and the **composer** at the bottom (sticky). On mobile the header stays at full width; on tablet and desktop the column maxes out at around 900 px and centers itself.
| Region | What you see |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| Header | Back arrow, title, **Created `{date}`**, **{n} messages**, source chips, overflow menu. |
| Message log | Question turns labelled **You** and answer turns labelled **Wittify**. Empty state when the session has zero turns. |
| Composer | Attach button, scope filter button, text area, character counter, **Send** or **Stop** button. |
## Header
| Element | What it shows |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Back arrow | Routes to **Chats / `{sub-view}`** based on where you came from. Flips to a forward chevron in Arabic. |
| Title | The session title, or **New conversation** until the first turn auto-titles it. Click the title to open an inline rename input; press Enter to save, Escape to cancel. |
| **Created `{date}`** | Shown after the breadcrumb with the session creation date. Suppressed if the date is missing or invalid. |
| **{n} messages** | Singular form **{n} message** when count is 1. |
| Source chips | One chip per attached knowledge base (book icon, book name) and one chip per attached SQL source (database icon, source name). Each chip carries a small **remove** button on hover; clicking it opens a confirmation. |
| Overflow menu | A three-dot button. Tooltip *Conversation options*. |
### Overflow menu items
| Item | What it does |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Share as snapshot** | Opens the snapshot share dialog. Hidden if your role does not have **share:write**. See [Share Links](/en/Systems/Chat-with-Documents/Share-Links). |
| **Archive** | Moves the session to **Archived conversations**. Confirmed via a dialog: *Archive this conversation? Archived conversations stay searchable but do not appear in the main list.* |
| **Delete** | Moves the session to the trash. Confirmed via a dialog: *Delete this conversation? This moves the conversation to the deleted bin. You can restore it from there.* The destructive button is red with white text per the global rule. |
### Removing a source from the header
Hover any source chip and click the small **remove** button. A confirmation dialog opens.
| Element | What it says |
| ---------- | -------------------------------------------------------------------------------------------------------------------------- |
| Title | **Remove this source from the conversation?** |
| Body | Names the source. *The conversation will no longer search this {kind}. Citations from earlier answers may stop resolving.* |
| **Cancel** | Closes the dialog. |
| **Remove** | Destructive (red, white text). Updates the session's source list and refreshes. |
## Message log
The log scrolls smoothly as new content arrives. The view auto-scrolls to the latest message on every committed turn and on every token batch during streaming. To stay scrolled up while reading older messages, scroll up manually; the auto-scroll resumes only when a new turn lands.
### Empty state
When the session has zero turns:
| Element | What it says |
| ------- | --------------------------------------------------------------------------------- |
| Title | **Ask anything about your sources** |
| Hint | *Questions can reference any document or database attached to this conversation.* |
### Question turn
Question turns are pinned to the end edge of the log (right in English, left in Arabic).
| Element | What you see |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Role label | **You**, in small uppercase. |
| Timestamp | Locale-formatted hour and minute. |
| Bubble | Brand-color background with white text. Direction (`dir`) is detected per bubble: bubbles whose content is more than half Arabic codepoints render right-to-left. The body is wrapped so Arabic and English do not bleed into each other. |
### Answer turn
Answer turns sit on the start edge of the log with a small brand-gradient avatar.
| Element | What you see |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Avatar | A small circle with a lightning-bolt icon. |
| Role label | **Wittify**, in small uppercase. |
| Tool tags | English-only chips (see Tool tags below). |
| Timestamp | Locale-formatted hour and minute. |
| Status line (mid-stream) | A small line under the role row showing the current step, e.g. *Retrieving from 3 KBs*, *Generating SQL*, *Executing query*. |
| Bubble | Card-tinted background. Markdown is rendered with safe sanitization; raw HTML is never executed. |
| **Generated SQL** block (when the answer ran SQL) | Shows the SQL the agent generated, with a small **Validated** badge, **Show all rows** button, and rows count. A paginated data table or a chart renders below. |
| **Sources** footer | A list of citation cards (see Citations below). |
| Action row | **Copy**, **Helpful**, **Needs work**, **Regenerate**. |
### Tool tags
Tool tags are English-only because they describe a technical pipeline. They never translate.
| Tag | When it appears |
| ------------------------- | ---------------------------------------------------------------------------------- |
| **RAG** | The agent retrieved from documents. |
| **SQL · `{source name}`** | The agent ran SQL against a source. |
| **RAG + SQL** | The agent combined retrieval and SQL. |
| **RAG · {n} sub-queries** | The decomposer split your question into multiple sub-queries that ran in parallel. |
| **RAG · HyDE** | A hypothetical answer was generated to improve recall before the vector search. |
### Inline citations
In the answer body, references appear as small numbered pills like `[1]` `[2]`. Clicking any pill jumps to the chunk inspector for that citation. Citations that were generated before chunk metadata was wired up render as plain numbers without click targets.
### Citations footer
| Element | What you see |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Heading | **Sources** |
| Card per citation | Document name, knowledge base name, the chunk excerpt, and a small **page X** marker when known. Clicking a card jumps to the chunk inspector. |
### Per-message actions
| Action | Behavior |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Copy** | Copies the answer's text to the clipboard. Toast on success: *Copied*. Toast on failure: *Couldn't copy*. Falls back to a textarea-based copy for older browsers. |
| **Helpful** | Records a thumbs-up against the message. Visual fills in. |
| **Needs work** | Records a thumbs-down. Visual fills in. |
| **Regenerate** | Re-runs the last turn with the same question. Available only on the most-recent answer. |
### Follow-up suggestions
When the backend returns follow-up suggestions, a small chip row renders below the action row. Each chip is a clickable button; clicking it pre-fills the composer with the suggestion text and focuses the input. The composer remounts with the new starter so the chip click does not get blocked by an existing draft.
## Composer
The composer is sticky at the bottom of the page and stays inside the column.
### Layout
The text area sits in a rounded container with two leading buttons (attach, scope), the input itself, and a floating **Send** button anchored above the end edge. The end-edge padding clears the floating Wittify widget launcher in the bottom-end corner so the **Send** button is never covered.
### Buttons
| Button | What it does |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Attach (paperclip icon) | Opens a file picker. Accepts PDF, DOCX, XLSX. Tooltip *PDF, DOCX, XLSX. Up to 100 MB per file.* The file input also accepts files dropped anywhere on the composer area. |
| **Scope** filter (funnel icon) | Opens the slide-out scope panel. When at least one scope filter is active, the icon turns brand-color and a small numeric badge shows how many filters are on. |
| **Send** | Brand-gradient pill anchored above the input on the end edge. Disabled when the input is empty, while a turn is streaming, or while any attachment is still ingesting. |
| **Stop** (replaces Send) | Destructive (red) pill labelled **Thinking** with a square icon while a turn is streaming. Clicking it aborts the connection on your side; the backend finishes the turn quietly. |
### Text area
| Behavior | Detail |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Placeholder | *Ask about your documents or databases.* |
| Character cap | 10,000 characters per turn. |
| Counter | A small caption appears below the input only after you exceed 9,500 characters; reads *{n} characters left* on the end edge. |
| Direction (`dir`) | Auto-detected per content: more than half Arabic codepoints flips the input to right-to-left. |
| Auto-grow | Grows up to about 180 px tall, then scrolls inside. |
| Enter | Submits the turn. **Shift+Enter** inserts a newline. |
### Attachments
Drop a PDF, DOCX, or XLSX file onto the page (or use the attach button). Attachments queue as chips above the input.
| Chip state | Meaning |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| **Preparing** | A session-only knowledge base is being prepared on the server. Brief; only shows on the very first attachment. |
| **Uploading** | The file is being transferred. A small progress indicator fills as the upload runs. |
| **Processing** | The server is parsing, chunking, and embedding the file. |
| **Ready** | The file is searchable on the next turn. |
| **Failed** | Something went wrong. Tooltip carries the backend message. |
A small **remove** button on each chip (tooltip *Remove attachment*) drops the file before submit. Once the chip is **Ready**, removing it also unbinds it from the session.
While any chip is mid-flight, **Send** is disabled.
Attachment errors surface as toasts. A toast like `report.pdf: File too large` is the verbatim backend message; it never gets rewritten on the way to you.
### Drag-and-drop visuals
When you drag a file over the composer area, the area tints brand-color and shows a dashed border so you know it accepts the drop. Releasing the file outside the area cancels.
## Scope filter panel
Click **Scope** in the composer to open the slide-out drawer. In Arabic the drawer slides from the start edge; in English from the end.
### Header
| Element | What you see |
| ----------- | ----------------------------------------------------------------------------------------- |
| Title | **Narrow retrieval scope** |
| Description | *Apply these filters to the next turn only. Pin to keep them for the whole conversation.* |
### Sections
The body is a single scrollable column with the following sections in order. Sections that have nothing to filter (no knowledge bases beyond one, no sheets detected, etc.) hide themselves.
#### Answer with
A radio list of three options.
| Option | Meaning |
| ----------------------- | ----------------------------------------------------------------- |
| **Auto (router picks)** | Default. The agent decides whether to retrieve, run SQL, or both. |
| **Documents only** | Force RAG. SQL is skipped this turn. |
| **Databases only** | Force SQL. Retrieval is skipped this turn. |
#### Quick filters
Two switches.
| Switch | Effect |
| ------------------ | ----------------------------------------------------------- |
| **Tables only** | Limit retrieval to chunks that contain tabular content. |
| **Exclude tables** | Limit retrieval to narrative chunks (skip tabular content). |
#### Knowledge bases
Shown only when the session has more than one attached knowledge base. *Deselect to exclude a KB from this turn. Leaving all selected searches across every KB.* Each knowledge base renders as a small chip that toggles on or off. The panel keeps at least one knowledge base selected at all times.
#### Documents
A grouped picker. *Uncheck to skip. Leaving all checked is the same as no filter.* Empty state: *No documents in this conversation's sources yet.*
#### Sheets
A list of detected spreadsheet sheets. Empty state: *No spreadsheet sheets detected.*
#### Headings
A list of detected document headings. Empty state: *No headings detected.*
#### Languages
A list of detected language tags. Empty state: *No language tags detected.*
#### Metadata filters
A predicate builder. *All predicates are combined with AND.*
| Element | Notes |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Empty hint | *No filters. Click "+ add predicate" to narrow by tag.* |
| **+ Add predicate** button | Adds a new row. Each row has a key field, an operator dropdown, and a value field. |
| Operator dropdown | **equals**, **not equals**, **is one of**, **is not one of**, **greater than**, **greater or equal**, **less than**, **less or equal**, **contains**, **starts with**, **ends with**, **has any value**, **is empty**. |
| Multi-value hint | *Comma-separated values.* Shown for **is one of** and **is not one of**. |
| Key validation | *Keys use letters, digits, underscore, or Arabic. Max 64 chars.* Invalid keys highlight in red. |
| Value validation | *Value is too long.* Triggered when a value passes the per-row cap. *Filter is too complex to apply.* Triggered if the predicate tree depth or count exceeds the platform limit. |
| Remove button | A small X on each row. Tooltip *Remove predicate*. |
### Footer
| Element | What it does |
| ------------------------------- | ------------------------------------------------------------------------------- |
| **Pin for this session** toggle | Keeps the active filters across every turn until you unpin. Off by default. |
| **Clear all** | Resets every filter back to defaults. The pin toggle is preserved across reset. |
| **Apply** | Closes the drawer. The next **Send** picks up the current scope. |
### Active count badge
If at least one filter is active and the drawer is closed, the small **Scope** button in the composer turns brand-color and shows a numeric badge equal to the count of non-default filters.
## Streaming lifecycle
| Phase | What you see |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Idle | Empty state or last message. |
| Sending | Composer disables; the composer button flips from **Send** to **Stop**. |
| Streaming | A status line under the answer's role row updates as the agent moves through retrieve, generate, execute. Tokens stream in token-by-token; the bubble grows. |
| Done | Tool tags settle, citations and per-message actions appear, scroll snaps to the latest. |
| Error | Toast with the backend message, or the fallback *The assistant couldn't answer that turn. Try again.* |
If you navigate away from the canvas during a stream, the backend finishes the turn quietly. When you come back to the same session, the message log catches up via a fresh fetch. If you try to close the tab during a stream, the browser shows its native confirm prompt.
## Auto-titling
The first time the session is given an answer, an auto-title runs in the background and updates the title in the header and in the sidebar history list. If the auto-title fails, the title stays as **Untitled** and the next turn retries. A user-supplied rename always wins; the auto-title is skipped if you have already named the session.
## Common questions
Three things disable **Send**: the input is whitespace-only, a turn is streaming (in which case **Stop** replaces it), or an attachment is still preparing or uploading. Wait for chips to flip to **Ready** before sending.
Processing covers parsing, chunking, and embedding. For large PDFs (especially scanned ones) this can take 30 to 60 seconds. If a chip stays on **Processing** for a long time, hover it for the backend message; common causes are an encrypted PDF, an unsupported format, or an empty XLSX sheet.
**Stop** aborts the connection on your side. The backend keeps running until it finalises the turn, which is usually only a fraction of a second after you click. If you do not want the answer at all, archive or delete the session afterward.
The third one is the session-scoped attachment KB (created when you drop a file). It is hidden from the panel because deselecting it would silently break your attachments. Use the chips in the header to remove an explicit knowledge base.
The chunk inspector deep-link relies on chunk metadata being present. Older sessions may have citations that pre-date that wiring; their pills render but do not link. Newer turns will link normally.
The bubble's `dir` is decided per message based on its content. A bubble with more than half Arabic codepoints renders right-to-left even if the page is in English (and vice versa for an Arabic page). This keeps mixed-language threads readable; no setting toggles it.
A streaming answer is typing in real time; replacing **Send** with **Stop** makes the most-likely next click safe (clicking **Send** again would queue another turn at the wrong moment). Once the answer finishes, **Send** comes back.
That is intentional. **Clear all** resets the filter values themselves while preserving your pinning intent. Untick **Pin for this session** explicitly if you want to drop the pin too.
Most often the query returned zero rows. The **Generated SQL** block above the table shows what the agent ran, often with a **Validated** badge, so you can copy it and tweak it manually if needed.
Refreshing reloads the session from the server. If the message log is shorter than expected, a turn was likely aborted before the backend finalised it. Check **Chats / Deleted** if the whole session disappeared (you may have soft-deleted it from the header).
## Where to go next
Back to the conversation list.
Inspect the chunk a citation pointed at.
Add semantic terms so SQL turns are smarter.
Share this session as a public read-only or chatbot link.