@lotics/cli 0.294.1 → 0.295.0

package/docs/cli_reference.md

@@ -43,7 +43,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics knowledge hide <id...>` / `lotics knowledge unhide <id...>` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, hidden }`. Hiding takes docs out of every **listing** — the Library's list, `list_knowledge`, and the corpus `grep_knowledge` searches — while leaving IAM untouched and keeping them readable **by id** (`read_knowledge` with an id, a code run staging one, an app agent's declared set). So it can never silently break an app that depends on a doc, and unhiding costs nothing. Refuses the no-argument form rather than reading it as "everything". |
 | `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |
 | `lotics setup <model.json> [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes — `--name` and `--timezone` apply), then applies the model to its workspace, then prints the one-time sign-in link. **When that email already has an account it hands over to the `lotics auth login` flow** — it prints the sign-in page to open and the code it must show, and **exits 1 having created nothing**; the person presses Confirm and runs the same command again, which collects the key and carries on into the model. (`--wait` holds the terminal through the Confirm instead, finishing in one command.) The re-run is not refused for naming an `--email` it is now signed in as — that address IS the account it holds, not a second one. The file is a workspace MODEL, and it is read and checked before an account is created — the design decisions an apply would refuse it for too (`lotics docs design`), since a new workspace holds no rows to change them — because a file with a typo in it must not leave an organization behind. Then it is `lotics model apply` run on the new workspace: its tables, rows and apps; the sign-in link lands on its app when it has one, else on the workspace's app list. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently writes into an org the caller did not name — the message says how to do each thing on purpose. Without it, `setup` applies the model to the account you already have. A path positional after the file is accepted and IGNORED with a warning — `setup` writes nothing to disk — so a prompt that passes one still runs. **`--json` prints one object on stdout and nothing else** — what `lotics model apply --json` does (`tables`; `apps`, each with `alias`, `app_id`, `version_id`, `origin`, `address` and `findings`; and `findings`) plus `organization_id`, `workspace_id` and `signin_url`, and a `warnings` array carrying everything the prose form would have said out of band, such as a sign-in link that could not be minted. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. Reachable with no install: `npx -y @lotics/cli setup …`. |
