create-dql-app 1.4.0 → 1.4.3

package/README.md

@@ -3,30 +3,34 @@
 The fastest way to start a DQL project.
 
 ```bash
-npx create-dql-app my-analytics
+npx create-dql-app@latest my-analytics
 cd my-analytics
-npx @duckcodeailabs/dql-cli notebook
+npm install
+npm run notebook
 ```
 
-Opens a running notebook at <http://localhost:5173> in under 5 minutes on a
-clean machine. No global install required.
+Opens a running notebook at <http://127.0.0.1:3474> in under 5 minutes on a
+clean machine. No global install required; the template installs
+`@duckcodeailabs/dql-cli` locally and exposes it through npm scripts.
 
 ## Templates
 
 | Template | What you get |
 | --- | --- |
 | `jaffle-shop` *(default)* | DuckDB + the Jaffle Shop dataset + a sample notebook, certified block, and dashboard |
-| `empty` | Just a `cdql.yaml` and project layout — bring your own warehouse |
+| `acme-bank` | Banking OSS release walkthrough with sample data, certified blocks, sample notebooks, Apps, dashboards, governance, schedules, and agent Skills |
+| `empty` | Just `dql.config.json` and project layout - bring your own warehouse |
 
 ```bash
-npx create-dql-app finance-reports --template empty
+npx create-dql-app@latest acme-bank --template acme-bank
+npx create-dql-app@latest finance-reports --template empty
 ```
 
 ## Flags
 
 | Flag | Default | Meaning |
 | --- | --- | --- |
-| `--template <name>` | `jaffle-shop` | Starter template |
+| `--template <name>` | `jaffle-shop` | Starter template: `jaffle-shop`, `acme-bank`, or `empty` |
 | `--no-install` | off | Skip downloading the Jaffle Shop seed data |
 
 ## Docs

package/bin/create-dql-app.mjs

@@ -34,16 +34,17 @@ function usage() {
   console.log(`create-dql-app ${VERSION}
 
 Usage:
-  npx create-dql-app <project-dir> [options]
+  npx create-dql-app@latest <project-dir> [options]
 
 Options:
-  --template <name>   Starter template: jaffle-shop (default), empty
+  --template <name>   Starter template: jaffle-shop (default), acme-bank, empty
   --help, -h          Show this help
   --version, -v       Show version
 
 Examples:
-  npx create-dql-app my-analytics
-  npx create-dql-app finance-reports --template empty
+  npx create-dql-app@latest my-analytics
+  npx create-dql-app@latest acme-bank --template acme-bank
+  npx create-dql-app@latest finance-reports --template empty
 `);
 }
 
@@ -169,7 +170,7 @@ ${c.green('✓ Ready.')} Next steps:
   ${c.bold(installCmd)}
   ${c.bold(runCmd)}${dbtTip}
 
-Your notebook will open at ${c.cyan('http://localhost:5173')}.
+Your notebook will open at ${c.cyan('http://127.0.0.1:3474')}.
 
 Docs:   ${c.cyan('https://github.com/duckcode-ai/dql')}
 Issues: ${c.cyan('https://github.com/duckcode-ai/dql/issues')}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dql-app",
-  "version": "1.4.0",
+  "version": "1.4.3",
   "description": "Scaffold a new DQL project. Run with: npx create-dql-app <name>",
   "license": "MIT",
   "author": "DuckCode AI Labs",

package/templates/acme-bank/.dql/skills/mei.chen@acme-bank.com/cards-fraud.skill.md

@@ -0,0 +1,15 @@
+---
+id: cards-fraud-daily-ops
+user: mei.chen@acme-bank.com
+description: "Cards fraud analyst skill for Acme Bank daily operations"
+preferred_metrics: [card_volume, fraud_exposure]
+vocabulary:
+  "fraud exposure": "block:fraud_alerts_by_region"
+  "approval rate": "block:card_approval_rate"
+  "merchant fraud": "block:fraud_by_merchant_recent"
+---
+Mei supports the Cards Operations App. Default to certified cards-domain blocks
+first. Always cite the block id and certification status. When a question asks
+about branch-level fraud, respect persona RLS fields `user.region` and
+`user.branch`.
+

