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

# Define your first intention

> Move from anonymous observation to identity-aware shadow-mode enforcement.

An **intention** is a declarative rule: "for this kind of work, these elements
are allowed, with this TTL." Defining your first intention graduates your
adoption from L1 (observe) to L2 (test) on the
[maturity model](/concepts/maturity-model).

## Where intentions come from

Two paths:

1. **Generalize from observation** — Inviolet's `Generalize` workflow
   suggests intentions based on observed query patterns. Best for teams with
   2+ weeks of observation data.
2. **Manual declaration** — write an intention against a known workflow. Best
   for greenfield use cases.

This guide covers the manual path. For the generalize-from-observation
path see [Generalize from observation](/guides/generalize-from-observation).

## Anatomy of an intention

```yaml theme={"dark"}
id: customer_support_lookup
name: "Customer Support Lookup"
description: "Look up a customer's identity + recent order history when answering a support ticket."
elements:
  - customer.name
  - customer.email
  - customer.order_history
ttl_seconds: 300
identity_required: true
approval_required: false
```

* **`elements`** is the column allowlist. Anything outside this list will be
  rewritten or blocked at the database proxy.
* **`ttl_seconds`** bounds the lifetime of any grant minted under
  this intention.
* **`identity_required`** forces an IdP-authenticated user\_id to be present
  on every call.
* **`approval_required`** routes the call through a Slack / email approval
  queue before any grant is minted.

## Create the intention

1. App dashboard → **Intentions** → **Compose** (new in Phase 18 lifecycle)
2. Fill the form fields above
3. Save — the intention is created in **shadow mode** by default

## Run in shadow mode

Shadow mode evaluates the policy on every matching tool call but does NOT
block anything. The decision feed shows what *would* have happened. Watch
this for a week or two.

## Promote to live

Once the shadow stats look right (low false-positive denials, high
match-rate on intended traffic), promote with one click:

App dashboard → **Intentions** → pick the intention → **Promote to live**

Promotion is immediate. The next matching tool call gets a live decision
written to the audit log.

## Read next

* **[Generalize from observation](/guides/generalize-from-observation)** — the alternate creation path
* **[Mandates](/concepts/mandates)** — what gets minted on approval