-| `lotics model apply <model.json> [--app <alias> ...] [--plan] [--json]` | **The model, applied to this workspace, through the `apply_model` tool.** The file is read and checked against the model's own rules with the validator the server runs, every problem in one run, before anything is uploaded. **The apply refuses an app leaving out a treatment its rows call for** (`lotics docs design`) — judged by the server beside the workspace's rows, before it writes anything — until the app adopts it or states why not under the `declines` key the refusal names; the refusal carries each refused app's patch adopting its decisions, to merge in the order printed. Documents a row attaches by a path beside the file are uploaded first and the rows sent with their `fil_` ids; a path this workspace already recorded keeps its id, so a re-apply uploads nothing twice. **Where the file was pulled (`-o`) or applied in this workspace before, only what it changed since is sent**, as a `patch`: what changed in the workspace since and the file does not touch stays. What the file takes out is sent as a removal: it goes where an apply rebuilds it (an app's acts and columns, a write rule) and is refused, naming the tool that deletes it, where an apply never deletes it (a table, a field, an option, an app). A file that reorders items named by their `alias`, or states a `null` a patch would read as a removal, sends the whole model, said on stderr. The copy each change is read against is kept per workspace and file under `~/.lotics/model_bases`: an apply narrowed by `--app` leaves in it the other apps as they were, so the next apply sends their edits again, and an apply that fails — refused, or cut off — leaves none, so the next sends the whole model. Then the tool adopts or creates every table (the table this workspace bound the entity to, else an existing table of the same label, is ADOPTED and given the fields, options and views it lacks; no stored value changes), writes first rows only where every bound table is empty, and mints a new version of each app the model declares — `--app` (repeatable, comma-separated) narrows which apps, while the tables are applied whole. Prints one line per app — alias, `app_id`, `created`/`updated` with the version minted or `unchanged`, and the address it is served at — then the model's notes once, as the server states them. **`--plan` writes nothing and uploads nothing**: it prints what the apply would do to the tables (what it would create, what it leaves as the workspace has it, what the two disagree about), which apps it would create or update, and what it would refuse an app for — the decisions among its findings, read beside the workspace's rows, with each refused app's patch — exiting 1 when it would refuse one; workflow bodies are checked only at apply, since they name fields a plan has not created. **A rollback restores an app's earlier version** (`lotics run rollback_app`); table changes and data writes stay. Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, tables, apps, findings}` on stdout (with `--plan`, each table and app is what the apply would do, an app the patches change carrying its body as they leave it as `draft`, and `designs` each refused app's patch in merge order), or `{ok: false, findings}` when the file does not check. |
+| `lotics model apply <model.json> [--app <alias> ...] [--plan] [--json]` | **The model, applied to this workspace, through the `apply_model` tool.** The file is read and checked against the model's own rules with the validator the server runs, every problem in one run, before anything is uploaded. **The apply refuses an app leaving out a treatment its rows call for** (`lotics docs design`) — judged by the server beside the workspace's rows, before it writes anything — until the app adopts it or states why not under the `declines` key the refusal names; the refusal carries each refused app's patch adopting its decisions, to merge in the order printed. Documents a row attaches by a path beside the file are uploaded first and the rows sent with their `fil_` ids; a path this workspace already recorded keeps its id, so a re-apply uploads nothing twice. **Where the file was pulled (`-o`) or applied in this workspace before, only what it changed since is sent**, as a `patch`: what changed in the workspace since and the file does not touch stays. An item named by its `alias` that the file puts in a new place — an act among an app's acts, a field between two others — is sent as a move beside the patch: inside an app it is built into the app, an option of a select takes its new place among that select's options on the table, and a table's fields and views, the roles, the templates and the apps themselves keep the order the workspace holds, said as a note. A list whose items carry no `alias` — an app's columns, a section's fields, the sections — is sent whole in its new order. What the file takes out is sent as a removal: it goes where an apply rebuilds it (an app's acts and columns, a write rule) and is refused, naming the tool that deletes it, where an apply never deletes it (a table, a field, an option, an app). A file stating a `null` a patch would read as a removal sends the whole model, said on stderr, and so does a reorder sent to a server that takes no move. A patch builds the apps it states or moves an item of and each other app whose build it changes, `--app` naming others; one whose every key and move lies inside one app's body leaves the tables as they stand — its `tables` is empty — and checks and builds that app alone, beside any other app whose build reads what it changed. The copy each change is read against is kept per workspace and file under `~/.lotics/model_bases`: an apply narrowed by `--app` leaves in it the other apps as they were, so the next apply sends their edits again, and an apply that fails — refused, or cut off — leaves none, so the next sends the whole model. Then the tool adopts or creates every table (the table this workspace bound the entity to, else an existing table of the same label, is ADOPTED and given the fields, options and views it lacks; no stored value changes), writes first rows only where every bound table is empty, and mints a new version of each app the model declares, or the patch builds — `--app` (repeatable, comma-separated) narrows which apps, while the tables are applied whole. Prints one line per app it built — alias, `app_id`, `created`/`updated` with the version minted or `unchanged`, and the address it is served at — then the model's notes once, as the server states them. **`--plan` writes nothing and uploads nothing**: it prints what the apply would do to the tables (what it would create, what it leaves as the workspace has it, what the two disagree about), which apps it would create or update, and what it would refuse an app for — the decisions among its findings, read beside the workspace's rows, with each refused app's patch — exiting 1 when it would refuse one; workflow bodies are checked only at apply, since they name fields a plan has not created. **A rollback restores an app's earlier version** (`lotics run rollback_app`); table changes and data writes stay. Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, tables, apps, findings}` on stdout (with `--plan`, each table and app is what the apply would do, an app the patches change carrying its body as they leave it as `draft`, and `designs` each refused app's patch in merge order), or `{ok: false, findings}` when the file does not check. |
 | `lotics model pull [-o <model.json>]` | **This workspace's model, rebuilt from what owns each part** — the tables, fields, options, templates and roles the workspace holds, how rows are recognised, and each app's body from its current version — through the `get_model` tool, as the file `model apply` reads: to stdout, or to the file `-o` names. What the workspace holds that a model cannot state is printed on stderr, never written into the file. Applying what it wrote changes nothing. With `-o`, what it wrote is the copy the next `model apply` of that file reads its changes against. |
 | `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`), scaffolds a Vite + React + TypeScript project into `[path]` (default `./<name>`, refused when not empty — before the app row exists) that depends on `@lotics/app-sdk` alone and draws with plain React, and installs it (`npm install --ignore-scripts`), then writes the declarations of the app's live bindings (`get_app_types`) into `.lotics/`, which the project's `tsconfig.json` includes. `package.json#lotics` names the app and its workspace, which is how `app deploy` in that directory finds both. The app has no version until the first `lotics app deploy`. `--custom` is required: an app the runtime draws from a model is made by `lotics model apply`. The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the project. |
 | `lotics app pull [app_id] [path]` | **A custom-code app's live source, as a project ready to deploy on it.** The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** — but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`get_app_types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). A JSON app has no source tree: the server's refusal names `get_model`, and `lotics model pull` is its pull. |

