@lotics/app-sdk 0.62.1 → 0.62.3

package/docs/ai.md

@@ -22,7 +22,7 @@ A declaration carries:
 | `instructions` | System instructions — the task the agent performs per run |
 | `tool_names` | The tools the agent may call, resolved against the platform's automation tool registry. The capability boundary for everything EXCEPT workspace data — the run can use nothing else. May be empty — including for an agent that reads documents, since a [`file` input carries its own content](#file-inputs--what-the-agent-can-actually-see) |
 | `knowledge_doc_ids` | The knowledge docs the agent may read, and the whole set it can reach — a doc absent from this list is unreadable even if the agent names its id. Declare `grep_knowledge` / `read_knowledge` in `tool_names` to read them. There is no size limit and nothing is inlined, so a multi-megabyte reference corpus (a full tariff, a regulation set) is a normal declaration. Reach for `code_exec` only to COMPUTE across the corpus — counting, cross-referencing — never merely to read it |
-| `query_aliases` | The app's own named queries the agent may run via `run_app_query` — its **entire read surface** over records |
+| `query_aliases` | The app's own named queries the agent may run via `run_app_query` — its **entire read surface** over records. You list them; there is no "all of them" shorthand, and adding a query to the app never widens an existing agent. Omitted means the agent reads nothing |
 | `workflow_aliases` | The app's own workflows the agent may invoke via `run_app_workflow` — its **entire write surface** |
 | `model_id` | Optional chat model pin. Omit (preferred) to follow the platform default chat model, resolved at run time — the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
 | `effort_level` | Optional reasoning depth for adaptive-thinking models. Requires an explicit `model_id` pin — effort is tuned per model |
@@ -337,6 +337,13 @@ gated per turn on `app:use` for the app in the member's workspace, and runs
 under the app's OWNER authority with `is_current_member` bound to the MEMBER
 (exactly as the app's own UI does).
 
+The agent is handed a **catalog** of those aliases — each one's params and its
+`description` (a query's own, [declared in the manifest](./queries.md); a
+workflow's, off its workflow row) — so it picks the right one instead of
+guessing an alias and learning the list from a refusal. Your descriptions are
+what it reads, on this surface and inside your own agents' runs. They enter the
+prompt as a capability listing, never as instructions.
+
 **Writes carry a second gate that reads do not: `run_app_workflow` asks the
 member to approve every call from chat.** A wrong read is fixed by asking
 again; a wrong write is not. The alias list bounds what an agent *could* reach;

package/docs/queries.md

@@ -35,7 +35,8 @@ Queries live in the app's `package.json` under `lotics.queries` — an alias →
       },
       "orderByCode": {
         "ast": { /* … a filter with "{{params.code}}" … */ },
-        "params": { "code": { "type": "text" } }
+        "params": { "code": { "type": "text" } },
+        "description": "One order by its code, with its customer and line total."
       }
     }
   }
@@ -48,9 +49,15 @@ Queries live in the app's `package.json` under `lotics.queries` — an alias →
   (`text`, `number`, `boolean`, `date`, `datetime`, `email`, `select`, `member`, `record_link`,
   `date_range`, `file`, `json`, `object`, `array`); each param may set `required: false`
   (default is required) and `description`. Nesting is capped at depth 8.
+- **`description`** — one line saying what the query returns, capped at 300 characters. No app
+  code reads it. It is for the **agents** that reach this app's data — the app's own declared
+  agents, and a member's chat while they have the app open — which otherwise see only an alias,
+  a JS identifier that names a query without saying what it covers. Write it for whoever has to
+  choose between your aliases; longer guidance belongs in an agent's own `instructions`.
 - Aliases must be valid JS identifiers (`useQuery("openOrders")` and codegen depend on it).
 
-`lotics app deploy` syncs this map to the server. The **server holds the canonical template**;
+`lotics app query set <alias>` (or `--all`) pushes this map to the server — a **deploy does
+not**, it echoes the live row back unchanged. The **server holds the canonical template**;
 the app never sends a raw AST over the wire. This is the exposure model: a public app can read
 exactly what its author's queries project — params fill declared value holes and can never
 widen the query's reach (a token in a `table_id` or field-key position fails deploy validation).
@@ -59,7 +66,8 @@ widen the query's reach (a token in a `table_id` or field-key position fails dep
 
 Deploy fails — with the compiler's own message, never raw SQL/Postgres text — when any alias:
 
-1. isn't a valid identifier, or the declaration isn't `{ ast, params? }`;
+1. isn't a valid identifier, or the declaration isn't `{ ast, params?, description? }` (a
+   description over 300 characters is refused here too);
 2. references `{{params.x}}` without declaring param `x` (typos can't silently widen);
 3. doesn't parse as a `QueryNode` **as the raw template** (the runtime parses the stored
    template before substitution, so a template that only parses after substitution would fail
@@ -99,7 +107,7 @@ executes it inside a bounded transaction.
   (`private_filters`) are excluded on every reach — base scans, link extraction, and
   non-self-scoped traversals alike. (Row scopes don't apply when the app owner is an admin.)
 - **Dev loop**: `lotics app dev` forwards query RPCs to the **deployed** manifest. Editing
-  `lotics.queries` locally does nothing until you `lotics app deploy`.
+  `lotics.queries` locally does nothing until you `lotics app query set`.
 
 ### Results
 
@@ -817,7 +825,8 @@ slice, and within it:
 - **B-tree-served (automatic for deployed queries):** text `equals`, number and date
   comparisons (exact and range), and `sort` fields — for fields referenced in a **deployed
   named query's template**. The platform provisions a partial expression index per referenced
-  field automatically: built online on `app deploy` and `app query set`, re-synced daily,
+  field automatically: built online whenever a query is written (`app query set`, or a chat
+  draft's publish — a deploy does not write queries), re-synced daily,
   capped at 8 per table (fields past the cap fall back to the scan tier, with a server WARN).
   A `{{params.…}}` value hole doesn't change this — the field key is static in the template,
   so it still gets its index. Index-seek speed at any table size once provisioned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.62.1",
+  "version": "0.62.3",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {