ZLens 0.2.11

ZLens runs on Node 26 LTS.

• DuckDB now loads through @duckdb/node-api, which installs in about a
  second on Node 20, 22, 24 and 26, with nothing to compile.
• zlens sync warehouse installs the DuckDB driver the first time, so the
  quickstarts have one step fewer.
• A read-only PostgreSQL login now reads primary keys, foreign keys and view
  SQL.
• A question a certified block records is answered by that block, word for
  word, every time.

To upgrade, run npm i -D @zlens/cli@^0.2.11 in each project. On Node 26,
npm install -g @zlens/cli now installs 0.2.11 instead of 0.2.1.

Node 26 LTS: the DuckDB driver is now @duckdb/node-api

• ZLens runs on Node 20, 22, 24 and 26. Node 26 became the LTS this
  month, and until now ZLens could not use DuckDB on it: the old duckdb
  package had no binary for Node 26 and compiled DuckDB from source for over
  ten minutes, then failed. Worse, npm install -g @zlens/cli on Node 26
  quietly installed 0.2.1, the last release whose engines allowed it. ZLens
  now loads DuckDB through DuckDB's own Node API (@duckdb/node-api, RFC
  0011). Its binary is built on Node-API and comes as a per-platform optional
  dependency, so one install works on every Node from 20 up, in about a
  second, with no install script and nothing compiled. engines adds Node 26.
• It installs on its own. On the next npm run notebook or npm run sync, ZLens installs @duckdb/node-api into .dql/connectors. You can
  delete .dql/connectors/node_modules/duckdb; ZLens no longer loads it. If
  you install the driver yourself (CI, Docker), use
  npm install --prefix .dql/connectors '@duckdb/node-api@^1.5.6-r.1': npm's
  latest is DuckDB 2.0, whose files DuckDB 1.x cannot read.
• DuckDB 1.5. ZLens now reads files written by DuckDB 1.5 (and older), so
  a dbt-duckdb that installed Python DuckDB 1.5 no longer needs pinning back
  to 1.4. Files written by DuckDB 2.0 still cannot be opened.
• Same results. Every value comes back as before (numbers, dates and
  timestamps, TIME as text, lists and structs); a column that is NULL in the
  first row now gets its real type instead of none.
• A tile by month, quarter or year lists its rows in date order when you
  have not set a sort. DuckDB 1.5 returns grouped rows in a different order
  from run to run, so a table tile could show March before February.
• zlens sync warehouse installs the driver the first time, as zlens notebook does at start, so quickstarts and create-zlens-app have no
  separate driver step. A driver whose binary for this computer is missing (a
  .dql folder copied from another OS) is reinstalled on start.
• Removed: the Node 25/26 "no prebuilt binary" guard and
  ZLENS_DUCKDB_BUILD_FROM_SOURCE.

PostgreSQL: a read-only login reads keys and view SQL

• zlens sync warehouse on PostgreSQL now reads declared primary and
  foreign keys and view definitions with a SELECT-only login, the role the
  docs recommend. They came from information_schema, which shows a table's
  constraints and a view's SQL only to its owner, so a read-only login got
  none and the sync did not say so. Discovery then drafted joins from column
  names alone: it missed a foreign key whose names differ
  (orders.buyer_id → customers.customer_id) and could pass a join between
  two unrelated columns that share a name. Keys and views are now read from
  pg_catalog, which any login with USAGE on the schema can see; composite
  keys keep their column order. Redshift still reads information_schema.

Ask: a certified block answers the question it was certified for

