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}, 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.
messages	Singular form 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.
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 . 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 · 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 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

The Send button is greyed out even after I typed a question.

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.

My attachment is stuck on Processing.

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.

I clicked Stop but the answer still finished.

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 Scope panel says 'Knowledge bases' with two checkboxes, but my session is attached to three KBs.

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.

Inline citation pills like `[1]` are not clickable.

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.

Auto-detect language flipped my whole bubble to right-to-left.

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.

Why does Send vanish into a Stop button mid-answer?

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.

The Pin for this session toggle stayed on after I clicked Clear all.

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.

My answer says it ran SQL but the table is empty.

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.

Where did my chat history go after I refreshed?

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

Chats

Back to the conversation list.

Documents

Inspect the chunk a citation pointed at.

SQL Sources

Add semantic terms so SQL turns are smarter.

Share Links

Share this session as a public read-only or chatbot link.