package/templates/acme-bank/.dql/skills/sara.fitch@acme-bank.com/cfo-weekly.skill.md

@@ -0,0 +1,15 @@
+---
+id: cfo-weekly-bank-review
+user: sara.fitch@acme-bank.com
+description: "CFO weekly bank health review"
+preferred_metrics: [card_volume, fraud_exposure, deposit_balance, loan_outstanding]
+vocabulary:
+  "bank health": "block:bank_health_scorecard"
+  "deposit growth": "block:deposit_trend"
+  "credit risk": "block:loan_delinquency_by_region"
+---
+Sara prepares a Monday executive review across cards, fraud, deposits, and
+lending. Prefer the Executive Cockpit App and certified domain blocks. If the
+agent proposes SQL that is not backed by a certified block, flag it as
+uncertified and route it to analyst review.
+

package/templates/acme-bank/README.md

@@ -0,0 +1,75 @@
+# {{PROJECT_NAME}}
+
+Acme Bank is a runnable end-to-end DQL OSS sample for a single local owner. It
+models how a bank packages certified analytics into domain-specific Apps while
+keeping all source artifacts in git.
+
+## Run
+
+```bash
+npm install
+npm run compile
+npm run app:build
+npm run notebook
+```
+
+The notebook opens the local desktop UI. Click **Apps** to see the packaged
+stakeholder surfaces.
+
+## What is included
+
+```
+data/                    small DuckDB-readable CSV warehouse
+blocks/                  certified reusable DQL blocks by domain
+apps/                    stakeholder Apps with dql.app.json + .dqld dashboards
+notebooks/               analyst notebook walkthrough
+semantic-layer/          starter metric and dimension metadata
+.dql/skills/             agent skills for banking personas
+```
+
+## Domains
+
+| Domain | Business question | Certified blocks |
+| --- | --- | --- |
+| `cards` | Are card operations healthy and where is fraud concentrated? | `daily_transaction_volume`, `card_approval_rate`, `fraud_alerts_by_region`, `fraud_by_merchant_recent` |
+| `deposits` | Are deposits growing by segment and branch? | `deposit_trend`, `deposits_by_segment`, `branch_deposit_leaders` |
+| `lending` | Where is credit risk concentrated? | `loan_delinquency_by_region`, `high_risk_loan_exposure` |
+| `executive` | What should CXO leaders review this week? | `bank_health_scorecard` plus cited domain blocks |
+
+## Apps
+
+| App | Audience | Homepage dashboard |
+| --- | --- | --- |
+| `cards-ops` | Head of Cards, fraud analyst, branch manager | `daily-ops` |
+| `retail-deposits` | Retail banking leaders | `deposit-growth` |
+| `risk-office` | Credit and fraud risk committee | `credit-risk` |
+| `executive-cockpit` | CFO/COO weekly review | `bank-overview` |
+
+Certified business logic stays in root `blocks/`. App folders contain
+governance, schedules, dashboards, optional notebooks, and `drafts/` for future
+AI-generated work waiting for analyst review.
+
+## Sample notebooks
+
+| Notebook | Use case |
+| --- | --- |
+| `notebooks/welcome.dqlnb` | Guided first run across raw SQL and certified blocks |
+| `notebooks/cards_fraud_ops.dqlnb` | Cards volume, approval rate, fraud exposure, merchant watchlist |
+| `notebooks/retail_deposits_review.dqlnb` | Deposit trend, segment balance, branch leaders |
+| `notebooks/credit_risk_review.dqlnb` | Delinquency, probability of default, high-risk exposure |
+| `notebooks/executive_weekly_review.dqlnb` | CXO weekly review across cards, deposits, and lending |
+
+## Useful commands
+
+```bash
+npm run compile          # writes dql-manifest.json
+npm run app:build        # validates Apps and dashboard references
+npm run agent:reindex    # builds the local SQLite/FTS agent knowledge graph
+npm run verify           # proves manifest output is reproducible
+```
+
+## Persona preview
+
+Apps are single-user OSS artifacts. There is no login, SSO, or hosted
+multi-tenant behavior. Use the UI persona switcher to preview the real
+PolicyEngine and RLS paths declared in `dql.app.json`.

