create-runcontext 0.5.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Kittelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# create-runcontext
+
+Scaffold a new [RunContext](https://github.com/RunContext/runcontext) project — one command to start building an AI-ready data product from your database.
+
+## Usage
+
+```bash
+npx create-runcontext my-project
+cd my-project
+context setup
+```
+
+The setup wizard opens in your browser. Fill out a Context Brief (name, owner, sensitivity, database connection), and the pipeline builds your semantic plane automatically.
+
+## What it creates
+
+```
+my-project/
+├── context/
+│   ├── models/          # Semantic models (OSI YAML)
+│   ├── governance/      # Ownership, trust, security, semantic roles
+│   ├── rules/           # Golden queries, business rules, guardrails
+│   ├── lineage/         # Upstream/downstream lineage
+│   ├── glossary/        # Business term definitions
+│   └── owners/          # Team ownership records
+├── runcontext.config.yaml
+└── package.json
+```
+
+## What happens next
+
+1. **`context setup`** — Browser wizard guides you through the Context Brief
+2. **Pipeline runs** — Introspect database → scaffold Bronze → enrich to Silver
+3. **`context dev --studio`** — Visual editor to curate metadata to Gold tier
+4. **`context serve`** — MCP server live, AI agents get full context
+
+## Part of RunContext
+
+See the [RunContext repository](https://github.com/RunContext/runcontext) for full documentation.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var templatesDir = path.resolve(__dirname, "..", "templates", "minimal");
+function toKebabCase(input) {
+  return input.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+}
+function toTitleCase(input) {
+  return input.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function copyDir(src, dest, createdFiles, projectDir, projectName, displayName) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDir(srcPath, destPath, createdFiles, projectDir, projectName, displayName);
+    } else if (entry.name.endsWith(".template")) {
+      let content = fs.readFileSync(srcPath, "utf-8");
+      content = content.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+      content = content.replace(/\{\{PROJECT_DISPLAY_NAME\}\}/g, displayName);
+      const finalPath = destPath.replace(/\.template$/, "");
+      fs.writeFileSync(finalPath, content, "utf-8");
+      createdFiles.push(path.relative(projectDir, finalPath));
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      createdFiles.push(path.relative(projectDir, destPath));
+    }
+  }
+}
+function main() {
+  const projectNameArg = process.argv[2];
+  if (!projectNameArg) {
+    console.log("Usage: create-runcontext <project-name>");
+    console.log("");
+    console.log("Example:");
+    console.log("  npm create runcontext my-project");
+    console.log("  pnpm create runcontext my-project");
+    process.exit(1);
+  }
+  const projectName = toKebabCase(projectNameArg);
+  const displayName = toTitleCase(projectName);
+  const projectDir = path.resolve(process.cwd(), projectName);
+  if (fs.existsSync(projectDir)) {
+    console.error(`Error: Directory "${projectName}" already exists. Please choose a different name or remove the existing directory.`);
+    process.exit(1);
+  }
+  console.log(`Creating RunContext project: ${projectName}`);
+  console.log("");
+  fs.mkdirSync(projectDir, { recursive: true });
+  const createdFiles = [];
+  copyDir(templatesDir, projectDir, createdFiles, projectDir, projectName, displayName);
+  for (const file of createdFiles) {
+    console.log(`  Created ${file}`);
+  }
+  console.log("");
+  console.log("Done! Next steps:");
+  console.log(`  cd ${projectName}`);
+  console.log("  pnpm add -D @runcontext/cli");
+  console.log("  npx context lint");
+  console.log("  npx context tier");
+}
+main();

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "create-runcontext",
+  "version": "0.5.3",
+  "description": "Scaffold a new RunContext data product. Run npx create-runcontext, fill out a Context Brief in your browser, and the pipeline builds your semantic plane automatically.",
+  "license": "MIT",
+  "author": "Eric Kittelson",
+  "homepage": "https://github.com/RunContext/runcontext",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RunContext/runcontext.git",
+    "directory": "create-runcontext"
+  },
+  "bugs": "https://github.com/RunContext/runcontext/issues",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "create",
+    "scaffold",
+    "semantic-plane",
+    "semantic-layer",
+    "runcontext",
+    "data-product",
+    "ai-ready-data",
+    "npx",
+    "project-generator",
+    "mcp",
+    "data-catalog"
+  ],
+  "type": "module",
+  "bin": {
+    "create-runcontext": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist"
+  }
+}

package/templates/minimal/AGENT_INSTRUCTIONS.md

