For the complete documentation index, see llms.txt. This page is also available as Markdown.

Overview

The router — every page in these docs and what it answers. Ground vocabulary here, then read the narrowest page.

The building blocks of a .lynk project, and the map of every page in these docs. Lynk distinguishes primitives that general analytics vocabulary blurs — a metric is entity-local, a feature is row-grain, a skill is reasoning, a policy is behavior. Ground your vocabulary in the map below, then read the narrowest page that answers the question. For the mental model of how the primitives fit together, start with the Overview.

Every page, and what it answers

Concepts

  • Project — A Lynk project is a self-contained git repository — one repo, one customer — consumed as versioned, validated builds.

  • lynk.yml — The required project settings file at the .lynk/ root — schema_version, topology, and name.

  • LYNK.md — LYNK.md is the agent's orientation and identity — who the business is, who a team is, and how they think. Always loaded.

  • GLOSSARY.yml — GLOSSARY.yml is the team's vocabulary — the terms they use and what they mean, always loaded and merged across scopes.

  • Domain — A domain is an agent — one team's analytical surface, with its own vocabulary, entities, skills, and policies. A user talks to one at a time.

    • LYNK.md (domain) — A domain's LYNK.md — who this team is. Appended to the root LYNK.md; extends it, never replaces it.

    • GLOSSARY.yml (domain) — A domain's GLOSSARY.yml — the team's vocabulary, merged over the root glossary with the domain winning on a key collision.

  • Entity — An entity is a lazy, encapsulated representation of a thing in the business — a folder holding an ENTITY.md prose file and a schema.yml definition.

    • ENTITY.md — ENTITY.md is the prose side of an entity — quirks, conventions, and business context the agent reads. Short by design, frontmatter required.

    • schema.yml — schema.yml is the structured definition of an entity — identity, keys, imports, features, metrics, and relationships.

      • Identity and Imports — identity roots an entity in a warehouse table or view, or another entity; keys identify its rows; imports cherry-pick definitions from a parent entity.

      • Feature — A feature is a queryable, row-grain attribute of an entity — a column, a derivation, or a value pulled across a relationship.

      • Metric — A metric is an aggregation defined on the entity it aggregates — sum, count, average, conditional aggregates — invoked with metric().

      • Relationships — Relationships declare a path from an entity to a physical table or another entity — directional, per-step joins with cardinality.

  • Policy — Policies are eager, always-apply behavioral commitments — output format, clarification behavior, and other rules for how the agent operates.

  • Skill — Skills are lazy prose procedures for classes of analytical reasoning — how the agent thinks through an analysis, not what exists in the data.

  • Reference Files — Reference files — user-organized files outside the domain primitives, the escape hatch for cross-cutting content, reached by absolute /.lynk/ references.

Guides

  • Placing knowledge in a layer — How to decide where a piece of knowledge belongs — entity prose, schema, glossary, metric, skill, policy, LYNK.md, or a reference file.

  • Choosing and shaping entities — How to decide what becomes an entity and how to shape it — the entity test, grain, promoting table relationships to entities, the upstream boundary, and base-row hygiene. Reach for it before adding or restructuring entities.

  • Modeling metrics, time, and state — How to place a computation — feature, metric, skill, or glossary term — and how to model balances, time windows, cohorts, and ratio KPIs correctly.

  • Designing domains — How to decide how many domains to create, what belongs in the shared domain, and when to promote, extend, split, or merge.

  • Budgeting the agent's context — How to budget the agent's context — deciding @ injection vs a link, splitting a growing ENTITY.md, placing content at root vs domain, and when a rule earns a policy.

  • Evolving a live layer — How to change a live semantic layer — logging definition changes, renaming a shared feature or metric safely, deprecating with enabled false, and landing breaking changes across domains.

  • Reading a complete layer — A complete, annotated .lynk/ project for Grove (B2B SaaS) — every file of a small correct layer, end to end, with the reasoning behind each choice. Read when you want the whole shape at once instead of per-concept fragments.

Reference

  • Layout and Naming — The .lynk/ directory tree, the rules for naming folders and files, and the settings that control how a project is built.

  • Markdown Format — The frontmatter contract shared by every Markdown primitive, the reference grammar (@ injection, markdown links, bare paths), and how supporting files are organized.

  • SQL Expressions — The reference grammar inside schema.yml sql fields — segment-count path resolution, the metric/first/last functions, filters, and join binding.

  • What Lynk doesn't do — The boundaries in one place — testing and evaluations, metric parameterization, templating, tags, scheduling, cross-domain queries — what Lynk doesn't do by design, what's planned, and what belongs upstream, with the supported alternative for each.

API Reference

  • API Reference — The programmatic interfaces — the Lynk SQL query dialect and the REST endpoints for validation and catalog inspection.

    • Lynk SQL — The query dialect — warehouse SQL plus metric(.) and USING('<join_name>'); entity references, joins, CTEs, windows, supported statements, pitfalls.

    • REST API — HTTP endpoints for validating the semantic layer and inspecting the data catalog — full documentation in progress.

Last updated