• The question a block records is its own. A certified block's
  examples (and a description that is the question verbatim) now settle
  the route before any model reads the question: asked word for word, in any
  case, spacing or trailing punctuation, the question is answered by that
  block as Certified. Until now the certified tier matched only the model's
  reading, so the same words came back Certified one run and AI-generated
  the next (live gate W1, round 4: the model read "Which adjusters handle the
  most open claims?" as claim rows, and no block entails that). Two certified
  blocks recording the same question leave the choice to the meaning-based
  match, which still runs second for every other question.
• The question is recorded for you. "Make this a certified answer" and
  the review draft an Ask answer leaves both write the question as the
  block's first example; Block Studio edits the list under Context as
  "Questions it answers".

Fixes

• Apps: saving an App page's preview receipt no longer fails with
  "previewed against a different warehouse target" when ZLens runs on a
  connection that replaces the configured default (a copied DuckDB file, a
  host's draft space). (#212)
• Ask: the same question asked again in a thread is read as a new
  question, so it gets the certified answer a saved query now gives it,
  instead of being read as an edit of the earlier AI answer. (#213)
• Metadata: two metadata refreshes running at once on one project no
  longer leave the active snapshot pointing at the wrong catalog (the "Active
  metadata snapshot pointer mismatch" error). Refreshes now run one at a time
  per project. (#214, #216)
• Docs: the AI provider page explains how to finish a Claude or ChatGPT
  sign-in in a codespace, in Docker or on another computer. (#211)

ZLens 0.2.10

Sign in with your Claude or ChatGPT subscription when ZLens runs somewhere else: in a GitHub codespace, a Docker container or on another computer.

To upgrade, run npm i -D @zlens/cli@^0.2.10 in each project.

• Finish a sign-in by pasting an address:
  • After you sign in, Claude and ChatGPT send your browser back to localhost. In a codespace or on another host, that page can't load.
  • While a sign-in waits, Settings → AI provider → Subscription shows a box. Paste the address from the address bar there and click Finish sign-in.
• A link to the sign-in page, in case the pop-up is blocked.
• Docker: the demo image's command maps the two return ports, so sign-in finishes without pasting:
  docker run --rm -p 127.0.0.1:3474:3474 -p 127.0.0.1:54545:54545 -p 127.0.0.1:1455:1455 ghcr.io/duckcode-ai/zlens-demo
• Home card headings are readable in every theme.
• Hosts that review certification through pull requests can make the App Studio say "propose" instead of "certify".
• Try it without installing: an Open in GitHub Codespaces button and a Docker demo image. The docs moved to https://docs.zlens.app, and every docs page shows its YouTube tutorial.

Full list: CHANGELOG.

ZLens 0.2.9

A patch for Apps, found by walking the Jaffle sample on 0.2.8.

To upgrade, run npm i -D @zlens/cli@^0.2.9 in each project.

• Receipts name a reader's filter value on saved-query tiles: "Customer Name Melissa Lopez", not "Customer Name any", as on table tiles.
• "Certify now (recommended)" stays inside its button in the publish dialog when the text wraps.
• A related-table field is named once: "…has no Location Name field.", not "Location Location Name".
• Published App files name your git identity:
  • dql.app.json members and the App's README.md use git user.name and user.email, as certification receipts do.
  • The README lists the App's saved queries, tables and Metrics.

Full list: CHANGELOG.

ZLens 0.2.8

A branding patch: ZLens replaces DuckCode in everything people read. There are no behaviour changes.

To upgrade, run npm i -D @zlens/cli@^0.2.8 in each project.

• ZLens everywhere you read it: the docs, code comments and package metadata say ZLens.
  • create-zlens-app's author is ZLens.
  • NOTICE reads "ZLens is a product of DuckCode AI Labs".
• Unchanged: DuckCode AI Labs remains the copyright holder and the GitHub organisation. Theme token names and values are the same, so embedding hosts need no change.

Full list: CHANGELOG.

ZLens 0.2.7

A patch for MCP clients. Every answer's trust line now arrives as its own text block next to the data. Claude Desktop, Codex and other clients then open their answer with 🟢 Certified, 🔵 From Metrics or 🟠 AI-Generated instead of burying it.

To upgrade, run npm i -D @zlens/cli@^0.2.7 in each project.

• The trust line is its own block: results from query_via_block, query_semantic_model, query_via_metadata and answer_question that carry a trust line add it as a second plain-text block (**🟢 Certified · saved query …**), with the rule to start the answer with it.
• Tool descriptions say so too: the MCP descriptions of those four tools carry the same instruction.
• JSON unchanged: the JSON result is still the first block. A client that joins every text block before parsing JSON should parse the first block only.

Full list: CHANGELOG.

ZLens 0.2.6

A patch for honest answers over MCP and Ask. A semantic answer now covers the whole question or none of it. "Governed" is now From Metrics, and it applies only when every join is certified. Every MCP answer opens with its trust line.

To upgrade, run npm i -D @zlens/cli@^0.2.6 in each project.

• The whole question or not at all: query_semantic_model no longer drops a breakdown ("hour of the day"), a named member ("in Philadelphia") or a date range ("last quarter"). When one can't be expressed, the result says what is missing, and ask_dql sends the question to query_via_metadata.
• From Metrics:
  • Ask's "Governed" label reads From Metrics, matching Help.
  • A semantic answer that joins through a draft relationship is labelled AI-Generated, and the caveat names the relationship.
• Trust line first: every MCP answer with rows starts with a ready-made trustLine, such as 🟢 Certified · saved query monthly_revenue, 🔵 From Metrics · metric large_orders · not certified or 🟠 AI-Generated · … · needs review. Clients open their answer with it.
• Empty discovery results point back to ask_dql.
• Apps:
  • Certified saved queries are adopted in place.
  • Recovery messages use plain words.
  • Every row names its certifier.

Full list: CHANGELOG.

ZLens 0.2.5

A patch for MCP and Apps. Claude Desktop, Claude Code, Codex and Cursor now get a certified answer only when the block returns what was asked. The semantic layer answers with the metric the question names, labelled Governed as on the Ask page. In Apps, editing keeps saved queries and receipts, and Publish waits for pending changes.

To upgrade, run npm i -D @zlens/cli@^0.2.5 in each project.

• Certified only when the block returns the measure: "How many large orders did we get each month?" no longer answers from monthly_revenue, whose order count counts every order. "How has revenue changed by month?" still does.
• The metric the question names:
  • Average order value by customer type, or for new versus returning customers, answers with average_order_value by customer_type.
  • "What share of revenue comes from food each month?" answers with food_revenue_pct by month.
  • When nothing matches, the result says "No semantic match" instead of using another metric.
• Derived metrics compile natively when their formula is arithmetic over simple metrics with no offset window.
• Governed over MCP:
  • A semantic compile is labelled Governed (built from semantic metrics, not certified).
  • ask_dql sends questions the semantic layer answers to query_semantic_model.
• Apps:
  • Editing a changed App keeps its saved queries and receipts, and every Certified says who and when.
  • Publish waits for a pending save.
  • The Jaffle sample opens as an existing project.
  • App links open a page.

Full list: CHANGELOG.

ZLens 0.2.4

A patch for Apps. A total over a Top N saved query is no longer labelled Certified, and Certify always leaves a receipt. The Apps docs now match the product. In the Jaffle Shop sample, every Jaffle Growth tile has a certification receipt.

To upgrade, run npm i -D @zlens/cli@^0.2.4 in each project.

• Honest totals: a Total or KPI over a saved query that keeps only its first N rows (such as top_beverage_customers) now reads Not certified yet and says why. A tile that shows the rows as they are keeps its label.
• Certify always leaves a receipt: certifying a hand-written block with no companion YAML now writes one, so its tile shows who certified it and notices later edits.
• Ask about this App cites "saved query", not "block". The scope line names the page only when it differs from the App.
• No "Show AI copilot" button without an AI provider, like the other AI controls since 0.2.3.

Full list: CHANGELOG.

ZLens 0.2.3

Apps are built from the data you choose, with one trust answer on every screen: a tile is Certified or Not certified yet, and publishing never blocks unless the project requires it. A database-only first run reads plainly. zlens ci init writes a CI check that works on a clean clone. Chat clients with no guide file, such as Claude Desktop, answer from certified blocks first.

To upgrade, run npm i -D @zlens/cli@^0.2.3 in each project. Use Node 20, 22 or 24 (Node 24 LTS recommended).

Breaking (MCP): build_dql_app now starts an App Studio draft and writes no App files. See AI agents (MCP) in the changelog.

Highlights:

• Apps:
  • choose the App's data first;
  • fields from saved queries and related tables;
  • certify tables, saved queries and joins from the publish dialog;
  • Sort and Top N;
  • filters that follow dbt relationships;
  • three quick choices when no AI is connected.
• Trust: one model everywhere, "Certified by · date", and checking is not certifying.
• Setup: start from any folder, and open an existing ZLens project directly.
• Ask and blocks: Ask drafts keep their name and Domain; an edited certified block needs recertification; Notebook AI reads the cell it was opened from.
• MCP: ask_dql first; inspect_dql_project lists the certified blocks and their grains; query_semantic_model names the certified block that answers.
• CI: zlens ci init, and strict eval thresholds.

Full list: CHANGELOG.

ZLens 0.2.2

Sharing through your own git repository now works from the workbench without
a terminal, and the DuckDB driver says which Node to use instead of failing
on Node 25 and 26.

To upgrade, run npm i -D @zlens/cli@^0.2.2 in each project. Use Node 20, 22
or 24 (Node 24 LTS recommended).

Source control

• Connecting your own repository works on the first send. A repository
  the host created with a README, licence or .gitignore no longer loops
  between "Get updates first" and "Send the branch first": ZLens brings those
  files in (your project's README wins; missing .gitignore lines are added)
  and sends. A repository holding other, unrelated work is never combined
  with the project; the message says how to add ZLens to it instead.
• Know before you send. The Source control page checks the remote in the
  background and says "3 new on the remote · 1 of yours not sent", "Up to
  date" or "Can't reach the remote". Send asks you to get updates first
  instead of failing.
• Send from the main branch goes to a new branch by default, ready for a
  pull request, and leaves the main branch as the team has it. Sending
  straight to the main branch asks again.
• Get updates works when you and the remote both changed. Your unsent
  changes are replayed on top of the team's; changes you already sent are
  never rewritten. Files changed on both sides get Compare, Keep mine and Keep
  theirs, then Continue, or Cancel update to put everything back. Undo update
  reverses a finished update.
• Review branches stay current. Get updates on a review branch also brings
  in what the team merged into the main branch.
• The ZLens sample is read-only. In a folder cloned from
  jaffle-shop-duckdb or jaffle-shop-warehouse, Send is not offered;
  Connect your own repository keeps the sample as upstream.
• Pull requests target your repository's default branch (main,
  master, develop…), not a guess.
• New projects start on main (or your init.defaultBranch), not git's
  master fallback.
• New guide: Share your work with your team.

Fixed

• DuckDB on Node 25 and 26. ZLens's DuckDB driver has no prebuilt binary
  for those versions, so its install fell back to a 10-minute source build
  that usually failed, and the Connections test said the driver was missing.
  Startup, Connections (Test and Install) and zlens doctor now say "use Node
  24 LTS or 22" and never start that build on their own
  (ZLENS_DUCKDB_BUILD_FROM_SOURCE=1 opts in). @zlens/cli declares Node 20,
  22 or 24 in engines. Moving to @duckdb/node-api is proposed in
  RFC 0011.