create-contextkit 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-contextkit",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Scaffold a new ContextKit project",
   "license": "MIT",
   "author": "Eric Kittelson",
@@ -10,27 +10,17 @@
     "url": "https://github.com/erickittelson/ContextKit.git",
     "directory": "create-contextkit"
   },
-  "keywords": [
-    "contextkit",
-    "scaffolder",
-    "create",
-    "init"
-  ],
+  "keywords": ["contextkit", "scaffolder", "create", "init"],
   "type": "module",
-  "bin": {
-    "create-contextkit": "./dist/index.js"
+  "bin": { "create-contextkit": "./dist/index.js" },
+  "files": ["dist", "templates"],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist"
   },
-  "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/context/AGENT_INSTRUCTIONS.md

@@ -0,0 +1,184 @@
+# ContextKit Agent Instructions
+
+You have two MCP servers: **duckdb** (query data) and **contextkit** (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 (+21):** 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
+
+## 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/LICENSE

@@ -1,21 +0,0 @@
-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.