package/templates/acme-bank/apps/cards-ops/README.md

@@ -0,0 +1,9 @@
+# Cards Operations
+
+Audience: Head of Cards, cards analyst, and branch operations leaders.
+
+Homepage dashboard: `dashboards/daily-ops.dqld`
+
+Certified blocks stay in root `blocks/cards/`. This App declares members,
+policies, RLS bindings, a weekday daily digest, and a high-frequency fraud
+watch schedule in `dql.app.json`.

package/templates/acme-bank/apps/cards-ops/dashboards/daily-ops.dqld

@@ -0,0 +1,61 @@
+{
+  "version": 1,
+  "id": "daily-ops",
+  "metadata": {
+    "title": "Cards Daily Ops",
+    "description": "Certified cards operating dashboard for volume, approvals, and fraud exposure.",
+    "domain": "cards",
+    "tags": ["cards", "fraud", "ops"]
+  },
+  "filters": [
+    { "id": "region", "type": "select", "options": ["NA-NE", "NA-W", "NA-SE", "EMEA"], "bindsTo": "region" }
+  ],
+  "layout": {
+    "kind": "grid",
+    "cols": 12,
+    "rowHeight": 80,
+    "items": [
+      {
+        "i": "approval-rate",
+        "x": 0,
+        "y": 0,
+        "w": 3,
+        "h": 2,
+        "block": { "blockId": "card_approval_rate" },
+        "viz": { "type": "single_value" },
+        "title": "Approval Rate"
+      },
+      {
+        "i": "transaction-volume",
+        "x": 3,
+        "y": 0,
+        "w": 9,
+        "h": 3,
+        "block": { "blockId": "daily_transaction_volume" },
+        "viz": { "type": "line" },
+        "title": "Daily Transaction Volume"
+      },
+      {
+        "i": "fraud-region",
+        "x": 0,
+        "y": 3,
+        "w": 6,
+        "h": 3,
+        "block": { "blockId": "fraud_alerts_by_region" },
+        "viz": { "type": "bar" },
+        "title": "Fraud Exposure by Region"
+      },
+      {
+        "i": "fraud-merchant",
+        "x": 6,
+        "y": 3,
+        "w": 6,
+        "h": 3,
+        "block": { "blockId": "fraud_by_merchant_recent" },
+        "viz": { "type": "bar" },
+        "title": "Fraud by Merchant"
+      }
+    ]
+  }
+}
+

package/templates/acme-bank/apps/cards-ops/dashboards/fraud-watch.dqld

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "id": "fraud-watch",
+  "metadata": {
+    "title": "Fraud Watch",
+    "description": "High-frequency card fraud monitoring dashboard for Slack and analyst review.",
+    "domain": "cards",
+    "tags": ["cards", "fraud", "watchlist"]
+  },
+  "layout": {
+    "kind": "grid",
+    "cols": 12,
+    "rowHeight": 80,
+    "items": [
+      {
+        "i": "fraud-by-region",
+        "x": 0,
+        "y": 0,
+        "w": 12,
+        "h": 3,
+        "block": { "blockId": "fraud_alerts_by_region" },
+        "viz": { "type": "bar" },
+        "title": "Fraud Exposure by Region"
+      },
+      {
+        "i": "fraud-by-merchant",
+        "x": 0,
+        "y": 3,
+        "w": 12,
+        "h": 4,
+        "block": { "blockId": "fraud_by_merchant_recent" },
+        "viz": { "type": "table" },
+        "title": "Fraud Exposure by Merchant"
+      }
+    ]
+  }
+}

package/templates/acme-bank/apps/cards-ops/dql.app.json

@@ -0,0 +1,76 @@
+{
+  "version": 1,
+  "id": "cards-ops",
+  "name": "Cards Operations",
+  "description": "Daily cards volume, approval health, and fraud monitoring for operations leaders.",
+  "domain": "cards",
+  "owners": ["raj.kumar@acme-bank.com"],
+  "tags": ["cards", "fraud", "daily", "ops", "audience:operations"],
+  "members": [
+    {
+      "userId": "raj.kumar@acme-bank.com",
+      "displayName": "Raj Kumar - Head of Cards",
+      "roles": ["owner"],
+      "attributes": { "department": "cards" }
+    },
+    {
+      "userId": "mei.chen@acme-bank.com",
+      "displayName": "Mei Chen - Cards Analyst",
+      "roles": ["analyst"],
+      "attributes": { "department": "cards" }
+    },
+    {
+      "userId": "li.park@acme-bank.com",
+      "displayName": "Li Park - NYC Branch Manager",
+      "roles": ["branch_viewer"],
+      "attributes": { "region": "NA-NE", "branch": "NYC-042", "department": "cards" }
+    }
+  ],
+  "roles": [
+    { "id": "owner", "displayName": "Owner", "description": "Full App configuration and execution." },
+    { "id": "analyst", "displayName": "Analyst", "description": "Can execute dashboards and review proposed blocks." },
+    { "id": "viewer", "displayName": "Viewer", "description": "Can view and run certified dashboard tiles." },
+    { "id": "branch_viewer", "displayName": "Branch Viewer", "description": "Dashboard execution narrowed to the member's region and branch." }
+  ],
+  "policies": [
+    {
+      "id": "cards-dashboard-view",
+      "domain": "cards",
+      "minClassification": "internal",
+      "allowedRoles": ["viewer", "branch_viewer", "analyst", "owner"],
+      "accessLevel": "execute",
+      "enabled": true
+    },
+    {
+      "id": "cards-config-owner",
+      "domain": "cards",
+      "minClassification": "restricted",
+      "allowedRoles": ["owner"],
+      "accessLevel": "admin",
+      "enabled": true
+    }
+  ],
+  "rlsBindings": [
+    { "role": "branch_viewer", "variable": "user.region", "from": "region" },
+    { "role": "branch_viewer", "variable": "user.branch", "from": "branch" }
+  ],
+  "schedules": [
+    {
+      "id": "daily-7am-digest",
+      "cron": "0 7 * * 1-5",
+      "dashboard": "daily-ops",
+      "deliver": [{ "kind": "slack", "channel": "#cards-ops" }],
+      "description": "Weekday cards operations digest.",
+      "enabled": true
+    },
+    {
+      "id": "fraud-spike-watch",
+      "cron": "*/15 * * * *",
+      "dashboard": "fraud-watch",
+      "deliver": [{ "kind": "slack", "channel": "#cards-fraud-alerts" }],
+      "description": "High-frequency fraud monitoring digest.",
+      "enabled": true
+    }
+  ],
+  "homepage": { "type": "dashboard", "id": "daily-ops" }
+}

package/templates/acme-bank/apps/cards-ops/drafts/.gitkeep

@@ -0,0 +1 @@
+

package/templates/acme-bank/apps/cards-ops/notebooks/.gitkeep

@@ -0,0 +1 @@
+

package/templates/acme-bank/apps/executive-cockpit/README.md

@@ -0,0 +1,9 @@
+# Executive Cockpit
+
+Audience: CFO, COO, and weekly CXO business review.
+
+Homepage dashboard: `dashboards/bank-overview.dqld`
+
+The App summarizes multiple domains by citing certified blocks instead of
+copying business logic into the App folder.
+

package/templates/acme-bank/apps/executive-cockpit/dashboards/bank-overview.dqld

@@ -0,0 +1,57 @@
+{
+  "version": 1,
+  "id": "bank-overview",
+  "metadata": {
+    "title": "Bank Overview",
+    "description": "CXO scorecard that cites certified domain blocks.",
+    "domain": "executive",
+    "tags": ["executive", "scorecard", "cxo"]
+  },
+  "layout": {
+    "kind": "grid",
+    "cols": 12,
+    "rowHeight": 80,
+    "items": [
+      {
+        "i": "health-scorecard",
+        "x": 0,
+        "y": 0,
+        "w": 6,
+        "h": 4,
+        "block": { "blockId": "bank_health_scorecard" },
+        "viz": { "type": "table" },
+        "title": "Bank Health Scorecard"
+      },
+      {
+        "i": "deposit-trend",
+        "x": 6,
+        "y": 0,
+        "w": 6,
+        "h": 3,
+        "block": { "blockId": "deposit_trend" },
+        "viz": { "type": "line" },
+        "title": "Deposit Trend"
+      },
+      {
+        "i": "card-volume",
+        "x": 0,
+        "y": 4,
+        "w": 6,
+        "h": 3,
+        "block": { "blockId": "daily_transaction_volume" },
+        "viz": { "type": "line" },
+        "title": "Card Volume"
+      },
+      {
+        "i": "credit-risk",
+        "x": 6,
+        "y": 4,
+        "w": 6,
+        "h": 3,
+        "block": { "blockId": "loan_delinquency_by_region" },
+        "viz": { "type": "bar" },
+        "title": "Credit Risk"
+      }
+    ]
+  }
+}