package/docs/design.md

@@ -16,8 +16,11 @@ rows in time, a template's act — until the model states it or declines it.
 
 1. **People and jobs, before any table.** Name each person by the work they do, then each JOB in one
    sentence: who does it, what exists when it is done, the record it moves. The sentence is the app's
-   `name` and `description`. One app per job, each one register over one entity — an app per table, or one
-   app holding every table, is no job's screen.
+   `name` and `description`. A job is a desk a person works every day from its own list; one app per job,
+   each one register over one entity — an app per table, or one app holding every table, is no job's screen.
+   A list worked only in passing on the way through another job — the rates a quote is priced from, the
+   transfers its receipts are matched to, the statement sent from its records — is a block, a section or an
+   act of that job's app, never an app of its own. A small business usually lands at four to six.
 2. **The entities the jobs touch.** A status is a state the work sits in, six options or fewer: a touch
    ("called") is a row of a log, a money fact ("paid in full") a formula the figure shows. A quantity is a
    number with its `unit`, never words in a text field; a quantity of several kinds is child rows, one per
@@ -51,18 +54,18 @@ then check again. A note refuses nothing.
 |---|---|---|
 | People or organisations | `records.<entity>.party`, with a photo or logo as its `image` | `model/records` |
 | Things with a photo, a scan or a paper | `records.<entity>.image`; `layout: "cards"` where the picture is how a row is found | `model/records`, `model/cards` |
-| Read by their day | `layout: "calendar"`; on a record, an `agenda` block | `model/calendar`, `model/blocks` |
+| Read by their day | `layout: "calendar"`; on a record, an `agenda` block | `model/calendar`, `model/timeline-and-agenda` |
 | Booked on a resource | `layout: "lanes"` with `lanes`, and `write_rules` `no_overlap` | `model/lanes`, `model/write-rules` |
 | A plan of spans | `layout: "gantt"` with `gantt` | `model/gantt` |
 | Who did what on which day | `layout: "roster"` with `roster` | `model/roster` |
-| A log of what happened | a `timeline` block | `model/blocks` |
+| A log of what happened | a `timeline` block | `model/timeline-and-agenda` |
 | Opened to be worked on | the record's `sections`, in the order the work reaches them — `at` where it moves in steps | `model/record-page` |
 | Rows that each belong to another row | a `rows` block on that row's record | `model/blocks` |
-| Moving through a status | an act per move, `status.history`, and the register's `readings` | `model/acts`, `model/records`, `model/readings` |
+| Moving through a status | an act per move, `status.history`, and the register's `readings` | `model/acts`, `model/status`, `model/readings` |
 | Counted over a period | the register's `tabs` over one `period`; an `open` tab's `where` reads only what was true at the period's end, never a status the row moves on from | `model/tabs` |
-| Papers a case gathers | a rows block with `expect`; the papers made, an act's `templates` | `model/blocks`, `model/acts` |
-| Papers to read | an act's `intake` with `fills` | `model/acts` |
-| Calls and visits | an act's `record` | `model/acts` |
+| Papers a case gathers | a rows block with `expect`; the papers made, an act's `templates` | `model/blocks`, `model/papers-and-recordings` |
+| Papers to read | an act's `intake` with `fills` | `model/papers-and-recordings` |
+| Calls and visits | an act's `record` | `model/papers-and-recordings` |
 | Documents covering lines | a rows block with `under` | `model/blocks` |
 | Rows on file a record takes in | a rows block with `pick` | `model/blocks` |
 | One owner's question across jobs | a dashboard app | `model/dashboards` |
