How to use Vitrus

Channel threads → one node per thread, @mentions auto-linked to people. Ingests: thread.

1. Create an app at api.slack.com/apps → "From scratch", pick your workspace.
2. OAuth & Permissions → Bot Token Scopes: add `channels:history`, `channels:read`, `users:read` (+ `groups:history`/`groups:read` for private channels).
3. Install the app to the workspace and copy the `xoxb-…` bot token.
4. Invite the bot to the channel (`/invite @YourApp`), find the channel ID (channel details → bottom), paste both into the form.

Permissions: ACL from channel membership — private channel → only members can see it. · Private channels stay private: membership is re-captured on every sync and enforced on every answer. · provider docs ↗

→ Connect it on the Connectors page (bot token + channel id).

Customer support messages (Business Cloud API) → nodes, in real time via webhook. Ingests: message.

1. In Meta for Developers, create a WhatsApp Business app and note the Phone number ID.
2. Create a System User permanent token with `whatsapp_business_messaging` permission (`EAAG…`).
3. Paste token + phone number ID here, then set the webhook URL shown by your deployment (`/webhooks/whatsapp`) with your verify token in the Meta dashboard.

Permissions: ACL = 'whatsapp:<phoneNumberId>' group (fail-closed — only the support team sees customer chats). · WhatsApp is webhook-only by design — messages flow in in real time; there is no history pull. · provider docs ↗

→ Connect it on the Connectors page (access token + phone number id).

Add the Vitrus agent to your project WhatsApp groups → the conversation becomes queryable company memory, answerable right in the chat. Ingests: message.

Permissions: ACL = 'whatsapp-group:<groupId>' per group (fail-closed). In-chat answers use the group's own knowledge + PUBLIC unless you widen 'principals'. · provider docs ↗

→ Connect it on the Connectors page (— + answer with access of).

Ask the brain from Slack: /vitrus <question> → a sourced answer + the yellow gap-box, right in the channel. Ingests: question (outbound answer — nothing is stored).

Permissions: Fail-closed: answers with the 'principals' above (default PUBLIC). Private-channel knowledge never leaks unless you add its group. · provider docs ↗

→ Connect it on the Connectors page (— + slack workspace (team) id, answer with access of).

Channel messages → batched conversation nodes; authors auto-linked to people. Ingests: message.

1. Create an app at discord.com/developers/applications → Bot → copy the bot token.
2. Enable the "Message Content Intent" under Bot settings.
3. Invite the bot to your server with the `Read Message History` + `View Channel` permissions.
4. Right-click the channel → Copy Channel ID (enable Developer Mode in Discord settings first) and connect.

Permissions: ACL = 'discord:workspace' group (channel membership not mapped yet → fail-closed). · provider docs ↗

→ Connect it on the Connectors page (bot token + channel id).

Channel messages and meeting notes across your teams. Ingests: message.

Permissions: Graph scopes; channel membership. · provider docs ↗

→ Connect it on the Connectors page (graph token + team id).

Repo issues, PRs & discussions → typed nodes, authors auto-linked to people. Ingests: issue/PR.

1. Open github.com/settings/tokens → "Generate new token (classic)" — or a fine-grained token scoped to one repository.
2. Grant read-only scope: `repo` → for public repos `public_repo` is enough; fine-grained: Issues + Pull requests → Read.
3. Copy the `ghp_…` token, paste it into the connector form, and set Repository to `owner/repo`.
4. Connect — the first sync pulls issues, PRs and discussions; authors are auto-linked to people nodes.

Permissions: ACL from repo visibility — private repo → 'github:<repo>' group (fail-closed). Multiple repos: comma-separate. · Private repo? Access is captured as a fail-closed `github:<repo>` group — only members see those nodes. · provider docs ↗

→ Connect it on the Connectors page (personal access token + repository (one or more)).

Issues & MRs → nodes (GitHub connector parity); authors auto-linked to people. Ingests: issue/MR.

1. GitLab → Preferences → Access Tokens → create a token with the `read_api` scope (`glpat-…`).
2. Set Project to the full path (`group/project`).
3. Connect — issues and merge requests arrive as nodes (GitHub-connector parity).

Permissions: ACL = 'gitlab:workspace' group (project visibility not mapped yet → fail-closed). · provider docs ↗

→ Connect it on the Connectors page (access token + project).

Workspace pages → markdown nodes (headings, lists, todos preserved). Ingests: page.

1. Open notion.so/my-integrations → "New integration" (internal), pick the workspace.
2. Copy the `secret_…` token.
3. Share the pages/databases you want ingested with the integration (page ⋯ menu → Connections → your integration).
4. Paste the token — no extra config needed; the token defines what the brain can see.

Permissions: ACL = 'notion:workspace' group (per-page sharing not exposed by API → fail-closed). · provider docs ↗

→ Connect it on the Connectors page (integration token + database).

Google Docs & text files → markdown nodes; owners auto-linked to people. Ingests: document.

