# Guides

**Task-focused how-to guides for extending an existing Lynk project.**

Use this section when you already have a working semantic layer and need to add something new — a new entity, a new feature — without rebuilding from scratch. Each guide is a focused checklist that walks through every required step in the right order.

***

## What's in this section

| Page                                                                                         | When to use it                                                                                                                                         |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Adding an Entity](https://docs.getlynk.ai/guides/guides/adding-an-entity)                   | You're modeling a new business concept the agent should be able to query — from YAML through relationships, context files, and evaluations             |
| [Adding a Feature](https://docs.getlynk.ai/guides/guides/adding-a-feature)                   | You're adding a new attribute to an existing entity — includes a decision tree to pick the right feature type (field / first\_last / formula / metric) |
| [Writing Evaluations](https://docs.getlynk.ai/guides/guides/writing-evaluations)             | You need to write regression test cases — covers what to test, how to write `expected_output`, and how to run evaluations in the UI                    |
| [Writing Task Instructions](https://docs.getlynk.ai/guides/guides/writing-task-instructions) | The agent is generating wrong SQL — covers how to identify the right rule, choose the right scope, and verify the fix                                  |
| [Troubleshooting](https://docs.getlynk.ai/guides/guides/troubleshooting)                     | Agent returned a wrong answer, an evaluation failed, or context isn't loading — diagnostic steps for the most common problems                          |

***

## What you can do with this

Use these guides to:

* Add a new entity correctly — without missing steps that cause the agent to fail (missing relationships, missing context files)
* Choose the right feature type for what you're trying to express — and understand why the wrong choice produces wrong results
* Follow a verified checklist so nothing is skipped before you run evaluations and push to production

**Before using these guides:**

* If you're building a project from scratch, start with the [Project Walkthrough](https://docs.getlynk.ai/tutorial/project) instead — it covers the right build order for a new project
* If you need the exact field-level syntax for a file you're writing, see [File-Types Reference](https://docs.getlynk.ai/file-types-reference/file-types)