@@ -0,0 +1,270 @@
+# RunContext Agent Instructions
+
+You have two MCP servers: **duckdb** (query data) and **runcontext** (query metadata).
+
+## The Cardinal Rule: Never Fabricate Metadata
+
+**Every piece of metadata you write must be grounded in evidence from the actual data.**
+
+- NEVER invent owner names, emails, team names, or contact info
+- NEVER write a field description that is just the column name repeated
+- NEVER assign a semantic_role without first querying the column's actual values
+- NEVER mark a field as additive without understanding what summing it means
+- NEVER write lineage entries without knowing the actual data sources
+- NEVER write a business_context narrative you can't justify from the data
+- NEVER create a glossary definition that is just "Definition for X"
+
+If you don't know something, say so. Leave it as a TODO with a note about what you'd need to determine the answer. A honest TODO is infinitely better than fabricated metadata that looks plausible but is wrong.
+
+## On Session Start
+
+1. Run `context_tier` to check the current metadata tier (Bronze/Silver/Gold)
+2. Report the current tier and list failing checks
+3. Ask the user what they'd like to work on — don't start changing files unprompted
+
+## When Asked to Reach Gold
+
+Work through ALL failing Gold checks iteratively until `context tier` reports Gold:
+
+1. Run `context_tier` and collect every failing check
+2. For each failing check, query the database to gather evidence, then fix the metadata
+3. Run `context_tier` again
+4. If checks still fail, go back to step 2
+5. **Do NOT stop until every Gold check passes** or you hit something that genuinely requires human input (like real owner contact info)
+6. For checks you cannot fix (e.g., owner email), leave a clear TODO explaining what a human needs to provide
+
+You must iterate — a single pass is never enough. Each `context tier` run may reveal new failures after earlier ones are fixed.
+
+## How to Curate Metadata (the right way)
+
+### Before writing ANY metadata, query the database first
+
+For every field you're about to describe or classify:
+
+```sql
+-- What type of values does this column contain?
+SELECT DISTINCT column_name FROM table LIMIT 20;
+
+-- For numeric columns: is this a metric or dimension?
+SELECT MIN(col), MAX(col), AVG(col), COUNT(DISTINCT col) FROM table;
+
+-- For potential metrics: does SUM make sense?
+-- If SUM produces a meaningful business number → additive: true
+-- If SUM is meaningless (e.g., summing percentages, scores, ratings) → additive: false
+```
+
+### Semantic Role Decision Tree
+
+Query the column first, then apply this logic:
+
+1. **Is it a primary key or foreign key?** → `identifier`
+2. **Is it a date or timestamp?** → `date`
+3. **Is it numeric AND does aggregation make business sense?**
+   - Does SUM make sense? (counts, amounts, quantities) → `metric`, `additive: true`
+   - Does only AVG/MIN/MAX make sense? (rates, percentages, scores, ratings) → `metric`, `additive: false`
+4. **Everything else** → `dimension`
+
+Common mistakes to avoid:
+- `stars` (ratings) → metric with AVG, NOT additive (summing star ratings is meaningless)
+- `_per_10k_people` (rates) → metric with AVG, NOT additive
+- `_score` (composite scores) → metric with AVG, NOT additive
+- `useful/funny/cool` (vote counts) → metric with SUM, additive
+- `_count` fields → metric with SUM, additive (usually)
+
+### Field Descriptions
+
+Write descriptions that help someone who has never seen this database understand what the column contains. Include:
+- What the value represents
+- Units or scale (if applicable)
+- Where the data comes from (if known)
+- Any known quirks or caveats
+
+Bad: `description: total_population`
+Good: `description: Total resident population of the census tract from American Community Survey 5-year estimates`
+
+### Lineage
+
+Upstream sources are the EXTERNAL systems that feed data into this warehouse. They are NOT the tables in the warehouse itself.
+
+Ask yourself: "Where did this data originally come from before it was loaded here?"
+
+### Owner Files
+
+Do NOT create fake owner identities. If the real owner is unknown:
+- Keep the existing owner file as-is
+- Note in the file that contact info needs to be filled in by a real person
+- NEVER invent email addresses like `analytics@example.com`
+
+### Business Context
+
+Write business_context entries that describe real analytical use cases you can verify from the data. Query the data to understand what questions it can answer before writing narratives.
+
+### Golden Queries
+
+Every golden query MUST be tested against the actual database before you write it. Run the SQL, verify it returns sensible results, then document it.
+
+### Data Quality
+
+When you discover data quality issues (null values, broken joins, missing data), FLAG THEM — don't hide them. Add notes in governance or report them to the user.
+
+## MCP Tools
+
+| Tool | Parameters | What it does |
+|------|-----------|-------------|
+| `context_search` | `query` | Find models, datasets, fields, terms by keyword |
+| `context_explain` | `model` | Full model details — governance, rules, lineage, tier |
+| `context_validate` | — | Run linter, get errors and warnings |
+| `context_tier` | `model` | Tier scorecard with all check results |
+| `context_golden_query` | `question` | Find pre-validated SQL for a question |
+| `context_guardrails` | `tables[]` | Get required WHERE clauses for tables |
+
+## Tier Checks Quick Reference
+
+**Bronze (7):** descriptions, owner, security, grain, table_type
+**Silver (+6):** trust, 2+ tags, glossary linked, lineage, refresh, 2+ sample_values
+**Gold (+24):** semantic_role on ALL fields, metric aggregation/additive, 1+ guardrail, 3+ golden queries, 1+ business rule, 1+ hierarchy, 1+ default_filter, trust=endorsed, contactable owner, 1+ relationship, description >=50 chars, ai_context (no TODO), 1+ business_context, version, field descriptions not lazy, glossary definitions substantive, lineage references real sources, grain statements specific, ai_context filled in, 3+ relationships (models with 3+ datasets), 1+ computed metric, 3+ glossary terms (models with 5+ datasets)
+
+## How to Reach Gold: Curation Recipes
+
+### Metrics (gold/metrics-defined)
+
+Inspect computed views in the database. Any calculated column is a candidate metric.
+
+```sql
+-- Find computed columns in views
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_name LIKE 'vw_%' AND data_type IN ('DOUBLE', 'FLOAT', 'INTEGER', 'BIGINT', 'DECIMAL');
+```
+
+For each computed column (e.g., `opportunity_score`, `shops_per_10k`, `demand_signal_pct`):
+1. Query it to understand what it measures
+2. Add it to the model's `metrics[]` array in the OSI YAML
+3. Include the SQL expression, aggregation type (SUM/AVG), and a human description
+4. Mark whether it's additive (can be summed across dimensions)
+
+Example:
+```yaml
+metrics:
+  - name: opportunity_score
+    expression:
+      dialects:
+        - dialect: DuckDB
+          expression: "(population/10000)*2 + (income/50000)*2 + (10-shops_per_10k)*3 + transit*1.5 + demand*0.5"
+    description: Composite score ranking census tracts for coffee shop viability
+    aggregation: AVG
+    additive: false
+```
+
+### Glossary Terms (gold/glossary-coverage)
+
+For each key business concept your model measures, create a glossary term file.
+
+Think about the terms a new analyst would need defined:
+- What is "supply saturation"? (> 5.0 shops per 10k people)
+- What is a "demand signal"? (review mentioning wait/line/crowded/busy)
+- What is "opportunity score"? (composite ranking formula)
+
+For each term, create `context/glossary/<term-name>.term.yaml`:
+```yaml
+term: supply-saturation
+definition: >
+  A measure of coffee shop density per census tract. Calculated as
+  shops per 10,000 residents. Tracts with > 5.0 are considered saturated.
+owner: analytics-team
+tags: [coffee-analytics]
+```
+
+Models with 5+ datasets need at least 3 glossary terms linked by shared tags or owner.
+
+### Relationships (gold/relationships-coverage)
+
+For each join in the SQL views, define a relationship in the OSI model.
+
+```sql
+-- Find joins by examining view definitions
+-- Look for patterns: ON table_a.col = table_b.col
+-- Or spatial joins: ABS(a.lat - b.lat) < threshold
+```
+
+For each join:
+```yaml
+relationships:
+  - name: business-to-tract
+    left_dataset: yelp_business
+    right_dataset: census_tract
+    join_type: spatial
+    cardinality: many-to-one
+    description: Businesses assigned to nearest census tract within 0.02 degrees (~1 mile)
+```
+
+Models with 3+ datasets need at least 3 relationships.
+
+### Golden Queries
+
+Write 3-5 SQL queries answering common business questions. **Test each query first!**
+
+```sql
+-- Run the query, verify it returns sensible results, then document:
+SELECT geoid, tract_name, opportunity_score
+FROM vw_candidate_zones ORDER BY opportunity_score DESC LIMIT 10;
+```
+
+## YAML Formats
+
+**Governance** (`context/governance/*.governance.yaml`):
+```yaml
+model: my-model
+owner: team-name
+version: "1.0.0"
+trust: endorsed
+security: internal
+tags: [domain-tag-1, domain-tag-2]
+business_context:
+  - name: Use Case Name
+    description: What analytical question this data answers and for whom.
+datasets:
+  my_table:
+    grain: "One row per [entity] identified by [key]"
+    table_type: fact    # fact | dimension | event | view
+    refresh: daily
+fields:
+  dataset.field:
+    semantic_role: metric        # metric | dimension | identifier | date
+    default_aggregation: SUM     # SUM | AVG | COUNT | COUNT_DISTINCT | MIN | MAX
+    additive: true               # can this metric be summed across dimensions?
+    default_filter: "is_open = 1"
+    sample_values: ["val1", "val2"]
+```
+
+**Rules** (`context/rules/*.rules.yaml`):
+```yaml
+model: my-model
+golden_queries:
+  - question: What are the top items by count?
+    sql: SELECT name, count FROM my_table ORDER BY count DESC LIMIT 10
+    intent: Identify top performers by volume
+    caveats: Filters to active records only
+business_rules:
+  - name: valid-ratings
+    definition: All ratings must be between 1 and 5
+guardrail_filters:
+  - name: active-only
+    filter: "status = 'active'"
+    reason: Exclude inactive records from analytics
+    tables: [my_table]
+hierarchies:
+  - name: geography
+    levels: [state, city, postal_code]
+    dataset: my_table
+```
+
+## CLI Commands
+
+```bash
+context tier                  # Check scorecard
+context verify --db <path>    # Validate against live data
+context fix --db <path>       # Auto-fix data warnings
+context setup                 # Interactive setup wizard
+context dev                   # Watch mode for live editing
+```

