create-contextkit 0.3.2 → 0.3.4

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,41 @@
+# create-contextkit
+
+Project scaffolder for [ContextKit](https://github.com/erickittelson/ContextKit) — AI-ready metadata governance over OSI.
+
+## Usage
+
+```bash
+# Create a new ContextKit project
+npx create-contextkit my-project
+cd my-project
+
+# Start working
+context lint
+context tier
+context build
+```
+
+## What it creates
+
+```
+my-project/
+├── context/
+│   ├── models/          # OSI semantic models
+│   ├── governance/      # Ownership, trust, security, semantic roles
+│   ├── rules/           # Golden queries, business rules, guardrails
+│   ├── lineage/         # Upstream/downstream lineage
+│   ├── glossary/        # Business term definitions
+│   └── owners/          # Team ownership records
+├── contextkit.config.yaml
+└── package.json
+```
+
+Includes example files to get started. Run `context setup` after scaffolding to connect a database and auto-generate metadata.
+
+## Part of ContextKit
+
+See the [ContextKit repository](https://github.com/erickittelson/ContextKit) for full documentation.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-contextkit",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Scaffold a new ContextKit project",
   "license": "MIT",
   "author": "Eric Kittelson",
@@ -10,17 +10,27 @@
     "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" },
-  "files": ["dist", "templates"],
-  "scripts": {
-    "build": "tsup",
-    "clean": "rm -rf dist"
+  "bin": {
+    "create-contextkit": "./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/context/AGENT_INSTRUCTIONS.md

@@ -122,7 +122,93 @@ When you discover data quality issues (null values, broken joins, missing data),
 
 **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
+**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