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

# Maintenance

> Create, update, and maintain knowledge base documents

Use `/knowledge` to create and edit documents. The agent structures content consistently, validates SQL, and adds wiki links between related documents. You can also edit documents directly in the knowledge base UI.

<Note>
  `/knowledge` requires the Developer role. Explorers can use the analytics agent but cannot modify the knowledge base.
</Note>

## Creating documents

**Document a table:**

```text theme={null}
/knowledge Document the sales.orders table.
Revenue = total_amount where status = 'completed'. Always exclude test accounts.
```

The agent creates a document at `sales/table/orders` with schema, relationships, common filters, and usage notes.

**Create a metric:**

```text theme={null}
/knowledge Create a metric for MRR.
MRR = sum of monthly subscription prices for active subscriptions.
Exclude trial and test customers.
```

The agent creates a document at `finance/metric/mrr` with the business definition, tested SQL, source tables, and filters.

**Create a business rule:**

```text theme={null}
/knowledge Document the rule for excluding test data.
Test accounts have is_test_account = TRUE or email ending in @company.com.
```

**Create a note:**

```text theme={null}
/knowledge Create an overview note for the sales namespace.
Covers order transactions, customer relationships, and revenue tracking.
```

## Providing better context

The more context you give, the better the documentation. Compare:

```text theme={null}
/knowledge Document the orders table
```

vs:

```text theme={null}
/knowledge Document the sales.orders table.
Key columns: order_id, customer_id, total_amount, status, order_date.
Revenue = total_amount where status = 'completed'.
Join to customers on customer_id. Exclude test orders where customer.is_test = true.
```

## Namespace structure

Documents are organized hierarchically: `{domain}/table/{name}`, `{domain}/metric/{name}`, `{domain}/rule/{name}`, `{domain}/note/{name}`. Documents reference each other with wiki links like `[[sales/table/orders]]`.

## Keeping documentation current

**Schema changes** — when tables are renamed or columns change:

```text theme={null}
/knowledge The orders table was renamed to sales_orders. Update all documents.
```

**Fix incorrect SQL:**

```text theme={null}
/knowledge The MRR metric should exclude churned subscriptions.
Update the SQL to filter where status != 'churned'.
```

**Update business definitions:**

```text theme={null}
/knowledge Enterprise is now ARR >= \$50k (changed from \$100k). Update all metrics.
```

**Validate periodically:**

```text theme={null}
/knowledge Validate all metric SQL queries and fix any errors
```

```text theme={null}
/knowledge Check all wiki links and report any broken references
```

**Add new documentation** as your data grows:

```text theme={null}
/knowledge Document the new marketing.campaigns and marketing.ad_spend tables
```

For larger additions, configure new sources and run **Update Knowledge** from **Context > Jobs**. See the [Onboarding guide](/knowledge-agent/onboarding).