package/templates/acme-bank/apps/executive-cockpit/dql.app.json

@@ -0,0 +1,82 @@
+{
+  "version": 1,
+  "id": "executive-cockpit",
+  "name": "Executive Cockpit",
+  "description": "CXO scorecard that summarizes cards, fraud, deposits, and lending risk.",
+  "domain": "executive",
+  "owners": ["sara.fitch@acme-bank.com"],
+  "tags": ["executive", "cxo", "scorecard", "audience:cxo"],
+  "members": [
+    {
+      "userId": "sara.fitch@acme-bank.com",
+      "displayName": "Sara Fitch - CFO",
+      "roles": ["owner"],
+      "attributes": { "department": "finance" }
+    },
+    {
+      "userId": "nora.evans@acme-bank.com",
+      "displayName": "Nora Evans - COO",
+      "roles": ["viewer"],
+      "attributes": { "department": "operations" }
+    }
+  ],
+  "roles": [
+    { "id": "owner", "displayName": "Owner", "description": "Full App configuration and execution." },
+    { "id": "analyst", "displayName": "Analyst", "description": "Can execute dashboards and review proposed blocks." },
+    { "id": "viewer", "displayName": "Viewer", "description": "Can view and run certified dashboard tiles." }
+  ],
+  "policies": [
+    {
+      "id": "executive-dashboard-execute",
+      "domain": "executive",
+      "minClassification": "internal",
+      "allowedRoles": ["viewer", "analyst", "owner"],
+      "accessLevel": "execute",
+      "enabled": true
+    },
+    {
+      "id": "executive-cards-readthrough",
+      "domain": "cards",
+      "minClassification": "internal",
+      "allowedRoles": ["viewer", "analyst", "owner"],
+      "accessLevel": "execute",
+      "enabled": true
+    },
+    {
+      "id": "executive-deposits-readthrough",
+      "domain": "deposits",
+      "minClassification": "internal",
+      "allowedRoles": ["viewer", "analyst", "owner"],
+      "accessLevel": "execute",
+      "enabled": true
+    },
+    {
+      "id": "executive-lending-readthrough",
+      "domain": "lending",
+      "minClassification": "internal",
+      "allowedRoles": ["viewer", "analyst", "owner"],
+      "accessLevel": "execute",
+      "enabled": true
+    },
+    {
+      "id": "executive-owner-admin",
+      "domain": "executive",
+      "minClassification": "restricted",
+      "allowedRoles": ["owner"],
+      "accessLevel": "admin",
+      "enabled": true
+    }
+  ],
+  "rlsBindings": [],
+  "schedules": [
+    {
+      "id": "monday-cxo-scorecard",
+      "cron": "0 7 * * 1",
+      "dashboard": "bank-overview",
+      "deliver": [{ "kind": "slack", "channel": "#cxo-weekly" }],
+      "description": "Monday morning CXO scorecard.",
+      "enabled": true
+    }
+  ],
+  "homepage": { "type": "dashboard", "id": "bank-overview" }
+}

package/templates/acme-bank/apps/executive-cockpit/drafts/.gitkeep

@@ -0,0 +1 @@
+

package/templates/acme-bank/apps/executive-cockpit/notebooks/.gitkeep

@@ -0,0 +1 @@
+

package/templates/acme-bank/apps/retail-deposits/README.md

