@lotics/cli 0.315.18 → 0.316.0

package/docs/working_in_a_workspace.md

@@ -0,0 +1,60 @@
+# Working in a workspace — the right means for each job
+
+Once tables and apps exist, an agent does the team's work through them. The means depends on what the work is.
+
+| The work | The means | Why |
+|---|---|---|
+| A business operation: move an order on, issue a paper, notify someone | `run_app_workflow` on the app's act, `act_<key>` or the `workflow` it names | The outcome equals a person's press: status, stamps, documents, notifications. `update_records` on an act's field skips all of them. |
+| Data entry, a correction, loading the owner's lists | `create_records`, `update_records` | The table's rules hold for every writer. |
+| A rule or policy the business wrote | `get_workspace` with `search`, then `read_knowledge` | The business's own words, not a guess. |
+| A file someone hands over | `read_file_content`; `upload_file` to keep it (over MCP or the CLI) | Reads its content; the upload files it in the workspace. When your host passes no bytes, `upload_file` with `person: true` gives the person a link to drop it on. |
+| A paper an app makes | the act that makes it, which files it on the record | `generate_document` makes an unattached file, for a paper no app makes. |
+| A connected service (KiotViet, MISA, a carrier) | a workflow step, reached through a Workflow node | No tool calls a service directly (`workflows/reaching-a-connected-service`). |
+| A figure or list the business defines, or an operation it repeats | the app's declared Query or Workflow node: `run_app_query`, `run_app_workflow` | The node is the business's own definition, found by `get_workspace` with `search` and read in `get_app`. |
+| A count or sum no app answers | `aggregate_records` (grouped by `group_by`), `query_records` | |
+
+Find the means in this order: `get_workspace` maps the workspace; `search` it by what is asked ("overdue"), which matches an app's declared Query and Workflow keys and descriptions and names the matching keys under the app; `get_app` lists that app's queries and workflows with their inputs. Run the declared node. Only a question no node answers goes to `aggregate_records`.
+
+## Workspace settings and standing instructions
+
+`get_workspace` shows the workspace's settings (name, timezone, default currency) and, with kind `instruction`, its standing instructions. `set_workspace` changes them in one all-or-nothing patch: a setting it leaves out is unchanged, and `instructions` is a map keyed by instruction name where an entry creates or merges and `null` removes. A workspace-wide instruction arrives with the connection, in the instructions a host reads when an agent connects; the answer of `set_workspace` names any that no longer fit that block. An administrator writes them.
+
+## People
+
+`get_workspace` with kind `member` lists the members. `set_member` is an admin's: `members` is a map keyed by an email address or a member id, where an email no member holds invites that person (`role` is `member` or `admin`; the invitation email goes out), a current member's entry sets `name`, a removed member's entry restores them, and `null` removes a member or cancels the invitation pending to that address. A member's role cannot be changed through it. The whole map is checked before anything is written or sent. A member's tool list does not carry `set_member`, `set_group` or `set_workspace`.
+
+## Doing an operation
+
+`get_app` lists the app's acts as `act_<key>` (or the `workflow` an Act names) with what each takes. `run_app_workflow` with `dry_run: true` writes nothing
+and answers what the run would do; the same call without it runs. An act refuses a row its conditions do not hold for,
+and says why (`agent_surface` § A refusal).
+
+## Writing records
+
+`create_records` takes 50 records a call, 20 or more of one shape in columnar form (`field_keys` once, then `rows`);
+`update_records` changes one or many. Both name fields and select options by alias, and `field_values` gives each
+type's value. Every write meets the table's rules (`model/write-rules`): every broken rule is listed at once, and a
+locked record answers under `blocked`. The owner's own lists (a menu with prices, customers, open orders) are rows of their
+tables, loaded this way after `set_tables`.
+
+## Answering a question
+
+1. `get_app`: a Reading's query (its `key`) is the business's own figure for it. `run_app_query` with `alias` and
+   `params` returns it; `filters`, `fields`, `sort` and `count` narrow the result.
+2. A period's total is one call per period, each with `from` and `to` or a date filter. `aggregate` groups a result by
+   a column (`by`), a number's bands (`bands`) or a date column's day (`day`), and sums one (`sum`).
+3. A question no app answers is `aggregate_records` (counts and sums grouped by a field) or `query_records`, over one
+   table; `filters` is the grammar of both.
+
+## A worked day
+
+A customer asks for the status of order 1042, then the order is shipped:
+
+```
+get_workspace          kind "app"                       → app_id of the sales desk
+get_app                app_id                           → aliases: order_list, act_ship, …
+run_app_query          app_id, alias "order_list", params {"search": "1042"}
+run_app_workflow       app_id, alias "act_ship", inputs {"record_id": "rec_…"}, dry_run true
+run_app_workflow       the same call without dry_run
+aggregate_records      table_id, group_by "stage"       → how many orders stand at each stage now
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.315.18",
+  "version": "0.316.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {