> 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/entity/entity-md.md).

# ENTITY.md

The prose side of an [entity](/concepts/entity.md) — what the agent reads to understand the entity's character: quirks, conventions, gotchas, business context. The kind of thing a senior teammate tells a new hire.

## What it is

Where [`schema.yml`](/concepts/entity/schema-yml.md) defines structure, `ENTITY.md` carries prose. It's the orientation an analyst needs before running any analysis on this thing — not exhaustive documentation, just the few things every analysis must know.

It is **not** the place for:

* definitions of features or metrics — those are in [`schema.yml`](/concepts/entity/schema-yml.md);
* domain-wide context — that's [`LYNK.md`](/concepts/lynk-md.md);
* vocabulary — that's [`GLOSSARY.yml`](/concepts/glossary.md);
* operational behavior like output format — that's a [policy](/concepts/policy.md).

## Where it lives

One per entity, alongside `schema.yml`:

```
.lynk/domains/<domain>/entities/<entity>/ENTITY.md
```

## Format

Frontmatter (the shared [contract](/reference/markdown-format.md#frontmatter-contract)) over an optional prose body.

**Frontmatter is required.** Lazy loading depends on it: the agent reads each entity's `name` and `description` at index time to decide whether to load the entity for a given question. Write the `description` to signal what the entity is *for* — what kinds of questions it answers.

**`enabled: false` disables the whole entity.** The flag lives on `ENTITY.md`, but it governs the entire entity — `schema.yml` included. A disabled entity can't be queried, referenced, or imported; it's as if it weren't there, so a reference to it fails the build like a reference to a missing entity. See [Markdown format](/reference/markdown-format.md#frontmatter-contract).

**The body should be short.** `ENTITY.md` loads as a unit whenever the entity is activated, so a long body taxes every analysis that touches the entity. A typical body covers:

* a brief framing of what the entity represents;
* conventions the team uses (vocabulary nuances, how they talk about this thing);
* quirks or gotchas in the data that affect most analyses;
* pointers to deeper content via [`@` injection](/reference/markdown-format.md#references).

The body is optional — an entity with no quirks worth flagging can have an empty body; the frontmatter alone makes it loadable. Keep `ENTITY.md` lean and inject only what every analysis needs; leave deeper content un-injected so the load cost stays honest.

## Examples

**Frontmatter only.**

```markdown
---
name: subscription
description: Active and historical subscriptions. One row per subscription. Use for MRR, billing cycle, and cancellation analysis.
enabled: true
---
```

**Grove's `customer`, with conventions, a quirk, and an injected file.**

```markdown
---
name: customer
description: Grove accounts. One row per company. Use for ARR, churn, and plan-tier analysis.
enabled: true
---

# Customer

One row per company that has signed up. The team uses "customer" and "account"
interchangeably.

**Conventions.** Most analyses exclude test and deleted accounts
(`is_test_account = false`, `is_deleted = false`). "Churned" is defined in
@glossary.logo_churn.description.

**Quirk.** `first_paid_at` is null for trials — filter it out when measuring
time-to-paid, or the cohort skews.

@/.lynk/domains/core/entities/customer/instructions/fiscal-year.md
```

## Validation

* `ENTITY.md` exists and carries valid frontmatter — `name` (matching the folder) and `description`. A missing required field fails the build.

## Related

* [Entity](/concepts/entity.md) — the entity folder and the two-file split
* [schema.yml](/concepts/entity/schema-yml.md) — the structured side, where definitions live
* [Markdown format](/reference/markdown-format.md) — the frontmatter contract and `@` injection
* Guides: [Budgeting the agent's context](/guides/context-engineering.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/entity/entity-md.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.