> For the complete documentation index, see [llms.txt](https://docs.getlynk.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getlynk.ai/concepts/glossary.md).

# GLOSSARY.yml

The team's vocabulary, structured for the agent to read. Each entry is a term the team uses and what it means.

## What it is

When a user mentions a term in a question, the agent resolves it against the glossary to understand what they mean. When the agent writes an answer, it draws on the glossary for the names the team actually uses. The glossary is how the agent speaks the team's language.

**A glossary entry has no structured pointer to an entity or metric — the agent resolves a term only by reading its prose, so the description must stand on its own.** It is always loaded as part of orientation, and the agent reads the whole merged glossary to resolve each term.

A term that is really *a way of computing* — "customer health" combining engagement, payment, and support signals — usually wants to be a [skill](/concepts/skill.md), not a glossary entry. The glossary defines what words mean; skills define how to reason.

## Where it lives

One `GLOSSARY.yml` at the project root, and optionally one inside each domain:

```
.lynk/GLOSSARY.yml                      # shared vocabulary
.lynk/domains/marketing/GLOSSARY.yml    # marketing's terms
```

## Format

A YAML file. Each top-level key is a term, in snake\_case — the stable address the [`@` operator](/reference/markdown-format.md#references) points at (`@glossary.expansion.description`).

```yaml
expansion:
  name: Expansion
  description: Additional recurring revenue from an existing customer — upsells, seat growth, or plan upgrades. Counted separately from new-logo revenue.
```

| Field         | Required | Type        | Notes                                                                                                     |
| ------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| key           | ✓        | snake\_case | The stable address. `@glossary.<key>` resolves here.                                                      |
| `name`        | ✓        | string      | The term as the team writes it.                                                                           |
| `description` | ✓        | string      | What the term means, in prose. Long forms, abbreviation expansions, and clarifying context all live here. |

**Composition merges across scopes.** The effective glossary in a domain is the root glossary merged with the domain's, with the **domain winning** on a key collision. A glossary reference never needs a domain prefix — it is already resolved against the merged result.

Lynk ships no default — the glossary is empty until you author it.

## Examples

**A single term.**

```yaml
active_customer:
  name: Active Customer
  description: A customer who has logged in within the last 90 days.
```

**A domain glossary (Grove, B2B SaaS) that overrides and extends the root.**

```yaml
logo_churn:
  name: Logo Churn
  description: A customer fully cancelling, counted as one lost logo regardless of contract size. Distinct from revenue churn, which weights by ARR.

ndr:
  name: NDR
  description: Net Dollar Retention. Revenue retained from existing customers over a period including expansion, contraction, and churn — excluding new logos.

at_risk:
  name: At Risk
  description: An active customer showing churn signals — declining usage, a pending cancellation, or an NPS detractor score in the last quarter.
```

## Validation

* Each entry declares `name` and `description`. A missing required field fails the build.
* Keys are snake\_case. On a root/domain key collision, the domain entry wins (this merge is expected, not an error).

## Related

* [Domain → GLOSSARY.yml](/concepts/domain/glossary.md) — the domain-scoped vocabulary that merges over this file
* [LYNK.md](/concepts/lynk-md.md) — orientation, which the glossary is not
* [Skill](/concepts/skill.md) — where *ways of computing* live, rather than the glossary
* Guides: [Placing knowledge in a layer](/guides/where-knowledge-goes.md) · [Modeling metrics, time, and state](/guides/metrics-time-and-state.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://docs.getlynk.ai/concepts/glossary.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.