> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velatir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> The key parts of the Velatir platform and how they fit together.

## The Building Blocks

Velatir is built around a small set of concepts. Once these click, the rest of the platform follows.

<CardGroup cols={2}>
  <Card title="Organisation & workspaces" icon="building" href="/platform/organizations-and-workspaces">
    Your organisation is the top-level account. Workspaces sit inside it and separate activity by team, department, or project.
  </Card>

  <Card title="Sessions & traces" icon="activity" href="/traces/understanding-sessions">
    Every AI interaction is captured as a trace. Related traces are grouped into a session that represents a complete conversation or workflow.
  </Card>

  <Card title="Agents" icon="shield-check" href="/agents/understanding-agents">
    Gatekeeper and Data Protector review every trace. Gatekeeper controls which services can be used, and Data Protector catches sensitive content.
  </Card>

  <Card title="Assessments" icon="list-checks" href="/agents/assessments">
    Each agent records an assessment for every trace it reviews, with the verdict and the reasoning behind it.
  </Card>

  <Card title="Instructions" icon="fingerprint" href="/agents/instructions">
    Your own rules that tell an agent what to do in a specific scenario, such as always blocking a project codename.
  </Card>

  <Card title="Insights" icon="chart-line" href="/insights/overview">
    Aggregated views of how your organisation uses AI, where activity concentrates, and what agents are catching.
  </Card>
</CardGroup>

## How They Fit Together

<Steps>
  <Step title="A trace is captured" icon="activity">
    An AI interaction, in the browser or a desktop app, is captured and sent to Velatir as a trace. Each trace has a direction: **Inlet** (a request to an AI service), **Response** (a reply from it), or **Signal** (an event). Related traces are grouped into a session.
  </Step>

  <Step title="Agents assess it" icon="shield-check">
    Your active agents review the trace at the same time. Each one records an assessment and reaches a verdict, applying your categories and instructions.
  </Step>

  <Step title="The outcome is resolved" icon="scale">
    The verdict depends on each agent's role. An Observer flags its findings for review. An Enforcer can block the trace or escalate it for approval. The most restrictive outcome wins.
  </Step>

  <Step title="People are notified" icon="bell">
    If a trace is escalated, it is sent to your connected channels so the right people can respond.
  </Step>

  <Step title="Everything is logged" icon="check">
    The trace, each assessment, and the outcome are recorded for audit purposes.
  </Step>
</Steps>

## Key Principles

### Traces are the foundation

Every AI interaction is captured as a trace. This gives your organisation full visibility into AI usage.

### Agents handle the volume

Agents review every trace automatically. People only see what an agent flags or escalates.

### Roles control authority

Each agent runs as an Observer or an Enforcer. You can start with monitoring only and add enforcement as you build confidence.

### Instructions tune behaviour

Instructions let you teach an agent how to treat a specific scenario, so its verdicts match your organisation over time.

### Everything is auditable

Every trace, assessment, decision, and outcome is logged with full context. Your compliance trail is always complete.

## Organisation and Workspaces

| Concept                | Description                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Organisation**       | Your company account. Holds members, settings, agent defaults, and your subscription.                                    |
| **Workspace**          | A space within your organisation for a team, department, or project. Workspaces can nest, and each has its own activity. |
| **Organisation roles** | **Administrator** (full access) and **Reader** (view only).                                                              |
| **Workspace roles**    | **Admin**, **Editor**, and **Reader**, with progressively fewer permissions.                                             |

See [Roles & permissions](/platform/roles-and-permissions) for the full breakdown.

## Trace Directions

| Direction    | Description                            | Example                                      |
| ------------ | -------------------------------------- | -------------------------------------------- |
| **Inlet**    | A request going to an AI service       | Someone submits a prompt to a chat assistant |
| **Response** | A reply coming back from an AI service | The assistant's answer                       |
| **Signal**   | A related event                        | A session starting, or a background event    |

## Assessment Outcomes

| Outcome       | What it means                                             |
| ------------- | --------------------------------------------------------- |
| **Allowed**   | The agent had no concern. The trace proceeds.             |
| **Flagged**   | An Observer noted a finding for review, without blocking. |
| **Blocked**   | An Enforcer stopped the trace.                            |
| **Escalated** | The trace was sent to a person for review or approval.    |

***

<CardGroup cols={2}>
  <Card title="Understanding agents" icon="shield-check" href="/agents/understanding-agents">
    Meet Gatekeeper and Data Protector.
  </Card>

  <Card title="Trace lifecycle" icon="refresh-cw" href="/traces/trace-lifecycle">
    Follow a trace from capture to final state.
  </Card>
</CardGroup>