Tier System

RunContext uses a three-tier maturity model to measure how complete and AI-ready your metadata is. Each tier builds on the previous one, adding more context and governance until your semantic layer is fully prepared for autonomous AI consumption.

You can check your current score at any time with:

context tier

This command evaluates every dataset and field against the tier requirements below, producing a per-model and aggregate score.

Bronze — Scaffolded

Bronze is the baseline — scaffolded metadata generated automatically from database introspection. It means the data exists in your semantic plane and has enough metadata for a human or AI to find it and understand what it is at a surface level.

How to achieve it: Run context setup or context introspect against your data source. RunContext connects to your database, reads table and column metadata, and generates OSI and governance files automatically.

context introspect --source my_warehouse

Bronze requirements

Requirement	Description
Description	Every dataset and field must have a human-readable description (auto-generated from introspection).
Ownership	At least one owner (team or individual) is assigned to the dataset.
Security classification	Each field has a sensitivity level (e.g., public, internal, confidential, restricted).
Grain	The dataset declares its grain — the set of columns that uniquely identify a row.
Table type	The dataset is classified as fact, dimension, staging, snapshot, or another recognized type.

At Bronze, you know what exists and who owns it. This is the scaffolded output of introspection — you do not yet know whether to trust it or how an AI should use it.

Silver — Trusted

Silver adds the context needed to trust and correctly interpret the data. Fields are linked to business definitions, lineage is documented, and enough metadata exists for an AI to use the data without hallucinating relationships.

How to achieve it: After introspection, run the enrich command targeting Silver. RunContext uses LLM-assisted enrichment to fill in gaps automatically.

context enrich --target silver

Silver requirements

All Bronze requirements, plus:

Requirement	Description
Trust status	Each dataset has an explicit trust status (trusted, verified, unverified, deprecated).
Glossary links	Fields are linked to terms in the business glossary, connecting technical column names to business language.
Lineage	Upstream sources are documented — where the data comes from and what transformations produced it.
Sample values	Representative sample values are recorded for each field, so consumers can understand format and range without querying the warehouse.
Refresh cadence	The dataset declares how often it is updated (hourly, daily, weekly, manual, etc.).
Tags	Datasets and fields carry categorical tags for discovery and filtering.

At Silver, you have a semantic layer that a careful analyst could work with confidently. Automated tools can query it without needing to guess at meaning.

Gold — AI-Ready

Gold is the highest tier. Every field carries explicit instructions for how AI agents should interpret and use it. Ambiguities are resolved, guardrails are in place, and golden queries provide tested examples of correct usage.

How to achieve it: Gold requires agent-driven curation. Your AI agent (in Claude Code, Cursor, or Copilot) connects to your actual database via MCP, queries real data, and fills in the deep semantic metadata that only comes from understanding the data itself. Copy the MCP config into your IDE and paste the curation prompt — the agent does the heavy lifting, consulting you on business logic along the way.

Gold requirements

All Silver requirements, plus:

Requirement	Description
Semantic roles on all fields	Every field has an explicit role: identifier, measure, attribute, date, currency, status, flag, category, foreign_key, etc.
Golden queries (3+)	At least three tested, approved SQL queries that demonstrate correct usage of the dataset. AI agents reference these as examples.
Guardrail filters	Required filters are declared on datasets (e.g., “always filter on is_deleted = false”) to prevent AI from returning misleading results.
Business rules	Prose or structured rules explaining business logic (e.g., “revenue is recognized at shipment, not at order”).
Hierarchies	Dimensional hierarchies are defined (e.g., country > region > city) so AI agents can drill up and down correctly.
Rich descriptions	Detailed, AI-friendly descriptions on every dataset and field, beyond the auto-generated Bronze descriptions.
Endorsed trust	Dataset trust status is explicitly set to trusted or verified by a data owner.
Contactable owner	Owner record includes a reachable contact (email, Slack handle, or equivalent).
Relationships	All foreign-key and logical relationships between datasets are explicitly declared with cardinality.

The path from Bronze to Gold

The key insight is that the setup wizard gets you to Bronze/Silver automatically. The jump to Gold is driven by your AI agent, which queries your actual database via MCP to build the deep semantic context that automation alone cannot provide.

context setup          -->  Bronze (scaffolded from introspection)
context enrich         -->  Silver (sample values, tags, lineage, glossary)
Agent-driven curation  -->  Gold   (agent queries real data via MCP)

Most teams reach Silver within minutes of running context setup. Gold is achieved through agent-driven curation — your AI agent in Claude Code, Cursor, or Copilot connects to the database, inspects real data, and curates the metadata with your guidance. Prioritize Gold for the most business-critical datasets first.

Use context tier regularly to track progress and identify which datasets need attention to reach the next level.