> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vh3.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Building on the layer
> Citizen builders, coding agents, and integrations on a secure operational substrate
# Building on the layer
An operations manager routes a sentinel digest to Slack. A coordinator builds a workflow for engineer follow-ups. A developer opens Cursor and asks it to build an account review panel against the VH3 AI API. Each builder is working on the same prepared operational model.
VH3 AI is designed as a secure operational substrate:
* Jobs and relationships are enriched once and stored in infrastructure scoped to your organisation.
* Fast discovery (search, similarity, entity resolution, customer knowledge sections) reads that model without an LLM.
* Agents, reports, and automations read the same model when they need language and narrative.
* Connected tools (email, calendar, CRM, storage, field systems) feed **entities back** into the same graph through managed sync and resolution.
This guide is for **builders**: operations staff using no-code tools, and technical staff using Claude Code, Cursor, or similar coding agents.
**Are you an operator or an IT lead?** Operators should start at [Working with your operation](/guides/working-with-your-operation); IT leads deploying internal apps should read [Deploying secure apps](/guides/deploying-secure-apps) for governance and auth patterns. This page focuses on builder workflows.
How search, customer knowledge sections, and entity resolution work on the layer.
## What integrating AI should mean in field service
| Maturity | What the business has |
| -------------------- | ------------------------------------------------------------- |
| **Level 1: Access** | Exports and dashboards; questions wait for manual analysis |
| **Level 2: Ask** | Chat over files; answers are not durable or shared |
| **Level 3: Model** | Persistent graph, enriched jobs, fast discovery, sentinels |
| **Level 4: Operate** | Agents, automations, cases, custom apps on the same substrate |
VH3 AI targets levels 3 and 4. Level 2 is where cost and trust break down: every session re-interprets raw text, and nothing belongs to the organisation in a structured form.
**Data sovereignty** means your enriched operational intelligence is tenant-isolated, portable, and usable outside a single vendor UI. You can connect your own models (BYOK), your own automations, and your own applications. The platform fee covers the intelligence layer; agent token spend stays visible on your provider account.
## Three builder paths (same foundation)
n8n, templates, Connie in Claude Projects. Solve local problems without a development queue.
Cursor, Claude Code, MCP. Generate apps and integrations against a documented API.
Direct API integration, custom UIs, partner solutions. Full control, full responsibility.
All three paths call the **same APIs** and read the **same operational model**. Each builder works from the same resolved customers, jobs, sites, and engineers.
One reason that holds: VH3 AI maintains a canonical domain model for field service. Every record that enters the platform, regardless of source system, is resolved into that model before it touches the graph. A job is a job. A customer is a customer. The model's schema is not exposed, but the contract it delivers is: consistent, resolved, connected entities at every endpoint. When you build an app or an automation on this layer, you inherit that consistency. See [The domain model](/intelligence-layer#the-domain-model-why-the-substrate-speaks-one-language) in the intelligence layer guide.
## The tool surface (at a glance)
The substrate is only half the story. The other half is the tool surface that sits on top, the same tools Connie uses internally, also available to your agents, automations, and apps.
| Class | Tools | What they do |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Discovery** (no LLM) | `/search/outcomes`, `/search/intake`, `/search/autocomplete`, `/search/summary-sections`, `/jobs/feed`, `/jobs/aggregate`, `/contacts/feed`, `/dashboard/snapshot`, `/weather/*` | Sub-second lookups: precedents, entity resolution, account hierarchies, KPIs |
| **Monitoring** (no LLM at detection) | `/sentinels/run`, `/sentinels/digest`, `/sentinels/results` | 24/7 pattern detection on the graph |
| **Synthesis, conversational** (BYOK) | `/connie/chat`, `/investigate` | Cited narrative, multi-step diagnosis |
| **Synthesis, platform** (included) | `/briefings/*`, `/reports/generate` | Pre-visit briefings, scheduled report generation |
| **Workflow** | `/cases/*`, `/teams/*`, `/users/*`, `/auth/*` | Cases, teams, users, JWT sessions for ownership and access |
| **Ingest** | `/triage/classify`, `/ingest/email-portal`, native integrations | Inbound triage and structured extraction |
This is the surface a coding agent or n8n workflow calls. Sentinels are how the platform notices things; discovery and synthesis are how it answers; cases and teams are how it follows through. The full inventory, with patterns and evaluation notes for AI agents reading the docs, is on [Platform tools](/guides/platform-tools).
Every tool, what it does, when to reach for it, and the patterns that get the most out of them. Use this page if you are evaluating VH3 AI for a build.
## Connected tools and programmatic access
Field service runs across more than one system. VH3 AI brings third-party tools into the same operational model so mail, calendar, CRM, storage, and field systems add useful context to the graph.
### Native connections (in the platform)
[Native integrations](/native-integrations) are activated inside VH3 AI: OAuth handled for you, sync managed by the platform, health visible to admins. Typical categories:
| Category | Examples | What flows into the layer |
| ---------------- | -------------------------------------------------- | ------------------------------------------------ |
| Field management | BigChange (live), others on roadmap | Jobs, engineers, customers, worksheets |
| Communication | Gmail, Outlook, Slack, Teams, WhatsApp | Threads, alerts, context for briefings |
| Scheduling | Google Calendar | Per-user availability and planning context |
| CRM / finance | Pipedrive, Zoho, Xero, Stripe, Salesforce, HubSpot | Commercial context alongside operational history |
| Storage / docs | Drive, OneDrive, Dropbox, PandaDoc | Documents linked to accounts and work |
**Per-user connections** matter for agents tied to real people: an engineer's inbox and calendar, scoped to what they authorised, can inform briefings without exposing everyone's mail to the organisation.
**Organisation-level connections** matter for shared systems: one Xero or Slack workspace, one CRM, available to automations and reporting across the team.
### Programmatic access (for your agents and apps)
Everything the platform does internally is also available **programmatically**:
* **REST API** for search, jobs feed, sentinels, reports, Connie, cases, teams, and backfill tasks.
* **MCP server** so Claude Desktop, Cursor, and other MCP clients call the same tools Connie uses, with credentials handled server-side after JWT auth.
* **n8n node** (community and PRO) for workflow builders who want operations-friendly automation without writing a backend.
When email arrives or a calendar event is created, ingestion and **entity resolution** map people, domains, and addresses back to **contacts** in your model. That is how personal agents and shared automations stay aligned with operational truth across inboxes and calendars.
Design automations so **fast endpoints** (search, autocomplete, sentinels, jobs feed) handle triggers and filters, and reserve Connie or investigate for steps that need narrative. Predictable latency and visible AI cost follow naturally.
## Operations builders (no-code and low-code)
The citizen-builder pattern is how strong field service teams already work when they are not waiting on IT:
* An operations manager routes a **sentinel digest** to Slack when SLA performance slips.
* A contracts lead schedules an **account monthly report** to a client distribution list.
* A service coordinator creates a workflow when **engineer-flagged follow-ups** spike for one customer.
None of that requires a development team. It requires **templates**, **connectors**, and an intelligence layer that returns consistent, scoped data.
**Starting points:**
* [n8n node and templates](/n8n-node)
* [Agent kits: n8n agents](/agent-kits/n8n-agents)
* [Claude Projects for ops](/agent-kits/claude-projects)
## Coding agents on a secure substrate
Tools such as **Claude Code** and **Cursor** work best when they are not guessing your domain. They need:
1. A **stable API contract** (OpenAPI, consistent field names).
2. **Guardrails** (which endpoint for which question, what never to expose to end users).
3. A **tenant boundary** (`company_id`, `api_key`, no cross-customer leakage).
VH3 AI ships **Agent Starter Kits** for that: AGENTS.md, Cursor rules, MCP setup, and n8n prompts that encode field service routing (discovery vs synthesis vs sentinels).
Drop-in configuration so coding agents use VH3 endpoints correctly from day one.
### What coding agents should build
| Application | Discovery / data | Synthesis / action |
| ------------------------- | -------------------------------------- | -------------------------------------------------------------------- |
| Dispatch assist panel | `search/outcomes`, autocomplete | Optional Connie summary |
| Customer 360 internal app | Jobs feed, customer summary by contact | Reports, investigate |
| Slack ops agent | `sentinels/run` | Connie with citations ([observability](/guides/agent-observability)) |
| Partner portal | Scoped search by `contact_id` | Branded report export |
### Safe patterns
**Never call VH3 APIs from browser code.** Your `api_key` and `company_id` are server-side credentials. If they appear in a browser network request — even inside a fetch call in a React component or a bundled environment variable — they are visible to anyone who opens browser developer tools. Build a backend route that holds the credentials and proxies the call. The browser calls your backend; your backend calls VH3. This applies to every endpoint on `api:kP8T1CK7` and `api:YdihQNr3`. For browser-based apps, use [User Authentication (JWT)](/authentication#user-authentication) so users log in with email and password only, and no API key is ever involved in client code.
**Never expose internal identifiers** in end-user interfaces: internal company, job, contact, resource, or linkage keys. Use names, references, and addresses in UI copy. Keep IDs in server-side calls only.
**Contact-centric scoping.** Build navigation around customers (contacts). Places are addresses under that customer. Engineers are resources. This matches how account managers and dispatchers think.
**Timeouts.** Discovery endpoints are typically sub-second. `investigate`, report generation with narrative, and Connie tool loops need longer HTTP timeouts (often 20 to 25 seconds). Agent kits document recommended values.
### MCP: intelligence without middleware
The MCP server exposes tools such as search, investigate, sentinels, jobs feed, and reports. A coding agent can call operational discovery directly, then generate UI or workflow code around the responses.
See [MCP setup](/agent-kits/mcp-setup).
## Customer knowledge your agents can rely on
Builders should understand the **Customer Summary** knowledge object (see [Operational discovery](/guides/operational-discovery)):
* Seven **modular sections**, each independently searchable and rankable.
* **Refreshed** on a schedule or when job drift thresholds are met, so agents are not stuck with a one-off PDF.
* **Injected** into Connie sessions together with recent jobs since generation, so conversations start with current context.
Coding agents can call `POST /search/summary-sections` for thematic queries across accounts, or fetch a full brief per contact before rendering a custom account page.
## From signals to owned work
AI integration fails when insight has nowhere to go. VH3 AI pairs **detection** with **ownership**:
| Concept | Role |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| **Sentinels** | Continuous pattern detection on the graph (no LLM at detection) |
| **Discovery** | Fast precedent, entity, and knowledge-section lookup |
| **Connie / investigate** | Cited synthesis and diagnostic narrative |
| **Cases** | Multi-step operational work (escalation, complaint, follow-up) with status and participants |
| **Teams** | Scoped groups for who owns which customers or regions |
**Example flow:**
1. Sentinel flags repeat attendance for a contact.
2. Automation runs `search/outcomes` for similar faults on that account.
3. Case opened: "Third fire panel callout in six weeks" with jobs linked as items.
4. Regional team notified; Connie drafts engineer briefing for the next visit.
Cases and teams are intentionally lightweight: enough structure to **close the loop** with status, participants, linked jobs, and ownership.
* [Cases API](/api-reference/cases)
* [Teams API](/api-reference/teams)
## Why the substrate makes coding agents viable
Prepared context is what makes coding agents useful in field service. Each session can start from enriched jobs, resolved accounts, and linked history.
VH3 AI front-loads **enrichment**, **multi-entity resolution**, and linking of jobs, customers, sites, and history at ingest. Coding agents then generate thin applications that call well-shaped endpoints. You are not paying an LLM to rediscover your operation on every click.
> Built to be built on. Your people, solving their own problems, on their own terms.
The platform is the layer your agents and applications sit on while your field system and IDE continue doing their jobs.
## Security and governance (builder-relevant)
If you are building any app that a user will open in a browser — even an internal tool, a partner portal, or a quick MVP — read [Deploying secure apps](/guides/deploying-secure-apps) before you ship. Coding agents in particular will produce working code that exposes credentials insecurely unless you give them explicit guidance on the frontend/backend split. The checklist on that page is the minimum bar for any user-facing app.
Builders should assume:
* **Data scoping** on every call (`company_id` + validated `api_key`). No API call can cross organisation boundaries.
* **Built-in user management and auth**: invite users, assign roles, issue JWTs. You do not need to build the auth layer yourself.
* **PII handling** aligned with your DPA: do not rebuild sensitive fields into public UIs.
* **Read-only field integration** by default; write-back only when explicitly agreed.
See [Authentication](/authentication) for the full credential surface map and [Deploying secure apps](/guides/deploying-secure-apps) for the deployment checklist.
## Choose your starting kit
| You are | Start here |
| ------------------------------ | ------------------------------------------------------------------------------------------------ |
| Ops lead, no code | [Claude Projects](/agent-kits/claude-projects), [n8n node](/n8n-node) |
| Technical ops / PM with Cursor | [AGENTS.md](/agent-kits/agents-md) + [Cursor rules](/agent-kits/cursor-rules) |
| Engineer building a product | [API overview](/api-reference/overview) + [Operational discovery](/guides/operational-discovery) |
| Agent in Claude Desktop | [MCP setup](/agent-kits/mcp-setup) |
## Related
Architecture narrative for technical buyers.
Connect inboxes, calendars, CRM, and storage.
Platform principles and sovereignty.
Keys, tenancy, and access.