04Documentation
Give it more to work with
Vernais can only reason over what it can reach. This is how you feed it.
Connect a tool and sync it
Point Vernais at a tool, prove the credentials work, choose exactly which fields come in, and pull the data.
Integrations is where a tool goes from a logo in a catalog to records Vernais can reason over. There are 18 tools and 72 streams to draw from. You connect and sync each one per workspace.
Integrations is an elevated section. The workspace owner grants integrations.manage to each person, and it is off by default. Without it, you will not see Integrations in the nav at all. See permissions and seats.
The order that works
Sync once with every field selected before you narrow anything — that first sync is what makes the field tree appear.
- 1Connect
Open the tool's card and hit
Connect. The form shows only the fields that tool needs, plus a collapsible guide on where to find them. Secrets are encrypted before storage and never shown back to you. You see********. - 2Test
Hit
Test sync. Vernais makes one real authenticated call and reports what came back: connection live, credentials rejected, server error, or could not reach the API. The result sticks asLast testwith a timestamp. - 3Pick streams
Open
Field mapping. Toggle off any stream you do not need. Each row shows its record and field counts. Changes save on their own about half a second after you stop clicking. - 4Sync wide
Hit
Sync nowwith every field still selected. Fields are discovered from your real stored records, so a stream that has never synced has no tree to show. - 5Pick fields
Return to
Field mapping, select a stream, and narrow its tree. Deselected fields are dropped as records are stored. - 6Schedule
Open
Settings→Sync scheduleand setAuto-sync. Every connection starts atManual only, so nothing runs until you set it.
What each tool asks for
The connect form is generated from each tool's declared credential fields. You never see a field that tool does not need. A tool that lives at your own address asks for that address as well as the token.
| Auth style | What the form asks for | Tools |
|---|---|---|
| One value | A single token or key | Figma, GitHub, Intercom, Sentry, Linear, Notion, Slack, Stripe |
| A key and its second key | Two values from the same page in the tool | Amplitude (API key and secret key), Datadog (API key and application key) |
| A token plus a location | The token, plus the host, project or folder it should read | GitLab, PostHog, Google Drive |
| Site, email and token | Your subdomain or cloud ID, your account email, and an API token | Jira, Zendesk, Confluence |
| Service account | An account name, its secret, and a project ID | Mixpanel |
| App registration | Tenant ID, client ID and client secret | Microsoft Teams |
Ten streams need a parent record that Vernais cannot supply yet, and syncing the parent does not unlock them. GitHub commits, releases and workflow_runs; GitLab pipelines; Slack messages; Teams channels and channel_messages; Figma team_projects, project_files and file_comments fail every run with needs a parent … id. Toggle them off in Field mapping so your runs stay clean. Everything else in the run still succeeds. See supported tools.
Read the field tree
The tree is built from your real records, sampled up to 400 per stream. A rare field in a large stream can honestly show 0% or miss the tree.
Each row is one field. The checkbox on the left has three states. Tick a parent object and everything under it ticks too. Tick only some children and the parent shows a dash. That dash means partial.
The right side of each row tells you whether a field is worth keeping.
The share of your sampled records where this field holds a real value. Measured on your data, not on a vendor list. A field at 3% exists but is nearly always empty.
The field that uniquely identifies a record, so re-syncing updates it instead of duplicating it. Kept for you automatically, even if you deselect everything else.
The timestamp field Vernais stores as its bookmark. Also kept for you automatically.
The tool's API documents this field, but it never appeared in your sampled records.
The doc badge is the one worth understanding. It does not mean the field is broken. It means your account has not produced a value for it. You can select it. It stays empty until your data contains it.
Deselected fields are dropped when the record is written. They are not hidden. A later question that needs one cannot be answered until you re-select the field and sync again.
Narrowing is the standard advice, and it is wrong on day one. You do not yet know which questions you will ask. Sync wide, live with it for a week, then cut the fields whose fill-rate bar never moves. The test: if you cannot name a question a field would answer, it can go.
Full refresh, incremental, and the cursor
A cursor is a bookmark — a timestamp field like updated_at or created that Vernais remembers so a later sync knows roughly where it left off.
Full refresh means re-read everything each run. Incremental means ask only for what changed. Most streams ship set to incremental.
Here is what actually happens on every run. Vernais fetches, then compares each record against what you already stored. If the content is identical, the record is counted and skipped. No write, no graph work. That comparison is what makes re-syncing cheap and safe to repeat.
The per-stream mode dropdown in Settings records your choice, but the fetch does not narrow on the cursor today. Many APIs expose a created date while letting the record change later, so filtering on it would silently miss edits. The content comparison protects you instead.
When a record changes at the source, the new version lands as a new revision. The old one is marked superseded, hidden from Events and from all counts, and the graph material built from it is retracted. Yesterday's version and today's never sit in the graph together.
Logs, expand the run, and read which stream failed and whySyncing does not make the data answerable
Synced records sit in raw form. Vernais cannot reason over them yet. A separate write path turns records into a graph it can traverse: dedup, embed, route, extract, verify, resolve, write, then topics.
Run Corvex once after your first sync. Until a full build finishes for the workspace, new records will not fold into the graph on their own.
Find it in Integrations under Pipeline → Run Corvex. It takes a few minutes and shows live stage progress. Running it needs brain.run, which the owner grants separately from integrations.manage — you can hold one without the other.
After that first full build, any sync that brings in new or changed records queues an incremental run by itself. A sync that changed nothing does nothing. See Build the graph.
The same applies after a purge. Re-syncing restores the records, but the graph material was deleted. A brain run is what rebuilds it.
Set a schedule
Open Settings → Sync schedule. Set Auto-sync to Manual only, Every 15 min, Every hour, Every 6 hours or Daily, then Save changes. A background worker picks it up and runs the sync. No browser needed. The Paused switch stops the schedule without losing the setting.
The Settings tab is the one that saves. Overview shows a matching dropdown and a Pause button that change the screen only and revert on reload. Overview's Send test event also runs the credential test, not a webhook test — the real one is on Webhooks.
The detail tabs
| Tab | What it is for |
|---|---|
| Overview | A read-only summary: connection facts, a 14-day sync chart, recent activity. Its schedule dropdown and Pause button do not save. |
| Events | The records that arrived. Search by id, filter by stream, click a row for its full raw JSON. Superseded versions are hidden, so you see the current one. |
| Field mapping | The streams rail and the field tree. This is where you narrow what comes in. |
| Products | Which products this tool's data feeds. Add a product, then enable, disable or remove the link. See set up a product. |
| Webhooks | An inbound URL and signing secret so a sender can push events in between syncs. See push events in live. |
| Logs | Sync-run history. Expand a run for a per-stream breakdown with record counts and the actual error text when a stream failed. |
| Permissions | Which credential fields are set (masked, never shown), the last test result, and which teammates can manage this tool versus only view its data. |
| Settings | Display name, the sync schedule that saves, per-stream mode, and the danger zone. |
Disconnect or purge
These two are opposites, and they are the easiest thing here to mix up. Neither one does both jobs.
| Disconnect | Purge | |
|---|---|---|
| Credentials | Removed | Kept |
| Stream and field choices | Removed | Kept |
| Synced records | Kept | Deleted |
| Graph built from them | Kept | Deleted |
| Tool then shows as | Not connected | Connected |
Disconnect when someone rotated a key or you connected the wrong account. Purge when you want Vernais to forget a tool's data but keep the connection ready to pull again.
Purge cannot be undone. It deletes this tool's raw records, cleaned signals, dedup entries, extracted candidate facts, and its signal nodes, edges and facts — in both databases. It keeps the connection, your credentials, your stream and field choices, and the source snapshot it re-syncs from. Sync cursors reset to zero, so the next Sync now re-pulls from the start. Shared things other tools also rely on, like a version or a customer, are left alone.
Related resources
Set up a product
A product groups the tools and the workflow behind one slice of your company. The workflow is the part that changes what your team sees on the Act board every day.
A product is a folder for one slice of your business — Checkout, Subscriptions, Onboarding. It collects the initiatives and metrics for that slice. It also carries a workflow, and that workflow decides the columns on your Act board. The second job is the one people miss, so most of this page is about it.
What a product owns
A workflow can only live on a product, so a team that wants a custom Act board needs at least one product.
An initiative binds to one product — set when you generate it from an investigation, or changed later from the Initiatives row menu. That binding fills the product's Overview table and KPIs.
The list of tools added to the product, each marked enabled or disabled. A new product starts with none.
The states your work moves through. These become the columns on the Act board. This is the part with teeth.
Two labels you set by hand. Health is healthy or at risk and shows as a dot on every tile. Owner is one name.
Create a product
Make one product per slice of the business you review separately, not per repository or service.
- 1Open Products and click New product
The button sits at the top right of the catalog, and there is a
+on the Catalog rail too. Both appear only if you hold the elevatedproducts.editpermission. - 2Name the slice, not the software
Checkoutreads better thancheckout-service. The name shows on every tile and in the workflow picker later. - 3Set the owner and health
Owner pre-fills to you, and the server defaults it to you if you clear it. Health is a label you choose — Vernais does not work it out from your data.
- 4Click Add product
You land on the product's detail page. Status is set to
activefor you. The product now covers no tools at all.
Coverage is opt-in. A brand-new product is added to zero of the 18 tools, and you add them one at a time from each tool. That is the next section.
One product is often enough. Act falls back to another product in your workspace when an initiative is not bound to anything, so a second product mainly buys you a second workflow. The test: do these two slices need different board columns? If not, keep one.
products.edit permissionproducts.edit you still open the catalog and every product's Overview — the New product button and the product's Settings tab are hidden. Ask the workspace owner to grant itMap the tools that feed it
Coverage is stored on the product but edited from the tool, so start in Integrations.
- 1Open the tool, not the product
Integrations, then click a tool, then the
Productstab. Its heading readsPRODUCTS FED. - 2Add the product
Click
Add product. Pick one you already have, or create a new one from inside that dialog. - 3Enable or pause it
With the toggle on, the row reads
Stripe feeds this product— your tool's name in place of Stripe. Off, it readsDisabled — Stripe paused. The trash icon removes the product from this tool and sends it back to the picker.
What enabling really does. It writes the tool onto the product's coverage map, which the product's own Signal sources pane then mirrors as Feeding signals or Paused. It does not filter what an investigation reads. An investigation reads your workspace's whole graph either way. Treat coverage as a decision your team wrote down and can see, not as a switch that narrows the AI.
Shape the Act board with a workflow
The workflow you set on a product becomes the columns on every Act board for that product's initiatives.
Act works out a board by walking a chain. It takes the task, finds its initiative, finds that initiative's product, and reads that product's workflows. The states become your columns. The arrows become the only moves the board will accept. None of this is visible from the Act tab itself, which is why a board that looks wrong is usually a workflow nobody set.
- 1Open Settings, then Workspace, then Workflows
Not the product's own Settings tab. The editor lives in the main Settings hub. This is the step most people hunt for and miss.
- 2Pick the product
The pane leads with a product picker, because workflows live on a product. Each product opens with a starter set: Engineering, Design, Content, Bug triage, and a branching Custom workflow example.
- 3Edit the flow
Rename it, add or remove states, and draw the arrows on the canvas. Every state carries a status band —
To Do,ActiveorDone— and the system reads that band, never the name you typed. - 4Close the canvas
There is no Save button. Every edit persists as you make it, and a
Saving…thenSavedmarker appears in the editor header.Donecloses the canvas.
The next Act board that loads for that product's initiatives uses the new states. Work already in flight keeps its column: a task sitting in In Progress stays in an active column instead of being dumped back to the start.
When an initiative has no product. Act still needs a rulebook, so it falls back to a product in your workspace — the most recently created one that has workflows — and uses its workflows. With no product anywhere in the workspace, it uses the built-in flows. So a product's workflow can govern boards you never bound to it.
tech is forced inactive and will never govern engineering tasks. To start from Engineering's shape, duplicate it into an editable copyThe starter workflows are good defaults. If your team already runs To Do, In Progress, In Review, Merged, Verifying, Done, change nothing. The test: is a column your team actually uses missing from the board? Edit for that, not to rename one.
What a product will not do
Four things people expect from a product and do not get. Each one has a real screen that hints otherwise.
at risk shows as a dot on every tile and filters the catalog rail.Deleting a product cannot be undone. Its initiatives are not deleted — they are unlinked and survive without a product. The confirm dialog tells you how many before you commit.
Related resources
Make your synced data answerable
Syncing a tool copies its records in. Running Corvex is what turns them into something the AI can reason over.
A sync is a delivery. It drops raw records into your workspace and stops there. Those records are not yet connected to each other, so the AI cannot follow a thread from a Sentry error to the release that caused it. Corvex is the run that builds those connections.
Until Corvex finishes, a new workspace answers nothing.
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.
Run it
Run Corvex once in every new workspace, and again each time you connect a tool.
- 1Open Integrations
Left nav → Integrations. The section is called
Connect & Sync. - 2Find the runner
In the left rail, under
Pipeline, clickRun Corvex. It is not in the Data section — that catches most people out. - 3Check the raw count
The screen shows
Raw recordsat the top. If it reads 0, sync a tool first. The run refuses to start on nothing and tells you there is nothing to process. - 4Click Run Corvex
Stages stream in one at a time, each reporting its real numbers. The screen refreshes about every second and a half.
- 5Wait for Pipeline complete
It takes a few minutes. The run happens on the server, so you can navigate away. A second click while it runs does not start a second run.
- 6Check it worked
Go to Data. The
Nodestable now has rows and the graph draws. Then ask the AI something you already know the answer to.
What the run does to your records
Each stage hands its output to the next. Nothing here is a black box — you can open any result in the Data section and read the source record behind it.
| Step | What happens |
|---|---|
| Removes duplicates | The same ticket pulled twice collapses into one record. The copy is kept and marked with the record it folded into, so you can always see what was set aside. |
| Reads meaning | Each record becomes a set of numbers that captures what it is about. That is how the AI knows a 'cart' record sits near a 'checkout' record without you writing a rule. |
| Pulls out facts | It reads the text and lifts out the things and the links between them: this ticket mentions v2.2.1, this error hits checkout. |
| Checks each fact against its source | A fact has to be entailed by the words of the record it came from. If the source does not support it, the fact is thrown out rather than stored. Borderline ones are held back for review instead of entering the graph. |
| Merges the same thing seen in different tools | Stripe's Acme Corp and Zendesk's acme.com become one thing. This is the move that lets a question cross from one tool to another. |
| Groups it into topics | Related records cluster together, and each cluster gets a name drawn from your own text. Nobody types the list. |
When to run it
Run it whenever the shape of your data changed — a new tool, new streams or fields, or a purge.
- After you connect a tool — sync it first, then run. The Brain works on records, not on credentials.
- In a new workspace — every workspace has its own private graph. Nothing carries over from another one, so a fresh workspace starts genuinely empty.
- After a purge — a purge deletes that tool's records and the graph built from them, while keeping the connection itself. Re-syncing brings the records back. The Brain is what rebuilds the graph over them.
Data can also flow in on its own. Once one full run has completed for the workspace, a sync that brings in new or changed records queues an incremental run by itself. This is on by default. A sync that changed nothing does nothing. See Stream data in live for how that works.
After that first full build, a routine sync does not need a manual run — new records join the graph on their own. Re-run the Brain when you change what is in scope, not when you add more of the same. The test: did the shape of your data change, or only its volume?
What you see while it runs
The screen is a live receipt, not a spinner. Each stage reports the numbers it actually produced, and four counts sit above them:
- Raw records — what your tools delivered.
- Signals (clean) — what survived de-duplication. These are the records the AI reasons from.
- Duplicates — the copies that were folded away.
- Dedup index — the fingerprints used to spot those copies.
A header line traces the same path in one sentence: raw → dedup index → clean, followed by the duplicate count. The run ends on Pipeline complete or Pipeline failed.
This takes a few minutes, not seconds. It reads every record, checks every extracted fact against its source, and re-clusters the whole corpus. There is no faster partial mode for a first build.
What survives a re-run
Re-running is safe: it rebuilds what the AI derived and never touches the records your tools sent.
The split is simpler than it looks. Everything your tools sent stays exactly as it arrived. Everything the AI worked out gets thrown away and worked out again from those same records.
| What | On a re-run |
|---|---|
| Your raw records | Untouched. The run reads them and never writes them. |
| Your connections and field choices | Untouched. Running the Brain is not a sync. |
| Topics and umbrellas | Rebuilt from scratch. Names and ids can change between runs, so a topic you bookmarked may come back with a different name. |
| Merged entities | Also rebuilt from scratch. The AI re-derives the same merges from the same records, but the ids behind them are new. Treat an entity id as a detail of one run, not a stable handle. |
Pipeline complete.Connect / sync / disconnect / purge to reach the section, and Run Corvex manually to start a runWhen the graph stays empty
Run Corvex manually the button still appears, and the run is refused when you click it.Run Corvex manually.Related resources
Send data in as it happens
Give a sender a private URL and a signing secret, and new records land in Vernais the moment they happen — no waiting for the next sync.
A sync pulls. A webhook pushes. Instead of Vernais asking your tool for new records on a timer, your tool sends each record the moment it happens.
You turn this on per tool, on that tool's own detail page. Vernais mints a private URL and a signing secret. Any sender that can POST JSON can use them — the tool itself, or a small service you own.
A schedule covers most needs. If a 15-minute delay is fine, set an auto-sync interval on the Settings tab and skip this page. The test: would an answer be wrong if the record showed up 15 minutes late?
Before you start
- Connect the tool first. The
Webhookstab showsConnect firstuntil credentials are saved. A webhook hangs off a connection. - You need the integrations permission. It is an elevated permission the workspace owner grants per person. Without it the whole Integrations section is hidden, so there is nothing to find.
- Have a sender in mind. Vernais receives. It does not configure the far end for you. Someone has to point a tool or a script at the URL.
This is an inbound path only. Vernais does not push data out to other systems.
Turn on the webhook
Enabling mints a secret, so plan to sign from the very first delivery.
- 1Open the Webhooks tab
Go to Integrations, open the tool, then the
Webhookstab. Before it is on, you see one button:Enable webhook. - 2Enable it
Click
Enable webhook. Vernais generates an unguessable token and a signing secret. The page flips to the live view: four counters across the top, anENDPOINTcard below. - 3Copy the URL
The
Webhook URLfield holds your address. It reads likehttps://your-host/api/webhooks/ingest/stripe/<token>. The token in the path is the only thing that identifies your connection, so treat the whole URL as a secret. - 4Copy the signing secret
Click the eye icon to reveal
Signing secret, then the copy icon. Paste the URL and the secret into your sender's settings. - 5Check the target stream
The
Target streamcounter names where events land —webhookby default. Deliveries show up under that stream on the tool'sEventstab.
Sign every delivery
The signing secret proves a delivery really came from your sender and was not altered on the way.
Your sender computes an HMAC of the exact request body, keyed with the secret, and sends it as a header. Vernais recomputes it and compares. Two header names work: X-Atmos-Signature and X-Hub-Signature-256. The value format is identical.
POST /api/webhooks/ingest/stripe/<your-token>
Content-Type: application/json
X-Atmos-Signature: sha256=<hex hmac of the raw body, keyed with your secret>
{"id": "evt_1a2b3c", "type": "charge.failed", "amount": 4900}Send one record as an object, or several as a JSON array. Vernais keys each record on its id, or failing that its uuid or key, or a hash of the record itself. Resending the same key updates that record instead of duplicating it.
Once a secret exists, an unsigned or wrong-signed delivery is rejected with a 401 — not accepted with a warning. Enabling mints a secret, so this applies to every webhook you make.
Rotating the secret
Rotate secret issues a fresh secret. It also issues a fresh token, which changes the URL.
Rotating destroys the old secret and the old URL for good. Every sender still using them stops working until you paste in both new values. The button reads Rotate secret, but the URL moves too.
Send a test event
Click Send test event. Vernais writes a small synthetic record through the same ingest step a live delivery uses, and logs it. A toast reports Test delivered · 1 event ingested, and a row appears in the history below.
The test starts inside Vernais, so it skips the token lookup and the signature check. It proves the write path and the target stream, not your sender's signing. Only a real POST proves that.
The Send test event action on the Overview tab is mislabelled — it runs the credential test instead. Use the button on the Webhooks tab.
Read the delivery history
RECENT DELIVERIES lists the last 40, newest first: arrival time, status, and the event and byte counts. A rejection carries its reason on the same row.
| What you see | What it means | What to do |
|---|---|---|
| delivered | The events were written to your workspace. | Nothing. Check the Events tab to see them. |
| rejected · missing signature | Your sender is not signing at all. | Add the X-Atmos-Signature header. |
| rejected · bad signature | The secret does not match. Common right after a rotate. | Re-copy the secret into the sender. |
| nothing at all | A wrong URL, a disabled webhook, an oversized body, or too many deliveries at once. These are refused before anything is logged. | Read the status code the sender got back: 404 means the URL, 413 means the body, 429 means the rate. |
Make it answerable
A delivery lands as a raw record, and the Events tab shows its status as raw. Raw records are stored, not understood. Corvex is what turns them into the signals, entities and topics the AI reasons over.
Once a full build has finished for the workspace, Vernais folds new records in on its own. A background worker checks every couple of minutes and drains whatever is waiting. Before that first full build, deliveries stack up raw and no question can reach them.
Run Corvex once by hand before you rely on any webhook.
Limits
413 and nothing is logged.429.A webhook fills the gap between syncs. It is not a way to backfill history — a live sync is itself capped, so for anything older, run a sync. See Limits and caps for the rest.
Related resources
Turn a chat message or page into evidence
Your team already knows things Vernais can't read. Tag a chat message or a page to an initiative and it becomes a signal that shows up in the evidence.
Vernais reads your connected tools. It does not read the hallway. When a support lead explains the real cause in a channel, or you write the context up in a page, that knowledge sits outside the graph. Tagging pulls it in. Each tag becomes one signal on the initiative you picked, scored and filed like any other piece of evidence.
Tag a message in live chat
Tag while you type. The picker attaches to the message you are about to send, not to one already posted.
- 1Open the picker
Type
/at the very start of the composer and pickCapture as a signal. Or click theCapture as signalbutton in the composer toolbar. A search box opens listing your workspace's initiatives. - 2Pick the initiatives
Click one or more. Each appears as a removable chip above the input. Use the + button to add another. If the list is empty you get
No initiatives yet — create one in the Initiatives section. - 3Type the message and send
The message posts to the channel or DM exactly as normal. It also files one signal per tagged initiative. The sent message carries a small target chip for each one, with the initiative code and name.
Staged tags clear when you switch channel or DM. That is deliberate — it stops a message routing to an initiative you picked in a different conversation. If you navigate away mid-compose, pick again.
Send a page into an initiative
A page carries more than a chat line. Use it when you have written the background up properly.
- 1Open the editor menu
In the page, type
/and pickSend page to initiative. - 2Pick the initiatives
A picker opens listing the initiatives that are not archived. Choose one or more.
- 3The whole page becomes one signal
Title and body are captured together as a single signal on each initiative you picked. Not one signal per paragraph — one per initiative. The editor confirms with a count, and tells you if a destination failed.
A private or restricted page stays restricted. Tagging never widens who can read it. The signal is visible to the page's original audience, its owner and you — so teammates on the initiative may not see it at all.
Find it in the initiative
This is the step most people miss. A tagged signal does not land on the initiative's front page — it lands under two toggles in Identify, both of which default away from it.
- 1Open the Identify tab
Go to Initiatives, open the initiative, pick
Identifyand scroll toSignal clusters. - 2Switch to Post-initiative creation
The toggle opens on
Pre-initiative creation, which shows only what the investigation clustered before this initiative existed. Everything tagged afterwards lives underPost-initiative creation. - 3Pick the right kind
Solutions & tasksis selected by default and holds signals that propose a fix. A message that describes what is happening is a statement — clickStatementsto see it, along with anything judged noise. - 4Read the two cards
Related signal clustersandNon-related signal clusters. Your tag is in one of them. Click through to the records table for the full list.
| Source | Glyph | Label | Shown as |
|---|---|---|---|
| Live chat | 💬 | Live-chat message | the first 60 characters of the message |
| Page | 📃 | Tagged page | the page title |
| File upload | 📄 | Uploaded file | the file name |
| Meeting | 🎙️ | Meeting transcript | the meeting title |
Each signal carries who tagged it. Tagging the same message to three initiatives creates three separate signals — one per initiative, scored separately against each problem.
Related and unrelated
Tagging is not a promise that something counts. Vernais scores every captured signal against that initiative's problem and files it into one of the two buckets, with a 0–10 relation score and a written reason. A tangential message honestly lands in the non-related card rather than padding the case. Related signals are ranked, strongest first.
It judges against the whole problem area, not the narrow root cause. A message about the same funnel counts even when it blames a different cause or proposes a different fix. A message about a different product area does not, however actionable it sounds.
Both buckets are rebuilt from your signals every time you open the initiative. There is no refresh button and no backfill step. A newly tagged message shows up on its own, and the same text always lands in the same bucket.
The AI is not the last word. If it filed something as unrelated and you know it matters, open the initiative's Validate tab, expand the Unrelated signals row and click Mark as evidence. That holds the signal in the related bucket and on the graph while the mark stands, and un-marking sends it back. It is a flag to keep the signal — it does not assert a cause. The test: can you say which part of the problem this record speaks to? Then mark it. If you cannot, the AI is probably right.
What a signal can change
Most tags land quietly in a bucket and nothing else moves. Some do more. A signal has to clear two bars first: relevant, and fresh — meaning it adds genuinely new information rather than restating what the initiative already says. Clear both and it can nudge the initiative's confidence, refine the problem statement, or add an insight.
The nudge is bounded. Confidence can move at most 25 points in either direction, and the result is clamped between 0 and 100. One chat message cannot swing an initiative from nothing to certain, and most signals do not move the number at all. The Activity log records what happened: Chat signal added with related — initiative updated., related., or filed as unrelated.
Where tagging silently does nothing
Three failures give you no error at all. They are worth knowing by name.
E2EE chip in the conversation header are the only tell.Send page to initiative.A chat tag takes a few seconds to appear inside the initiative. The message posts at once, then the scoring runs in the background with no progress bar. The target chip on the sent message records what you tagged — it does not confirm the signal was filed. A page tag is the opposite: it finishes before the editor's confirmation, so that count is real.
Related resources
Attach files and notes as evidence
Drop a PDF on an initiative. Vernais reads it, judges it against your problem, files it as evidence — and it can move the initiative's confidence.
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. A file you attach becomes one of those records.
Attach a file to an initiative
Attach to an initiative to keep a file as evidence. Attach to a chat message to ask a question about it.
- 1Open the initiative
Go to Initiatives and open the one the file is about. Click the
Filestab. - 2Drop the file
Drag it onto the dashed zone, or click the zone to pick one. You can pick several at once.
- 3Wait for the read
A progress line shows while the server reads the file. A big scan takes longer than a Word doc.
- 4Read the verdict
The file appears as a card with a badge:
↑ Updated initiative,Fresh evidence,Relevant,Not relevantorFiled. That badge is the AI's judgement of your file against this initiative's problem. - 5Open the card
Click it to read the file as a page. If the file moved the initiative, the top of that page says so and lists what changed.
What Vernais does with it
Four things happen to every file, in order. A fifth happens only when the file earns it.
The file is read on the server and turned into text. Both engines run locally — nothing is sent to a cloud parser.
The text becomes editable blocks — headings, lists and tables survive. The original bytes are not kept.
The AI reads the start of your file next to this initiative's problem, root cause, current confidence and top hypotheses. It decides two things: is this relevant, and is it new.
The file is scored 0-10 against the problem and lands in a Related or Unrelated cluster on the Identify tab, with a written reason.
Only a file judged both relevant and new. It can then move the initiative's confidence, sharpen the problem statement, or record an insight.
The judge is deliberately hard to please. It only calls a file new when the file says something the initiative does not already reflect, and any confidence move is capped at 25 points in either direction. Most files change nothing. That is the design, not a failure.
A file is a full signal, not a passive attachment. It joins the clusters, the Correlations graph on the Validate tab and the hypotheses, like any other piece of evidence. See Tag evidence for how a signal is scored.
What it can read
If a human can read the text on it, Vernais can almost certainly read it too.
| What you attach | How it gets read | What survives |
|---|---|---|
Office and structured docs — .docx .pptx .xlsx .csv .tsv .html .epub .json .xml .rtf .odt .md | MarkItDown converts it to markdown first | Headings, lists and tables |
| A digital PDF | Read natively, text intact | The text as written |
| A scanned PDF | The native read finds no text, so it falls through to OCR | Recognised text, no layout |
A screenshot or photo — .png .jpg .jpeg .tif .tiff .webp .bmp .gif | OCR reads the text off the image | Recognised text only |
| Logs, code, config, odd extensions | Decoded as plain text as a last resort | The raw text |
Each file card names the engine that read it, so you can tell an OCR read from a native one. An OCR read of a blurry screenshot is the one worth double-checking.
Attaching everything is worse than attaching nothing. Each file is judged alone against the problem, and the verdict reads only the opening of it. A 200-page deck whose one relevant paragraph sits on page 140 reads as noise. The test: can you point at the page that changes someone's mind? Attach that.
Four ways evidence arrives
A file is one of four ways evidence reaches an initiative. All four become signals, and all four get scored the same way.
- A file — upload it on the Files tab. This page.
- A page you wrote — in Pages, use
Tag to initiative. The whole page goes, not a selection. See Write things down. - A live-chat message — tag an initiative on the message. See Talk to your team.
- A meeting transcript — it attaches on its own if the meeting was linked to the initiative. See Run a meeting.
Chat attachments are a different thing
A chat attachment goes on one message. Click + in the composer, then Attach file. Vernais reads it with the same engines, hands the text to the model for that turn, and answers your question about it.
| Chat attachment | Initiative file | |
|---|---|---|
| Lives on | One chat message | The initiative, on the Files tab |
| What it is for | Asking a question about the file right now | Keeping the file as evidence for the work |
| Gets scored 0-10 | No | Yes — Related or Unrelated, with a reason |
| Can move confidence | No | Yes, when it is relevant and new |
| Shows up later | In that thread's history | In the clusters, the Correlations graph and the hypotheses |
One overlap is worth knowing. If the chat thread you attach to is the thread that produced an initiative, Vernais routes the file to that initiative too — the same read, judge and file flow as the Files tab. The attachment chip then reads Filed to initiative, or ↑ Updated initiative if it moved the number. Attaching in any other thread does none of that.
Who can see it, and deleting
A file you upload is visible to your whole workspace. Meeting transcripts are the exception: a transcript is restricted to the people who were in the meeting, so a teammate who missed it will not see it in Files at all. Two people can therefore see honestly different file counts on the same initiative.
Deleting a file removes the only copy Vernais has. The original bytes were never stored, so the read text goes with it, along with its signal, its score and its contribution to the graph. Re-uploading means re-reading. Only the initiative's owner or reporter can delete a file — a teammate cannot quietly destroy your evidence.
Related resources
Run a meeting that becomes evidence
Meet in Vernais, turn on the transcript, and it files itself — as a page for the people who were there, and as evidence on the initiative you linked.
Link the meeting before you run it
A meeting here is a calendar event with video switched on. Add a guest and the event turns into a meeting on its own. There is no separate meetings list.
Link the initiative in the composer before the call, not after. That link is the whole difference between notes and evidence.
- 1Open the composer
Calendar →
Create, or click an empty slot on the Day or Week grid. The form opens in the left panel. TheCreatedropdown also has aVideo meetingpreset if you want it on from the start. - 2Add your guests
Search workspace members. Adding one flips the
Video meetingswitch on for you. - 3Link an initiative
Use the
Link to initiative…field. Its owner, assignee and reporter show up as one-tap guests, so you can invite the people who own the problem. - 4Save
The event now carries the initiative id. That id is what routes the transcript later.
The composer lets you add a second initiative, but the event stores only the first one. The transcript routes to that one and no other. Add the initiative you actually want the evidence on first.
Answer the invitation
RSVP is not manners here. It is the gate on your own join button.
Open the event and use Going? → Yes, No or Maybe. Only people on the guest list can respond. The organizer is told either way, so a decline is never silent.
| Your answer | What you get | What the organizer gets |
|---|---|---|
| Yes or Maybe | The join button on the event card | "is going to" or "might attend" |
| No | The event greys out on your grid | "declined" |
| Pending | No join button. The card tells you to respond first | Nothing yet |
Ask for a different time
Guests cannot edit an event. Only the organizer can. Your one lever is Propose a new time.
Pick the slot on the calendar, where you can see everyone's schedule while you choose, then Send proposal. The organizer reviews it on their own grid and picks Accept or Decline. Accepting moves the meeting for everyone and notifies them. Declining tells only you. If you propose twice, the newer one replaces your pending one, and the button reads Propose a different time.
Join the call
Click the event, then Join meeting — or Join now once someone has started it. The room opens inside the app, not in an external tab.
The first person in flips the meeting to live, and everyone else gets a notification to join. Inside you get the participant grid, a docked chat panel, emoji reactions, raise hand, and live captions you can toggle with Captions on.
Join now only from 5 minutes before the start through 30 minutes after itVideo is off until an operator sets the three LiveKit keys. Until then every join answers "Video meetings aren't configured yet". The rest of the calendar — invites, RSVPs, proposed times — works without them.
What keeps the room private
Put a member on the guest list and the door closes: the organizer and the invited members get in, and anyone else is refused. A meeting carrying no member guests is the exception — it stays open to the whole workspace. If you want the room private, invite the people you want in it.
When you join, Vernais mints you a pass for that one room. The pass expires. Its life is tied to that meeting's scheduled end, plus about an hour of slack, and never runs past three hours.
That short life is doing real work. The video service accepts any unexpired pass and has no way to cancel one it already handed out. So the pass is built to die on its own. Ending for all is the other half: it disconnects every person in the room at once.
To get people out of a room now, use End everyone. Closing your own tab removes you and nobody else.
Record the transcript
Only the organizer can start recording, and everyone in the room sees it running.
Hit Record transcript in the control bar. A red Transcript recording pill appears for every person in the room. There is no silent capture.
Here is the mechanism, because it decides who ends up in your transcript. Each person's own browser turns that person's own speech into text and sends it up. Nothing listens to the room as a whole. That is why the transcript carries real speaker names instead of "Speaker 1".
That trick needs the browser's speech engine, which in practice means Chrome or Edge. Someone on another browser joins fine, talks fine, and contributes nothing to the transcript. If a key voice is on Safari, ask them to switch before you start.
Record screen sits in the same control bar and reads like the same thing. It saves a WebM to your own downloads folder and never reaches Vernais, and it only lights up while you are sharing your screen.Record transcript for anything you want the AI to read.End it, and the transcript files itself
The organizer clicks End everyone. That ends the meeting and files the transcript. If instead everyone drifts out, the last person to leave files the transcript too — but the meeting stays open, so anyone invited can still rejoin it.
End everyone disconnects every person at once, and an ended meeting cannot be rejoined. Anyone who still needs the room has to be re-invited to a new one.
If anything was captured, Vernais assembles the transcript and files it. If nothing was said, nothing is filed. It routes once and only once, so an end plus a stray leave cannot produce two copies. A sweep runs in the background about once a minute and picks up any ended meeting whose transcript never landed.
Where the transcript lands
Every captured meeting writes a page: Pages → Transcript → the date → <meeting title> — <date>. That page is restricted to the invited people, plus anyone who actually spoke in the room.
The page carries a Summary, then Decisions, then Action items as real checkboxes, then the speaker-labelled transcript under a Transcript heading. Each of those sections only appears if the call produced one. If you linked an initiative, a live view of it sits at the top. The model that writes the summary is told to stay faithful to the transcript and to return empty lists when there is nothing to report.
The date folder is visible to the workspace, but the transcript pages inside it are not. A teammate who was not in the call sees an empty-looking folder. That is the restriction working, not a bug.
The handoff into an initiative
This is the step the rest of Vernais depends on. If the meeting was linked, the transcript is also filed on that initiative as a signal.
Vernais reads it, judges whether it is actually relevant to that initiative, and files it into the correlations, hypotheses and Decide. It only edits the initiative when it judges the transcript both relevant and new — a call that repeats what is already there is filed as evidence and changes nothing.
Everyone in the meeting gets an inbox note either way. When the meeting was linked and the call produced action items, that note counts how many were routed into the initiative. Otherwise it tells you the transcript is ready.
Not every meeting deserves a link. A weekly status call with no bearing on an open question will file a signal that adds nothing to it. The test: could one sentence from this call change what you believe about the initiative? If not, leave it unlinked and let the transcript live in Pages.
From there the transcript behaves like any other evidence you hand over. See Tag evidence for the same handoff from a page or a chat message, and Work out the cause for what the initiative does with it.
Related resources
Collect public web data with a scrape
Ask Vernais to gather public pages about a topic, and answer the two questions it asks before it starts.
A scrape is a net, not a question. A web search opens two pages, answers you, and keeps nothing. A scrape crawls many sites, pulls out what it finds, and saves every item. You can ask about the collection later.
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.
Start it from the chat composer
Turn the AI Web scraping toggle on before you type. Chat is the only place a scrape can be started.
The toggle matters more than it looks. With it on, the server takes over and walks you through a fixed flow, one step per turn. Without it, your message falls through to the AI's own improvised version, which asks a third question that no longer does anything. Click + in the composer and pick AI Web scraping, or type /scrape.
- 1Turn on the toggle
Click
+in the chat composer and pickAI Web scraping. A chip appears in the chat bar showing the lane is active. - 2Name your subject
Type the topic and send. Name a concrete thing — a brand, a product, and what you want from it.
- 3Answer two cards
A popup asks how many pages per site, and how broad the search should be. Tap one option on each. Nothing has been scraped yet.
- 4Choose paid or public
It searches for sources, then shows what it found. A card lists any paid sites by name and asks you to include or skip them. Still nothing has been scraped.
- 5Watch it run
Once you tap, the scrape starts. A chip appears at the bottom right and a live panel opens on its own.
If you want an answer now and do not need it saved, use Web search instead — it reads a couple of pages and replies in one turn. The test: would you ask a second question about this data next week?
The two settings
These two cards decide everything about the run. One controls depth inside each site. The other controls how many sites get found in the first place.
| Field | Description |
|---|---|
| pagesrequired2 / 5 / 10 / all | How far it keeps clicking 'next page' inside each site it finds. This multiplies against every site, so it drives run time more than anything else. |
| intensityrequiredlow / medium / high | How many differently-worded searches it runs to FIND sites. Low is about 6 angles. Medium is about 20. High has no cap. It changes how many sites turn up, not how deeply each page is read. |
| Your goal | Tap this | What it costs you |
|---|---|---|
| A quick read on opinion | 2 pages, Low | A few sites, a few minutes |
| A solid review corpus | 5 pages, Medium | Many sites, many minutes |
| An exhaustive sweep | 10 or All pages, High | Tens of minutes, and a lot of near-duplicate items |
All pages is not unlimitedPaid and API-gated sources
Some sites block scrapers on purpose. The only way in is their official API, which usually costs money. Vernais separates those out by name and asks you before touching them. Skip is the effective default: only an explicit Include paid sources opts in, so anything else starts a public-only run.
- Blocked without an API — X/Twitter, LinkedIn, Instagram, Facebook, TikTok, YouTube, the App Store, the Play Store, Glassdoor, SurveyMonkey.
- Public and scrapable — Reddit, Trustpilot, G2, Capterra, forums, blogs, news, and the company's own site.
- Why skip works fine — the sources that carry real review text are almost all on the public side.
When the search finds no paid sites, the card asks Start scraping or Cancel instead. Either way, you tap before anything runs.
It never starts in the same turn it searched
This is a deliberate gate, enforced by the server and not by the AI's manners. A start that fires in the same turn as the source search is refused outright. So a reply that says "starting the scrape now" has not started one. The scrape begins on the turn after you tap a choice — never before.
If you are not sure whether something is running, look at the chip at the bottom right. No chip, no scrape.
How long it takes
Plan on tens of seconds per page. That is not a setting — it is what the work costs. Each page waits about 8 seconds for a Cloudflare challenge to clear, then a few more for the page to settle. A slow load gets up to 30 seconds before it gives up. Only then does one AI call read the text out of the page.
An early status showing 6 items is progress, not failure. Items land as pages finish, so the count climbs the whole way. A scrape that looks small at minute one is often large at minute ten.
Watch it, and stop it
A chip appears at the bottom right the moment a scrape starts, and the panel opens on its own. It refreshes about every 1.5 seconds while the run is live. You get the status, the page count, the item count, the scraper's own log lines as they happen, and the items themselves. The panel has a Stop button, and you can also say stop the scrape in chat.
Stopping keeps everything collected so far. The partial data stays searchable — a stopped scrape is a short scrape, not a wasted one.
Read the panel rather than asking "status?" in chat. The AI is told not to poll a run that takes minutes, so it may answer with something stale. The test: does the chip already show what you were about to ask?
Ask about what it collected
Ask in the same chat. Vernais searches the scraped items by keyword across each item's title, text, and source URL, and returns the best matches with their site. This corpus is kept apart from your connected tools on purpose — a question about your Jira or Stripe data goes to your data, never to the scrape.
To browse without chatting, open the Data section and pick the Scrapes tab in the left rail. The badge shows how many items you have. Filter by target site, search the text, and click through to the original page.
How scraped pages reach the knowledge graph
This happens on its own — you do not run anything. Each scraped item becomes a signal in your workspace's graph, tagged with the integration name web_scrape. It flows through the same pipeline your synced tools use, so it joins the graph beside your Jira tickets and Stripe charges. The panel shows the handoff: Mapping to KG… then Mapped to KG.
Scraping the same page twice will not duplicate it. Each item is keyed on its URL and text, so an item already in the graph is skipped rather than added again. The items land in the workspace that started the scrape, and stay there.
Develop your intuition
These are starting points, not rules. When a scrape disappoints, the fix is usually in the request, not the settings. Ask yourself:
- Did I name a subject, or a superlative? "best shirts" finds Best Buy. A brand plus a product plus an intent finds reviews.
- Did I need this saved at all, or did I want an answer this minute?
- Did I turn the toggle on, or did I type the word "scrape" and hope?
- Was the run actually short, or did I check the panel two minutes in?
- Are the sources I wanted on the paid list — and did I skip them without noticing?
- Am I asking the scraped corpus a question my connected tools already answer better?
Related resources
Write a scrape request that finds good sources
The words you choose decide which sites it finds. Name the subject, not the adjective.
Your words never reach the search engine alone. Vernais hands them to a model first. That model writes several differently-angled searches around your subject, and those angles do most of the work. A vague subject produces vague angles. Vague angles bring back weak sources.
Turn on the scraping toggle first
Open the + button in the chat box — its tooltip reads Add files and tools — and turn on AI Web scraping before you type your topic.
The toggle forces the scrape flow for that turn. You then get a fixed set of taps: how many pages per site, then how broad the search should be. Nothing crawls until you tap. Without the toggle your message can take an older path that asks an extra question.
If a flow asks you for a match keyword, you are on that older path. The keyword filters nothing now. Every page found gets opened and read either way.
Why an adjective drags in junk
Lead with the thing, not with how you feel about the thing.
A search backend matches words, not meaning. Type best running shoes and best is a word it can match. It finds a store called Best Buy. It finds a dictionary page for the word best. None of that is about shoes.
Vernais defends against this, but only partly. Your raw words are searched too — they are one query among several. The merge takes the top result from every search, then every second result, and interleaves them, so no single search fills the list. Dictionary and definition sites are blocked outright. A model then drops pages that only share a word with your query.
That machinery cleans up after a weak request. It cannot rescue one. The angles are written from your words. If your words name no subject, every angle inherits the hole.
Name a subject the web writes about
A good subject is a thing strangers already publish opinions about.
A named thing people review. hoka clifton 9, not shoes.
A business people rate or complain about. jiffy shirts, not printing vendors.
A subject with an opinion trail. dtf printing durability, not quality.
Build the request in two parts, and a third when it helps.
- The subject — the brand, product or topic under its real name.
- What you want — reviews, complaints, comparisons, ratings. This tells the model which angles to write, because it adapts to the subject's genre.
- A place word —
redditortrustpilotbecomes part of the searches. It is a nudge toward that kind of page, not a filter.
If you want the shape of a whole market, stay broad on purpose. crm software reviews is a real subject: many people write about it, so many domains come back. The test: could a stranger write a page about your words? If yes, the web already did.
Four requests, rewritten
best to match, and it matches shops and dictionaries. The second names a shoe, so every angle the model writes is about that shoe.One site cannot take the whole list
Vernais keeps at most six starting URLs from any single domain.
The official site often ranks first on every angle you send. Left alone it would fill the whole list, and you would scrape a company's own marketing instead of what its customers said. The cap pushes it aside. Reddit, Trustpilot, G2, forums and news then have room.
You lose no depth to this. The crawler paginates inside each site it starts on. Six front doors into one site is plenty, and your pages-per-site setting decides how far it walks from each.
What you cannot control
All pages stops at 50 pages per siteThe source count moves between runs. A model does the final quality pass, and it does not repeat itself. Vernais guards both ends. If that model drops too much of a healthy pool, its verdict is thrown out and the ranked pool is kept. If too few survive, the list is topped back up from vetted candidates. Read the number as a rough size, not a figure to compare.
Develop your intuition
These are starting points, not rules. The fastest way to learn what a strong request looks like is to read the sources a weak one found. Then ask yourself:
- Did I name a thing, or describe a feeling about it?
- Would a stranger know what to write about from my words alone?
- Do people publish opinions about this subject, or only my team?
- Did the sources come back from six different sites, or six pages of one site?
- Did I want the web at all, or a number from my own connected tools?
