01Documentation
Start here
The one rule behind every answer, and your first root cause in about twenty minutes.
How Vernais answers a question
One rule sits under everything else: an answer about your data has to trace back to a record it can point at.
One constraint shapes most of what follows: when Vernais answers from your connected data, every claim has to trace back to a record it can point at. It will not invent a cause. A question it cannot ground in your data returns nothing rather than a guess. Questions about the outside world, or about general knowledge, it answers like any good assistant — and tells you which world the answer came from.
Three worlds, and it tells you which one
Before you read a reply, ask which world it came from: your records, the live web, or plain knowledge.
| World | What it does | How you can tell |
|---|---|---|
| Your connected data | Reads the records synced from your connected tools. Every number returns with the filter that produced it. If nothing matches, you get nothing — not a guess. | Steps like Counting events, Searching records or Classifying outcomes appear in the thinking block above the answer. |
| The outside web | Searches the live public web, opens the best few result pages, and answers from what it read. | A N sources pill sits under the answer, and inline [1] markers render as source chips. |
| General knowledge | Answers a timeless question the way any good assistant would. No tool runs. | No tool steps appear. The reply starts writing straight away. |
Which world a question belongs to is a property of the question, not a setting you pick. how much did we bill last month is your data. stripe's stock price is the web. what is a retention cohort is general knowledge.
One reply can draw on more than one of them. The model holds the data tools and the web tools in the same turn, so a question that needs both can use both. The thinking block is where you read which it actually opened.
One model, deciding as it goes
One model reads your message. It picks its own tools, runs them, reads what comes back, and picks again if it needs more. Nothing sorts your message into a category before the model sees it.
That is why the reply starts almost at once: no second system runs ahead of your question. It also means two similar questions can take slightly different paths. A model is deciding, not a rule.
The same model chooses the heavy work too. Ask why something is happening and it reaches for the root-cause investigation on its own, then streams the case file into the same reply. That run takes a few minutes, because it reads evidence across your tools rather than counting one table.
When it picks wrong, take the wheel. The + menu carries Investigation, Data lookup and Web search; /investigate, /lookup and /web do the same for one message only. Investigation then runs end to end and cannot be quietly downgraded to a count. Data lookup and Web search push the model at your records or at the web. The test: if you already know which world holds the answer and the model keeps missing it, pick the lane yourself.
How a data answer gets grounded
Vernais does not know your field names in advance. Jira stores an assignee at fields.assignee.displayName. GitHub calls it author. Sentry has none. So the model samples a few real records first, learns the real keys, then filters or counts with them.
Every number comes back with the filter that produced it, like count = 200 matching [integrations=['stripe']]. That line is the receipt. If the filter says the whole Stripe tool but you meant only charges, the number is answering a different question than you asked.
Match each number in the answer to a step in the thinking block. A data answer with no step behind it is wrong.
Why an answer can come back empty
The investigation's evidence gate is where this bites hardest. Records do not become evidence by sitting nearby. Each candidate record is judged on its own by a small model that can say only supports, contradicts, or neutral. To take a side, it has to copy a real quote out of that record. If the quote is not genuinely in the text, the vote is forced to neutral.
So a record that never mentions your subject cannot vote for it. If not one record survives that check, you get the honest ending. It names the closest area it found, says no records there speak to your question, and asks you to name a tool, a metric, or a time frame. No confidence badge, no story.
A workspace whose knowledge graph has not been built yet looks identical to this from your seat. Syncing data and building the graph are two different jobs. See Build the graph.
Why we built it this way
The costs are lopsided. An empty answer costs you an hour and a rephrase. A confident wrong cause costs a sprint: you brief the team, you open the tickets, engineers chase a bug that was never there, and the real problem keeps running.
For a PM, a made-up cause is worse than no answer.
Everything slower about Vernais comes out of that trade. The quote check throws away thin records. The investigation spends minutes walking evidence instead of guessing in seconds. After the answer is written, a separate check re-reads each claim against its source and can pull the stated confidence down — never up. See Read the confidence badge for what each level means.
The rule stops at your data. Ask what a transformer is, or what happened in the news this morning, and you get a normal answer from a good assistant. Only claims about your own records have to carry a record behind them.
Related resources
Get your first root cause
Connect one tool, make its data answerable, then ask one why question. About 20 minutes, and most of it is waiting.
One constraint shapes most of what follows: when Vernais answers from YOUR CONNECTED DATA, every claim has to trace back to a record it can point at. It will not invent a cause. A question it cannot ground in your data returns nothing rather than a guess. Questions about the outside world, or about general knowledge, it answers like any good assistant — and tells you which world the answer came from.
Before you begin
- Credentials for one tool you already use — an API key or a token. The connect form shows you where to find them.
- The
integrations.manageandbrain.runpermissions. Both are elevated and off by default. The workspace owner grants them to you by name. - A Max seat. It is the seat that carries
investigation.run. A Power seat can browse data but holds no AI capability at all.
Step 1: Connect a tool
Test the credentials before you sync. A rejected key looks a lot like an empty tool.
Open Integrations in the left nav. Eighteen tools sit there, grouped by category. Each card's footer reads Connect; open one and click Connect again in the detail. A form opens with one input per credential that tool actually needs. Stripe asks for one secret API key. Jira asks for your site subdomain, your account email and an API token. A collapsible How to get these credentials guide sits inside the form.
Vernais encrypts the secret values before it stores them, and never shows them back. You only ever see ******** per field.
Now click Test sync. Vernais makes one real authenticated call to that tool's API and tells you what came back: Connection live, Credentials rejected (unauthorized), or Could not reach the API. For your first run, pick a tool that holds written text — Jira, Sentry, Zendesk. The AI needs quotable sentences to work with.
Text tools can name a cause but not size it. Failure counts and a tracking metric come from payments or analytics data, and without it the investigation can withhold its verdict and name the test it is missing. The test: if you want to know how big the problem is, connect Stripe or your analytics tool too.
Step 2: Choose streams and fields
Leave every field on for this first pass — the field tree does not exist until records land.
Open the Field mapping tab. The left rail lists that tool's streams: Stripe has charges, customers, invoices and four more; Jira has issues, projects, users. Each has a toggle, and turning one off keeps it out of every future sync. Your change saves about half a second after you stop clicking, and a Saving… marker turns to ✓ Saved to confirm it.
The field tree on the right is empty right now. Vernais builds it from your real stored records. A stream you have never synced reads No records stored for this stream yet — run a sync to discover its fields. That is the true order: pick streams now, sync, then come back and narrow fields.
Step 3: Sync
Open the Logs tab and look for live — a run labelled snapshot means your credentials never attached.
Click Sync now. Vernais calls the tool's API with your credentials, keeps your selected fields, and stores each record in your workspace's own database. A toast reports how many records landed across how many streams. Re-syncing is cheap: a record whose content has not changed is counted and skipped, so nothing duplicates.
Every run is recorded. Expand one in Logs to see each stream on its own line — records, source, and the exact error text if a stream failed. One broken stream never hides the ones that worked.
Step 4: Run Corvex
Nothing you synced is answerable until this run finishes. This is the single most common first-day confusion.
Synced data is not answerable data. Your records are sitting in raw form. Chat cannot reason over them yet. Corvex is the step that turns those records into the knowledge graph the AI reads.
Open Integrations, pick Run Corvex in the left rail's Pipeline group, then click the Run Corvex button. The screen says 15 stages · a few minutes and it means it. Stages stream past with their real numbers — dedup, embed, route, extract, verify, resolve, write the graph, then topics — and it ends on Pipeline complete. If nothing has synced, the run refuses and says integration_raw is empty — nothing to process. rather than running on nothing.
This first full build is required, and it is required once. After it completes, Vernais keeps up on its own: a sync that brings in new or changed records queues an incremental run for that workspace. A sync that changed nothing wakes nothing.
Run it again after a big sync, or when the graph looks stale. Re-running rebuilds the topic layer from scratch, so topic names and ids can change between runs. Your records and the entities they resolve to come back.
Step 5: Ask one why question
You do not pick a mode. The verb you write is what steers the model.
Open the AI chat and type a real question. There is no mode to pick and no button to press. The chat model reads what you wrote and decides on its own to run the deep investigation.
An investigation takes a few minutes, not seconds. You watch roughly 15 named stages stream past while it works. If the AI provider stays rate-limited past the time budget, the run halts cleanly and says so — it will not ship a half-answer.
If you want the deep path regardless of how you phrased it, use the composer's + menu and pick Investigation, or type /investigate. Your choice overrides the model's own routing and cannot be quietly downgraded to a lookup.
If you already know the number and want the records behind it, skip the investigation — a lookup returns them in seconds. The test: are you asking for a cause, or for a list?
Step 6: Read the case file
Read the confidence badge first — a check rewrites the prose to match it, so the badge and the words agree.
The answer arrives in the same chat turn, as a case file of collapsible sections. Here is what each one holds.
high, medium or low, above the answer. A deterministic check can lower what the model claimed. It can never raise it.
One row per claim: a mark saying whether a verifier could tie it to its source, plus a cite chip. Click the chip to expand that record inline — its stored text, fields and links — without leaving the answer.
Real counts from your event data — a by-version table of failed against succeeded, distinct users, sample failing events — scoped to this incident, not to your whole corpus.
One number with its formula, computed now, that measures the problem it diagnosed. Read-only here — you lock it as a baseline in an initiative's Measure tab.
The competing explanations written before any evidence was read, each carrying its assessment. A separate Ruled out section shows what lost, and why.
Missing data and counter-evidence, in plain words. Below the case file, an NLI ground-check line counts how many claims a verifier could tie back to their sources.
high means the pattern is proven and the named mechanism covers the failures. medium means one named objection stood: a symptom predates the change you blamed, or the mechanism only explains part of the failing group. The caveat line names which one.
Sometimes Vernais finds a plausible mechanism but refuses to call it a cause. Then the badge reads low, the caveat opens Causal conclusion withheld: and names what was missing, and a hypothesis only marker appears on the stage. The usual reason is that no payments or analytics data was connected to prove impact.
If it says it found no evidence
This is a likely first result, and it is a real answer rather than an error. It reads: I couldn't find grounded evidence for this in your connected tools. The closest area was your topic, but no records there speak to your question. So it will not guess. It fires only when zero records survive the evidence check.
A juror has to quote the record word for word, or its vote does not count.
- Did the brain run finish? An unbuilt graph looks exactly like no evidence from your seat. Check
Integrations→Run CorvexforPipeline complete. - Do your words match your data's words? Your question is matched to the closest topics. Open
Data, filter the node type to Topic, read a few names, and reuse that vocabulary. - Do the records hold quotable text? Pure telemetry — charges, analytics events — rarely survives on its own, because there is no sentence to quote.
- Did you name the right tool? Naming a tool folds all of its records into scope. If those tools turn out to hold under a third of the grounded evidence, you get a caveat and a high confidence drops to medium.
What you have now
You connected a tool, made its records answerable, and got one cited answer with its receipts attached. Connect a second tool and re-run the brain to see the real payoff. A Jira ticket and a Stripe charge that both mention v2.2.1 resolve to one shared entity. That link is the thread an investigation walks from a symptom to a cause.
Related resources
How Vernais knows things
Your tools become signals, signals become a map, and the map is what the AI reads instead of everything.
The one constraint
One constraint shapes most of what follows. When Vernais answers from YOUR CONNECTED DATA, every claim has to trace back to a record it can point at. It will not invent a cause. A question it cannot ground in your data returns nothing rather than a guess.
Questions about the outside world, or about general knowledge, it answers like any good assistant — and tells you which world the answer came from.
Everything below is one idea in different clothes: if there is no record behind it, it does not get stored, and it does not get said.
Signal, entity, topic
Three words carry most of the model. Learn these and the rest follows.
Receipts. One record from one connected tool, after cleaning — a single Jira issue, one Slack message, one Stripe charge. Duplicates were removed before it became a signal.
Glue. One real thing that many records talk about — a customer, a version, a service, a bug. Stripe's Acme Corp and Zendesk's acme.com resolve to one entity.
Shelves. A cluster of related records, grouped by maths, not by hand — for example Promo-code failure at checkout. Its name is lifted from phrases in the members' own text.
A topic name can never be invented. Candidate phrases are pulled out of the members' real text, and the one whose meaning sits closest to the middle of the cluster becomes the name — so you can always find the words on the page.
Every signal keeps its original record underneath. Open any row in Data and expand Raw payload to read exactly what the tool returned. Nothing is summarised away.
How much is one signal?
The rule is one record, one signal. Tools differ wildly in how many records they produce, so the same week of work lands very unevenly.
A scraped page is not one signal — each review or post on it becomes its own. And a week of payments is hundreds of records, so it is hundreds of signals, while a week of tickets might be a dozen.
This is why a graph built mostly from payments looks huge but says little, and a graph with tickets and messages says a lot with fewer rows. Volume is not evidence.
How one tool's data meets another's
Entities are the join. This is the single move that makes cross-tool questions possible.
A Jira ticket mentions v2.2.1. A GitHub commit mentions v2.2.1. A Stripe charge carries v2.2.1. Those three records live in three tools that have never heard of each other. Vernais resolves all three mentions to one entity, and now the records are connected.
You can audit the merge. Open an entity and read Resolved from N mentions. It lists every wording that got folded into that one thing.
No entity, no cross-tool answer — and the join is a decision you can inspect.
Very connected entities do not get every pair of their records linked. Above about 40 mentions, Vernais links one representative record per tool instead. Two Jira issues sharing a busy entity may have no direct line, yet they still connect through the entity itself.
The four evidence links, strongest first
Links between records are not equal. Vernais ranks them, and the ranking decides how much weight a link can carry.
| Link | What makes it | What it may do |
|---|---|---|
| REFERENCES | The text literally names the other record — fixed in PR #42 | Assert. It is a hard link. |
| SHARED_ENTITY | Both records point at the same resolved thing — both mention v2.2.1 | Assert. It is a hard link. |
| SIMILAR_TO | The two records read alike, by a measured similarity score | Rank only. Never assert. |
| TEMPORAL_NEAR | They happened close together, in different tools, inside about a day | Rank only. Never assert. |
Hard links are the ones the AI can build an argument on. The text either says it, or both records genuinely point at the same thing. Neither is a guess.
Ranking links only decide what is worth looking at next. A deploy and an error spike an hour apart is a coincidence in time. It is a good lead. It is not proof, and Vernais never lets it become one.
A standard build writes the hard links only: a record to the thing it mentions, and records that share the same entity. REFERENCES, SIMILAR_TO and TEMPORAL_NEAR are switched off by default, and a second default-off setting keeps the investigation from walking them even where they exist. If you expected "it links things that happened at the same time" and do not see it, that is the reason — not a bug.
Cause is not stored
This is the heart of it. The graph never stores X caused Y.
The reason is plain: your data never says that. A Jira ticket says there is a promo bug. A commit says the cart changed. A Stripe charge says a payment failed. Not one of those records says one thing broke another. If Vernais stored a cause, it would be storing something no record supports — and once stored, a wrong cause is permanent.
So it stores only what it can point at, and works out the cause fresh every time you ask.
When you ask why, Vernais gathers candidate records and puts each one in front of a small AI juror. A juror has to copy a real quote from that record to take a side. No quote, and the vote drops to neutral. The records that survive with a real quote are the evidence — and only those.
If not one record survives, you get told so. Vernais names the closest area it looked in and stops. It does not guess.
The answer comes back as a hypothesis with its evidence chain attached, and you can click any citation to open the source record.
The Data section shows grounded facts. The why lives in chat. If you want a cause, ask for one there — the map alone will never hand you one.
Working out a cause takes a few minutes, because it is real work over your records rather than a stored lookup. A quick count takes seconds.
If you already know the cause and want the records, skip the investigation and ask for the data instead. The test: are you asking why, or asking how many? Only the first one needs the slow path.
The upside of deriving instead of storing: a hypothesis improves as your data grows. Nothing wrong is baked in permanently. Connect the missing tool, and the same question can return a better answer.
Why a new workspace is empty
Each workspace has its own private graph. Vernais always reads the workspace you are in, and always builds into the workspace you are in. Nothing leaks across.
So a new workspace starts genuinely empty, and stays empty until two things happen there. First, your tools sync their records in. Second, someone runs Corvex in that workspace.
Connecting a tool is not enough. Syncing data is not the same as building the map. Until the Brain runs, the Data table is blank and every why-question honestly reports no evidence — which looks identical to having no answer.
The Run Corvex button lives in Integrations, not in Data. It runs 15 stages and takes a few minutes.
Running the Brain is an elevated permission, off by default. Browsing Data is not — that one is on for everyone. A teammate can see an empty section, be told to run the Brain, and not be able to. If that is you, ask your workspace owner to grant it.
Where the map is honest about its limits
Some gaps are deliberate. They are the price of refusing to blur "probably" into "is".
An untopiced record is not a broken record. It means the maths had no honest reason to file it, and Vernais would rather leave it loose than put it on the wrong shelf.