Context as Code

The idea

dbt moved analytics transformations into git. ktx applies the same pattern to analytics context: metric definitions, joins, business rules, wiki pages, and ingest decisions become files that can be reviewed, merged, and audited.

Before	With ktx
Context scattered across BI tools, chats, docs, and analyst memory	Context lives in YAML and Markdown
Agent changes are hard to inspect	Agent changes are git diffs
Imports overwrite local judgment	Ingest reconciles with existing files
History depends on tool logs	History lives in commits and transcripts

Auto-ingestion

Most context already exists in dbt manifests, LookML, MetricFlow, Metabase, Notion, warehouse metadata, and analyst notes. ktx reads those inputs through connectors, then reconciles them into local files.

output

context sources -> connectors -> reconciliation agent -> YAML + Markdown diffs

Step	What happens	Output
Extract	Connectors read models, metrics, questions, schemas, and docs	Structured metadata
Reconcile	The agent compares incoming facts with existing context	Create, update, skip, or flag
Write	ktx saves changed semantic sources and wiki pages	Reviewable project files

Reconciliation is the key difference from a sync. ktx preserves accepted local edits, fills gaps, and surfaces conflicts instead of blindly overwriting files.

The git workflow

Run ingestion on a branch, review the changed YAML and Markdown, then merge the accepted context the same way you merge dbt or application code.

output

dbt / BI / docs / warehouse
          |
          v
   ktx ingest --all
          |
          v
 branch: ingest/nightly
          |
          v
   semantic diff in PR
          |
          v
 approve and merge
          |
          v
 agents read updated files

Typical review checklist:

new sources match the warehouse and source-tool evidence;
joins have the right relationship direction;
generated measures match business definitions;
wiki pages capture caveats without duplicating YAML;
.ktx/ runtime state stays out of git unless your team intentionally reviews a report or transcript.

Teams often run ingestion on demand during setup, then schedule ktx ingest --all --no-input on an ingest branch once the source is stable.

Feedback loops

Context improves when human corrections and agent signals flow back into the same reviewed files.

Signal	Example	Where it lands
Analyst correction	A measure excludes test accounts	`semantic-layer/*/.yaml`
Business clarification	ARR changed definition this quarter	`wiki/*/.md`
Agent query issue	A filter returns no rows unexpectedly	Wiki caveat or tighter source filter
Join problem	A path duplicates order-level measures	Relationship metadata or grain fix

Accepted corrections become input to the next ingest run. That makes the context layer converge toward the team's current source of truth.

Deterministic replay

Every ingestion session records the connector inputs, tool calls, LLM responses, write decisions, and reasoning behind each change.

Use case	What replay gives you
Debugging	Trace a bad source, join, or measure back to the input that produced it
Trust	Show where a definition came from and who reviewed the resulting diff
Reproducibility	Compare old and new ingest behavior after config or model changes

Commit the YAML and Markdown changes. Commit reports or transcripts only when they are part of your team's review workflow.

Agent usage notes

Use this page when an agent needs to explain review workflows, ingestion diffs, replayability, or why ktx writes YAML and Markdown instead of hiding context in a hosted service.

Agent task	Relevant section	Next page
Explain how generated context should be reviewed	The git workflow	Building Context
Diagnose why ingestion changed a semantic source	Auto-ingestion / Deterministic replay	ktx ingest
Explain how context improves over time	Feedback loops	Building Context
Tell a user what to commit	The git workflow	Writing Context