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

# Repository Reference

> Every file the content layer reads from your dbt repository: upsolve.yml, the upsolve/ folder, meta.upsolve on models and columns, and the sync workflow.

A connected repository is an ordinary dbt project with one config file and one folder added. Nothing here changes how dbt itself runs.

```text theme={null}
your-dbt-project/
├── dbt_project.yml
├── models/
│   ├── marts/_marts.yml      ← descriptions, meta.upsolve
│   └── semantic/_metrics.yml ← MetricFlow metrics
├── upsolve.yml               ← dbt target, RLS
├── upsolve/
│   ├── prompts/
│   │   ├── system.md         ← system prompt
│   │   ├── sql.md            ← SQL prompt
│   │   └── chart.md          ← chart prompt
│   ├── skills/
│   │   └── <name>/SKILL.md   ← one folder per skill
│   └── knowledge/
│       └── <slug>.md         ← one file per entry
└── .github/workflows/upsolve-sync.yml
```

The repository is a **mirror**, not a merge: each sync makes the workspace match it. Delete a skill folder and the skill is gone after the next sync; remove `upsolve/prompts/sql.md` and the SQL prompt becomes empty.

## Tables and columns: your dbt models

The workspace's tables are **exactly the dbt models** in the parsed project, read from `target/manifest.json`. Sources, seeds and snapshots are not enabled. Each model's table is found in the [warehouse connection](https://docs.upsolve.ai/ai-agent-builder/content-layer/setup.md#4-warehouse-connection) by the relation dbt writes for it (`schema.alias`), so a model with an `alias` works as expected.

Descriptions come from the model's and each column's `description:`. A `{{ doc() }}` block is rendered by dbt before Upsolve reads it.

### `meta.upsolve`

Upsolve's own settings for a model or column live in dbt's `meta`, which dbt keeps in the manifest as written:

```yaml theme={null}
models:
  - name: fct_purchase_orders
    description: One row per purchase order.
    meta:
      upsolve:
        display_name: Purchase orders
    columns:
      - name: status
        description: Draft, Approved, Received or Cancelled.
        meta:
          upsolve:
            selectable: true
      - name: attributes
        meta:
          upsolve:
            json_parsed: true
```

| Key | On | Effect |
| - | - | - |
| `display_name` | model or column | The name shown in Upsolve instead of the dbt name. |
| `selectable` | column | The agent may look up the column's distinct values when it answers. See [Mark columns as selectable](https://docs.upsolve.ai/ai-agent-builder/data-models.md#mark-columns-as-selectable). Default `false`. |
| `json_parsed` | column | The column holds JSON whose keys the agent may query as columns of their own. See [JSON columns](https://docs.upsolve.ai/embedded-bi/data-connection/json-columns.md). Default `false`. |

`meta` set with `config: meta:` in `dbt_project.yml` or a model's `config()` block works too.

## `upsolve.yml`

At the repository root. The setup pull request adds it; a sync refuses to run without it. It is read strictly: invalid YAML, or a block of the wrong shape, stops the sync with the workspace untouched.

```yaml theme={null}
version: 1
environments:
  production:
    target: prod          # the dbt target the workflow parses

rls:                      # optional — Team plan
  require_on_facts: true  # optional
  rules:
    - name: Tenant isolation
      column: organization_id
      operator: "="
      property: organization.id
  tables:
    dim_suppliers:
      where: "region = '{{user.region}}'"
```

### `environments.production.target`

The dbt target `dbt parse` runs against. The workflow reads it on every run, so changing it here changes what the next sync reads. The **branch** a workspace listens to is not in this file: it is set in Upsolve (Settings → Git), so one repository can feed a staging workspace and a production one.

### `rls`

[Row-level security](https://docs.upsolve.ai/ai-agent-builder/data-governance.md) for the workspace, in the same two forms as the Data Model editor's.

**`rules`** are global rules, applied to every table they fit:

| Key | |
| - | - |
| `name` | Shown in Upsolve. Optional. |
| `column` | Filter every table that has this column... |
| `operator` | ...with one of `=`, `!=`, `IN`, `IS NULL`, `IS NOT NULL`... |
| `property` | ...against this property of the person asking: `user.<key>` or `organization.<key>`. |
| `schema` | Instead of `column`: read each table from the schema this property names (one schema per tenant). |
| `optional` | When `true`, a user without the property sees the table unfiltered instead of being refused. Default `false`. |

**`tables`** gives one model its own condition, keyed by **dbt model name**, which replaces the global rules on that model. `where` is one SQL condition on the model's own columns. Fill in the person asking with `{{user.<key>}}` or `{{organization.<key>}}`; any other `{{…}}` is refused, since it would reach the database as written.

**Models behind a metric must be filtered.** Once `upsolve.yml` declares any row-level security, every model behind a MetricFlow measure must be filtered — by its own `tables` condition, a schema rule, or a column rule on a column it has. MetricFlow joins dimension tables onto the facts, so a rule on a dimension table alone filters none of the facts' rows: a metric would add up every tenant's numbers. A sync that leaves one unfiltered stops with `FACT_TABLE_NOT_FILTERED`.

**`require_on_facts`**: when `true`, it is stricter: every model behind a MetricFlow measure needs a condition of **its own** under `tables`. A global rule that would filter it does not count. Turn it on when you want every fact table's filter written out explicitly.

> [!WARNING]
>
> RLS in `upsolve.yml` needs the **Team plan**, and a commit that **loosens** it waits for an owner or admin to accept it before it is published. See [Row-level security is reviewed twice](https://docs.upsolve.ai/ai-agent-builder/content-layer/overview.md#row-level-security-is-reviewed-twice).

## `upsolve/prompts/`

| File | Becomes |
| - | - |
| `system.md` | The workspace's [system prompt](https://docs.upsolve.ai/ai-agent-builder/system-prompts.md), used whole after Upsolve's own guardrails. |
| `sql.md` | The SQL generation prompt. |
| `chart.md` | The chart generation prompt. |

A missing file is an empty prompt. Working memory is not a prompt the repository holds; it stays in Upsolve.

![Repository, System Prompts tab: a banner says the prompts are defined in upsolve/prompts/ and read-only, with the system prompt and chart generation prompt filled from the repository and the SQL generation prompt not set](https://mintcdn.com/upsolve/ly_6q_O7-mhPeQj9/images/ai-agent-builder/content-layer/repository-prompts.png?fit=max\&auto=format\&n=ly_6q_O7-mhPeQj9\&q=85\&s=ea19bcb5cfb746bbc0c777bc223d75be)

## `upsolve/skills/<name>/SKILL.md`

One folder per [skill](https://docs.upsolve.ai/ai-agent-builder/skills.md). The folder name is the skill's name: lowercase letters, digits and hyphens. The file is front matter plus the instructions:

```markdown theme={null}
---
name: supplier-scorecard
description: >
  Score a supplier on spend, on-time delivery and contract
  compliance. Use when asked how a supplier is performing.
---

1. Use the `spend`, `on_time_delivery_rate` and
   `contract_compliance_rate` metrics.
2. Compare against the category average over the same period.
```

## `upsolve/knowledge/<slug>.md`

One Markdown file per [knowledge base](https://docs.upsolve.ai/ai-agent-builder/knowledge-base.md) entry. The file name is its slug (lowercase letters, digits and hyphens), and its first `# ` heading is its title.

```markdown theme={null}
# Metric definitions

Spend excludes cancelled purchase orders...
```

## `.github/workflows/upsolve-sync.yml`

Added by the setup pull request. On every push and pull request it installs dbt and your adapter, reads the target from `upsolve.yml`, runs `dbt deps` (when you have `packages.yml`) and `dbt parse`, and uploads an `upsolve-sync` artifact holding `target/manifest.json`, `target/semantic_manifest.json`, `upsolve.yml` and `upsolve/`. Artifacts are kept for seven days.

It runs on every branch so a workspace can switch branches, or a second workspace can listen to another one, without editing it. Upsolve reads only runs for **pushes** to the branch a workspace listens to; pull request runs are checks.

You may edit it (pin dbt, add a step), as long as it still uploads the same artifact under the same name.

> [!NOTE]
>
> `dbt parse` never connects to your warehouse and needs no credentials. See [If you don't commit a profiles.yml](https://docs.upsolve.ai/ai-agent-builder/content-layer/setup.md#if-you-dont-commit-a-profilesyml) for how the workflow builds a profile.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.