@@ -0,0 +1,9 @@
+# Retail Deposits
+
+Audience: retail banking leaders tracking deposit growth and branch leaders.
+
+Homepage dashboard: `dashboards/deposit-growth.dqld`
+
+Certified blocks stay in root `blocks/deposits/`. This App packages the
+deposit growth dashboard with programmable OSS governance.
+

package/templates/acme-bank/apps/retail-deposits/dashboards/deposit-growth.dqld

@@ -0,0 +1,48 @@
+{
+  "version": 1,
+  "id": "deposit-growth",
+  "metadata": {
+    "title": "Deposit Growth",
+    "description": "Certified deposit growth dashboard by segment, branch, and snapshot date.",
+    "domain": "deposits",
+    "tags": ["deposits", "growth", "retail"]
+  },
+  "layout": {
+    "kind": "grid",
+    "cols": 12,
+    "rowHeight": 80,
+    "items": [
+      {
+        "i": "deposit-trend",
+        "x": 0,
+        "y": 0,
+        "w": 12,
+        "h": 3,
+        "block": { "blockId": "deposit_trend" },
+        "viz": { "type": "line" },
+        "title": "Total Deposit Trend"
+      },
+      {
+        "i": "segment-balance",
+        "x": 0,
+        "y": 3,
+        "w": 6,
+        "h": 3,
+        "block": { "blockId": "deposits_by_segment" },
+        "viz": { "type": "bar" },
+        "title": "Deposits by Segment"
+      },
+      {
+        "i": "branch-leaders",
+        "x": 6,
+        "y": 3,
+        "w": 6,
+        "h": 4,
+        "block": { "blockId": "branch_deposit_leaders" },
+        "viz": { "type": "table" },
+        "title": "Branch Leaders"
+      }
+    ]
+  }
+}
+

package/templates/acme-bank/apps/retail-deposits/dql.app.json

@@ -0,0 +1,59 @@
+{
+  "version": 1,
+  "id": "retail-deposits",
+  "name": "Retail Deposits",
+  "description": "Deposit growth and branch leaderboard App for retail banking leaders.",
+  "domain": "deposits",
+  "owners": ["diego.ramos@acme-bank.com"],
+  "tags": ["deposits", "retail", "growth", "audience:retail-leaders"],
+  "members": [
+    {
+      "userId": "diego.ramos@acme-bank.com",
+      "displayName": "Diego Ramos - Retail Analytics",
+      "roles": ["owner", "analyst"],
+      "attributes": { "department": "retail" }
+    },
+    {
+      "userId": "nora.evans@acme-bank.com",
+      "displayName": "Nora Evans - Retail COO",
+      "roles": ["viewer"],
+      "attributes": { "department": "retail" }
+    }
+  ],
+  "roles": [
+    { "id": "owner", "displayName": "Owner", "description": "Full App configuration and execution." },
+    { "id": "analyst", "displayName": "Analyst", "description": "Can execute dashboards and review proposed blocks." },
+    { "id": "viewer", "displayName": "Viewer", "description": "Can view and run certified dashboard tiles." }
+  ],
+  "policies": [
+    {
+      "id": "deposits-dashboard-view",
+      "domain": "deposits",
+      "minClassification": "internal",
+      "allowedRoles": ["viewer", "analyst", "owner"],
+      "accessLevel": "execute",
+      "enabled": true
+    },
+    {
+      "id": "deposits-owner-admin",
+      "domain": "deposits",
+      "minClassification": "restricted",
+      "allowedRoles": ["owner"],
+      "accessLevel": "admin",
+      "enabled": true
+    }
+  ],
+  "rlsBindings": [],
+  "schedules": [
+    {
+      "id": "weekly-deposit-growth",
+      "cron": "0 9 * * 1",
+      "dashboard": "deposit-growth",
+      "deliver": [{ "kind": "slack", "channel": "#retail-deposits" }],
+      "description": "Weekly deposits growth digest.",
+      "enabled": true
+    }
+  ],
+  "homepage": { "type": "dashboard", "id": "deposit-growth" }
+}
+

package/templates/acme-bank/apps/retail-deposits/drafts/.gitkeep

@@ -0,0 +1 @@
+

package/templates/acme-bank/apps/retail-deposits/notebooks/.gitkeep

@@ -0,0 +1 @@
+