package/templates/minimal/glossary/example-term.term.yaml

@@ -0,0 +1,5 @@
+id: revenue
+definition: "Total value of completed orders before refunds"
+synonyms: [sales, order revenue]
+owner: example-team
+tags: [finance]

package/templates/minimal/owners/example-team.owner.yaml

@@ -0,0 +1,4 @@
+id: example-team
+display_name: Example Team
+email: team@example.com
+description: "Responsible for data and analytics"

package/templates/minimal/products/example-product/context-brief.yaml.template

@@ -0,0 +1,8 @@
+product_name: example-product
+description: "{{PROJECT_DISPLAY_NAME}} — describe your data product here."
+owner:
+  name: Your Name
+  team: Your Team
+  email: you@example.com
+sensitivity: internal
+docs: []

package/templates/minimal/products/example-product/governance/example-model.governance.yaml

@@ -0,0 +1,23 @@
+model: example-model
+owner: example-team
+trust: endorsed
+security: internal
+tags: [orders, revenue]
+
+datasets:
+  orders:
+    grain: "One row per order"
+    refresh: daily
+    table_type: fact
+
+fields:
+  orders.amount:
+    semantic_role: metric
+    default_aggregation: SUM
+    additive: true
+  orders.order_id:
+    semantic_role: identifier
+  orders.customer_id:
+    semantic_role: identifier
+  orders.order_date:
+    semantic_role: date

package/templates/minimal/products/example-product/lineage/example-model.lineage.yaml

@@ -0,0 +1,12 @@
+model: example-model
+
+upstream:
+  - source: source-system.raw-data
+    type: pipeline
+    refresh: daily
+    notes: Raw data ingested daily via ETL pipeline
+
+downstream:
+  - target: analytics-dashboard
+    type: dashboard
+    notes: Executive KPI dashboard

package/templates/minimal/products/example-product/models/example-model.osi.yaml

@@ -0,0 +1,51 @@
+version: "1.0"
+
+semantic_model:
+  - name: example-model
+    description: Example orders analytics model
+    ai_context:
+      instructions: "Use for order and revenue analysis"
+      synonyms: ["orders model"]
+
+    datasets:
+      - name: orders
+        source: warehouse.public.orders
+        primary_key: [order_id]
+        description: "Orders fact table"
+        fields:
+          - name: order_id
+            expression:
+              dialects:
+                - dialect: ANSI_SQL
+                  expression: order_id
+            description: Unique order identifier
+          - name: customer_id
+            expression:
+              dialects:
+                - dialect: ANSI_SQL
+                  expression: customer_id
+            description: Foreign key to customers
+            dimension:
+              is_time: false
+          - name: amount
+            expression:
+              dialects:
+                - dialect: ANSI_SQL
+                  expression: amount
+            description: Order amount in USD
+          - name: order_date
+            expression:
+              dialects:
+                - dialect: ANSI_SQL
+                  expression: order_date
+            description: Date the order was placed
+            dimension:
+              is_time: true
+
+    metrics:
+      - name: total_revenue
+        expression:
+          dialects:
+            - dialect: ANSI_SQL
+              expression: "SUM(orders.amount)"
+        description: Total revenue across all orders

package/templates/minimal/products/example-product/rules/example-model.rules.yaml

@@ -0,0 +1,19 @@
+model: example-model
+
+golden_queries:
+  - question: "What is total revenue?"
+    sql: |
+      SELECT SUM(amount) AS total_revenue
+      FROM orders
+    dialect: ANSI_SQL
+    tags: [revenue]
+
+business_rules:
+  - name: positive-amounts
+    definition: "Only include orders with positive amounts in revenue calculations"
+    enforcement:
+      - "Filter to amount > 0 when calculating revenue"
+    avoid:
+      - "Do not include negative or zero amounts in revenue totals"
+    tables: [orders]
+    applied_always: true

package/templates/minimal/runcontext.config.yaml.template

@@ -0,0 +1,6 @@
+context_dir: .
+output_dir: dist
+products:
+  - example-product
+glossary_dir: glossary
+owners_dir: owners