> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/v1/resources/vulcan/configurations/usage.md).

# Usage guidance

`usage.yaml` is an optional, business-facing companion to `config.yaml`. Where `config.yaml` tells Vulcan how to run a project (dialect, gateways, models, hooks, linting), `usage.yaml` tells a human consumer how the resulting data product is meant to be used.

Think of it as the "read me before you query this" document for a data product: what it's good for, what it isn't for, what caveats to keep in mind, where to find more detail, and, if relevant, what it costs. It carries no runtime configuration and has no effect on how Vulcan plans, runs, or executes models. It exists purely to communicate intent and boundaries to downstream consumers.

`usage.yaml` sits alongside `config.yaml` in a project and is referenced from it via the `usage_path` key (or inline via `usage`). See [Configurations](/references/v1/resources/vulcan/configurations.md) for how it fits into the overall project layout.

No key is required, and the file itself is optional. If it's missing entirely, Vulcan falls back to empty usage guidance plus a default internal pricing plan. It's safe to omit until you have real content to put in it.

## When to create `usage.yaml`

Add this file once your data product has real consumers and you want to answer the questions they'll ask before touching the data: what is this good for, what should I not use it for, what are the known gaps, and where do I go for more detail. Skip it while a project is still exploratory or has no external consumers yet. An empty or missing file is a valid state.

## Top-level keys

| Key             | Type       | Required | When to use                                                                                                   | When to skip                                                                    |
| --------------- | ---------- | :------: | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `objectives`    | list\[str] |    No    | You want to state up front what the data product is trying to achieve.                                        | Objectives are already obvious from `description` in `config.yaml`.             |
| `alignments`    | list\[str] |    No    | You want to record Data Mesh alignment(s) relevant to this product's usage story.                             | `alignment` in `config.yaml` already covers it and no further nuance is needed. |
| `good_for`      | array      |    No    | You know specific use cases this product supports well and want to guide consumers toward them.               | No clear use cases have emerged yet.                                            |
| `not_for`       | array      |    No    | You know use cases this product should *not* be used for (wrong grain, stale data, etc.).                     | There are no known anti-patterns yet.                                           |
| `caveats`       | array      |    No    | There are limits, freshness delays, exclusions, or gotchas consumers should know before relying on this data. | The product has no meaningful caveats.                                          |
| `references`    | array      |    No    | You want to point consumers to docs, dashboards, runbooks, or tickets for more detail.                        | No supporting material exists yet.                                              |
| `pricing_plans` | array      |    No    | This product is billed/charged for and you want to document the plan(s).                                      | Internal, unbilled usage: the default internal plan applies automatically.      |

## `good_for`, `not_for`, `caveats`: shared shape

Each of these accepts a list where every item is either a plain string (quick note) or an object with more structure. Use plain strings for short, self-explanatory points; use the object form when you need to add detail or (for caveats) a severity.

**Object form:**

| Field      |      Required     | Description                                       |
| ---------- | :---------------: | ------------------------------------------------- |
| `title`    |        Yes        | The headline statement.                           |
| `details`  |         No        | Extra context or explanation.                     |
| `severity` | No (caveats only) | `low`, `medium`, or `high`. Defaults to `medium`. |

```yaml
good_for:
  - Customer analytics and segmentation          # plain string
  - title: Revenue reporting and forecasting      # object form
    details: Planning, board reporting, and trend analysis across segments

not_for:
  - Real-time alerting
  - title: Real-time operational decisions
    details: Data refreshes weekly. Not suitable for alerting or live dashboards

caveats:
  - Historical data available from 2024-01-01
  - title: Weekly refresh cadence
    details: Updates every Monday ~6am UTC; answers can be up to 7 days stale
    severity: medium
```

When to reach for `severity` on a caveat: use `high` for anything that could lead to a wrong business decision if missed (e.g., known data quality issues, incomplete history), `medium` for freshness/latency notes, and `low` for minor exclusions or edge cases.

## `references`

| Field   | Required | Description                                                                          |
| ------- | :------: | ------------------------------------------------------------------------------------ |
| `title` |    Yes   | Link text shown to consumers.                                                        |
| `url`   |    Yes   | Where the reference points.                                                          |
| `type`  |    No    | `doc`, `design`, `dashboard`, `runbook`, or `other`. Helps consumers filter by kind. |

```yaml
references:
  - title: Vulcan book
    url: https://tmdc-io.github.io/vulcan-book/
    type: doc
```

Use `references` for anything a consumer might need mid-investigation: a runbook when something looks wrong, a dashboard that already answers common questions, or a design doc explaining why the model is shaped the way it is.

## `pricing_plans`

| Field              | Required | Description                                        |
| ------------------ | :------: | -------------------------------------------------- |
| `name`             |    Yes   | Plan identifier.                                   |
| `unit`             |    Yes   | What's being billed (e.g., `query`, `seat`, `GB`). |
| `price`            |    No    | Numeric price.                                     |
| `price_currency`   |    No    | Currency code (e.g., `USD`).                       |
| `billing_duration` |    No    | Billing period (e.g., `month`).                    |
| `notes`            |    No    | Free-text clarification.                           |

Only add `pricing_plans` when the product is actually metered or billed outside the platform default. If you don't set this, Vulcan applies a default internal pricing plan automatically. There's no need to declare a $0 plan just to be explicit.

## Minimal vs. complete example

Minimal, safe to start with, or even omit the file entirely:

```yaml
good_for:
  - Customer analytics and segmentation

not_for:
  - Real-time alerting
```

Complete, once the product is mature enough to need all of it:

```yaml
objectives:
  - Provide a single trusted source for order lifecycle metrics

alignments:
  - consumer_aligned

good_for:
  - Customer analytics and segmentation
  - title: Revenue reporting and forecasting
    details: Planning, board reporting, and trend analysis across segments

not_for:
  - Real-time alerting
  - title: Real-time operational decisions
    details: Data refreshes weekly. Not suitable for alerting or live dashboards

caveats:
  - title: Weekly refresh cadence
    details: Updates every Monday ~6am UTC; answers can be up to 7 days stale
    severity: medium

references:
  - title: Vulcan book
    url: https://tmdc-io.github.io/vulcan-book/
    type: doc

pricing_plans:
  - name: internal-default
    unit: query
    price: 0
    price_currency: USD
    billing_duration: month
    notes: Default internal pricing plan; no external billing applies
```

## Related pages

* [Configurations overview](/references/v1/resources/vulcan/configurations.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/references/v1/resources/vulcan/configurations/usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.