@@ -141,13 +144,26 @@ status holds it, `set` to the next), at the foot of the section whose work it en
 condition a person sets. A value decided as a row reaches an outcome — why it was lost, refused, voided — is that
 act's `asks`, never a field the reader must remember to fill. An act reaching past the workspace — sending an invoice
 to a service, a letter by mail — runs its `workflow`, and what the workflow keeps from the answer (an invoice's id,
-its link) is named in `writes`, the act's as what it sets is.
+its link) is named in `writes`, the act's as what it sets is. A stage the work only steps aside into from one step
+and leaves only back to it — a pause, a repair — is a detour: its option and its section stand before that step,
+entered by its own act; listed after, it reads as the work's next step.
+
+#### Stages
+
+Name each job's work plan by its shape: a status a person sets; a pipeline, where who holds the row and for how long
+matter; or tasks, where only how many are done counts (`records.<entity>.task`). A pipeline states each stage once in
+`records.<entity>.status.stages` — its `owner` (a member field, a link's member field, or a `role`) and its target
+`within` days — and the server holds it: only the owner's acts move the row on, and a level an amount skips stands
+named with why. Late rows, rows due soon, a warning the line draws and rows waiting on the reader stand first in a
+register; a register whose job is a strict order, a first-come queue, states `register.attention: false`.
 
 #### History
 
 `records.<entity>.status.history` names a child the app's own writes append one row to per status move: its
 link to the row, the new status, the moment and who. It keeps when each row entered each status and who
-moved it; `record.history: true` draws it beside the record where the owner asks for that trail. Worked: `examples/approval`.
+moved it — what the rail reads. A record's activity shows every move as a change, so `record.history: true` adds
+nothing — and beside `record.activity: false`, which shows them nowhere, it is
+refused. Worked: `examples/approval`.
 
 #### Readings
 

package/docs/examples.md

@@ -468,7 +468,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
 
 **Read.** `records.customer.party: "organization"` and its `image` (the logo); a `timeline` of touches, a `trend` of its orders, and its papers `expect`ed by kind.
 
-**Keys.** `model/records`, `model/blocks`, `model/reading-blocks`
+**Keys.** `model/records`, `model/timeline-and-agenda`, `model/blocks`, `model/reading-blocks`
 
 **Not when.** A list of customers is not a job by itself: the customer is a link on the desk whose rows name it, unless the job is the account itself.
 
@@ -701,7 +701,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
 
 **Read.** `expect` blocks for the papers brought (one line per kind, the missing ones empty), an act's `templates` for the forms made (ticked and made at once, kept in `into`), and `intake` reading the papers brought.
 
-**Keys.** `model/blocks`, `model/acts`
+**Keys.** `model/blocks`, `model/papers-and-recordings`
 
 **Not when.** A record that needs no papers, or one paper made once — a single `template` act.
 
@@ -1113,7 +1113,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
 
 **Read.** An act's `record` (into the `timeline` child: audio, transcript, when and who) and `fills` (the touch's fields an agent fills from the transcript).
 
-**Keys.** `model/acts`, `model/blocks`
+**Keys.** `model/papers-and-recordings`, `model/timeline-and-agenda`
 
 **Not when.** Calls made and logged elsewhere — a `timeline` with its own add keeps the note.
 
@@ -1441,7 +1441,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
 
 **Read.** `records.de_nghi.status` with its `history` (each move: when and who), sections staged by `at`, and `register.readings` leading with the headline number.
 
-**Keys.** `model/records`, `model/record-page`, `model/readings`
+**Keys.** `model/status`, `model/record-page`, `model/readings`
 
 **Not when.** Rows that never move — a reference list (a price list, a catalog) has no status and no headline number.
 
@@ -1479,6 +1479,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
           "options": [
             {"alias": "nhap", "color": "slate"},
             {"alias": "cho_duyet", "color": "amber"},
+            {"alias": "cho_chu_tich", "color": "violet"},
             {"alias": "da_duyet", "color": "blue"},
             {"alias": "da_chi", "color": "green"},
             {"alias": "tu_choi", "color": "rose"}
@@ -1502,7 +1503,17 @@ Every key: the `model` reference, at the pages each section names under **Keys**
     "de_nghi": {
       "title": "noi_dung",
       "subtitle": ["du_an"],
-      "status": {"field": "trang_thai", "closed": ["da_chi", "tu_choi"], "history": "lich_su_duyet"},
+      "status": {
+        "field": "trang_thai",
+        "closed": ["da_chi", "tu_choi"],
+        "history": "lich_su_duyet",
+        "stages": {
+          "nhap": {"owner": "nguoi_de_nghi"},
+          "cho_duyet": {"owner": {"role": "giam_doc"}, "within": 1},
+          "cho_chu_tich": {"owner": {"role": "chu_tich"}, "within": 2},
+          "da_duyet": {"owner": {"role": "ke_toan"}, "within": 2}
+        }
+      },
       "figure": "so_tien",
       "limits": {"da_duyet_du_an": "ngan_sach_du_an"},
       "due": ["han_thanh_toan"],
@@ -1544,7 +1555,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
           },
           {
             "title": "Duyệt",
-            "at": ["cho_duyet"],
+            "at": ["cho_duyet", "cho_chu_tich"],
             "fields": ["nguoi_duyet", "duyet_luc", "ly_do_tu_choi"],
             "acts": ["rut_lai"]
           },
@@ -1562,7 +1573,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {
           "alias": "rut_lai",
           "label": "Rút lại",
-          "when": {"trang_thai": ["cho_duyet"]},
+          "when": {"trang_thai": ["cho_duyet", "cho_chu_tich"]},
           "set": {"trang_thai": "nhap"},
           "confirm": true
         }

package/package.json

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