@lumerahq/cli 0.19.15 → 0.19.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumerahq/cli",
-  "version": "0.19.15",
+  "version": "0.19.16",
   "description": "CLI for building and deploying Lumera apps",
   "type": "module",
   "engines": {

package/templates/default/AGENTS.md

@@ -41,9 +41,9 @@ All resources use **external IDs** in the format `<app-name>:<resource-name>` (a
 **All collection names are automatically namespaced by project.** Always use bare names (e.g. `orders`, not `myproject__orders`) everywhere — in collection JSON files, Python SDK calls, JavaScript hooks, and frontend queries. The platform resolves bare names to the project-scoped version transparently.
 
 - `pb.ensure_collection("orders", ...)` → stored as `{project}__orders`
-- `pb.search("orders", ...)` → resolves to `{project}__orders`
+- `query_sql("SELECT id FROM orders")` → resolves to `{project}__orders`
 - `ctx.dao.find("orders", ...)` → resolves to `{project}__orders`
-- `pbList("orders", ...)` in frontend → resolves via `X-Lumera-Project` header
+- `pbSql({ sql: "SELECT id FROM orders" })` in frontend → resolves via `X-Lumera-Project` header
 
 **Never manually prefix collection names with `{project}__`.** Two projects can each have an `orders` collection — they are fully isolated.
 
@@ -96,10 +96,16 @@ Custom apps run in an **iframe**. **Always use the `@lumerahq/ui` bridge for API
 
 ```ts
 // ✅ Correct — uses postMessage bridge, no CORS issues
-import { pbSql, pbList, pbCreate, pbUpdate, pbDelete } from '@lumerahq/ui/lib';
+import { pbSql, pbCreate, pbUpdate, pbDelete } from '@lumerahq/ui/lib';
+
+// New read queries: use SQL for collection access, including lookups, lists, reports, joins, ordering, and filters
+const result = await pbSql<{ id: string; amount: number }>({
+  sql: 'SELECT id, amount FROM orders WHERE status = {:status} ORDER BY updated DESC LIMIT 100',
+  params: { status: 'pending' },
+});
+const records = result.rows;
 
 // CRUD
-const records = await pbList('orders', { filter: JSON.stringify({ status: "pending" }) });
 await pbCreate('orders', { amount: 100 });
 await pbUpdate('orders', recordId, { status: 'done' });
 await pbDelete('orders', recordId);
@@ -113,6 +119,9 @@ fetch('https://app.lumerahq.com/api/pb/sql', ...);
 
 **Rules:**
 - Always import from `@lumerahq/ui/lib` — never write a custom `apiFetch` with raw `fetch()`
+- Use `pbSql()` for new read-only collection access
+- Existing `pbList()` / `pbSearch()` filter code remains supported for simple existing list/search reads; do not rewrite working code just because SQL exists
+- Use record helpers such as `pbCreate()`, `pbUpdate()`, and `pbDelete()` for mutations
 - Token is not needed — the bridge handles auth via the parent session
 - `X-Lumera-Project` header is not needed — the parent adds it automatically