1. Create an OAuth token with the `drive.readonly` scope (Google Cloud Console → OAuth, or the OAuth Playground for a quick test).
2. Optionally copy a folder ID from the Drive URL to limit ingestion to one folder.
3. Paste the `ya29.…` access token and connect — Google Docs and text files become markdown nodes.

Permissions: ACL = 'drive:workspace' group (Drive sharing not mapped yet → fail-closed). · Tokens expire — for production use a refresh-token flow; the vault stores whatever you provide encrypted (AES-256-GCM). · provider docs ↗

→ Connect it on the Connectors page (oauth token + folder id).

Spaces & pages → text nodes; authors auto-linked to people. Ingests: page.

1. Use the same Atlassian API token type as Jira (id.atlassian.com → Security → API tokens).
2. Fill in site + account email; optionally a space key (e.g. ENG).
3. Connect — pages are converted from Confluence storage format to markdown nodes.

Permissions: ACL = 'confluence:workspace' group (page restrictions not mapped → fail-closed). · provider docs ↗

→ Connect it on the Connectors page (api token + site, account email, space key).

Shared files and folders as searchable documents. Ingests: file.

Permissions: Shared-folder membership. · provider docs ↗

→ Connect it on the Connectors page (access token + folder).

Issues (title, description, state) → nodes; assignees auto-linked to people. Ingests: issue.

1. Linear → Settings → API → "Personal API keys" → create a key (`lin_api_…`).
2. Optionally note a team key (e.g. ENG) to limit ingestion to one team.
3. Paste the key (and team, if any) into the form and connect.

Permissions: ACL = 'linear:workspace' group (per-issue sharing not exposed → fail-closed). · provider docs ↗

→ Connect it on the Connectors page (api key + team).

Issues via REST → nodes; assignees auto-linked to people. Ingests: issue.

1. Create an API token at id.atlassian.com/manage-profile/security/api-tokens (`ATATT…`).
2. Fill in your site (e.g. `yourco.atlassian.net`) and the Atlassian account email the token belongs to.
3. Optionally set a project key (e.g. PROJ) to limit ingestion; connect — issues arrive as nodes with status and assignee.

Permissions: ACL = 'jira:workspace' group (per-issue security not exposed → fail-closed). · provider docs ↗

→ Connect it on the Connectors page (api token + site, account email, project key).

Projects and tasks with assignees, due dates and notes. Ingests: task.

Permissions: Workspace membership. · provider docs ↗

→ Connect it on the Connectors page (personal access token + workspace).

Messages → nodes; participants (from/to/cc) become the ACL + linked people. Ingests: message.

1. Email is a staged connector today: export your mailbox to the documented JSON shape (see docs/PROVIDERS on GitHub).
2. Drop the export where your operator configured `VITRUS_SYNC_DATA/<org>/email.json`.
3. A token is still required when connecting — it is proof of authorization, stored encrypted.

Permissions: Fail-closed: only participants of a thread can see it (public:true → org-wide). · Participants (from/to/cc) become the ACL: only people on a thread can see it.

→ Connect it on the Connectors page (imap / api token + mailbox).

Events → nodes; attendees linked to people, time captured for bi-temporal queries. Ingests: event.

1. Calendar is a staged connector today: export events to the documented JSON shape.
2. Drop the export at `VITRUS_SYNC_DATA/<org>/calendar.json` (operator-side).
3. Attendees become the ACL; event times power bi-temporal queries ("what did we know before the launch?").

Permissions: Attendees → ACL; event time → capturedAt (temporal gap detection).

→ Connect it on the Connectors page (calendar api token + calendar).

Meeting recordings and transcripts as records. Ingests: meeting.

Permissions: Account scopes; recording read. · provider docs ↗

→ Connect it on the Connectors page (oauth access token).

Contacts, companies and deals from your CRM pipeline. Ingests: contact/deal.

Permissions: Per-app CRM read scopes. · provider docs ↗

→ Connect it on the Connectors page (private app token).

Accounts, opportunities and cases from Salesforce objects. Ingests: account/opportunity.

Permissions: Connected-app scopes; object read. · provider docs ↗

→ Connect it on the Connectors page (oauth access token + instance url).

Customers, subscriptions and payment events as searchable records. Ingests: customer/charge.

Permissions: Account-scoped; restricted read keys recommended. · provider docs ↗

→ Connect it on the Connectors page (secret key).

Files, frames and comments from design projects. Ingests: file/comment.

Permissions: Team membership. · provider docs ↗

→ Connect it on the Connectors page (personal access token + team id).

Bridge ANY MCP server as a source — short-circuit the connector race (Glean has 100+). Ingests: resource.

1. Take any MCP server that speaks Streamable HTTP and exposes resources (docs servers, wikis, internal tools).
2. Paste its URL; if it requires auth, provide the bearer token — type `none` for public servers.
3. Connect — the bridge lists the server's resources and ingests their text content as nodes.

Permissions: ACL = 'mcp:workspace' group (upstream ACL not mapped → fail-closed). · This short-circuits the connector race: anything with an MCP server can become a source. · provider docs ↗

→ Connect it on the Connectors page (server token + mcp server url).