@lotics/cli 0.233.0 → 0.235.0

package/dist/src/client.d.ts

@@ -344,6 +344,15 @@ export interface KnowledgeWarnings {
     /** `knowledge_expects` doc names with no matching workspace doc. */
     missing_expected_docs: string[];
 }
+/**
+ * An option's mark as stored and read back — `storedOptionMarkSchema` in
+ * `@lotics/shared`, typed structurally here because a published `.d.ts` cannot
+ * resolve that specifier.
+ */
+export interface OptionMark {
+    kind: string;
+    name: string;
+}
 /**
  * A workspace MODEL on the wire — a package contract with no apps, plus the
  * first rows that travel beside it keyed by entity alias.
@@ -361,6 +370,8 @@ export interface ScaffoldWorkspaceRequest {
     }>>;
     /** Bind an entity whose label already names a table here. Absent, a colliding label is refused. */
     adopt?: boolean;
+    /** The account each connection alias pushes through, by `cac_` id — where more than one of its provider is usable. */
+    connections?: Record<string, string>;
 }
 export interface ScaffoldWorkspaceResult {
     /** Every entity the model declares, in contract order. */
@@ -412,6 +423,49 @@ export interface ScaffoldWorkspaceResult {
      * whose rule nobody named is the one a reader has to be told about.
      */
     carried_rules?: string[];
+    /**
+     * Every table automation the model declares, with the table workflow it is:
+     * created by this run, or rewritten in place — found through the binding
+     * (`id`) or by its label on its table. Absent from an instance too old to
+     * provision one, which also refuses a model that declares any.
+     */
+    automations?: Array<{
+        alias: string;
+        entity: string;
+        table_workflow_id: string;
+        bound_by: "created" | "id" | "label";
+    }>;
+    /**
+     * The account each connection the model declares pushes through: named by the
+     * caller (`chosen`), kept from the binding this workspace held (`id`), or the
+     * only account of its provider the applier can use (`only`). Absent from an
+     * instance too old to bind one, which also refuses a model that declares any.
+     */
+    connections?: Array<{
+        alias: string;
+        connected_account_id: string;
+        provider: string;
+        bound_by: "chosen" | "id" | "only";
+    }>;
+    /**
+     * Options of an ADOPTED field that kept a mark other than the model's, by
+     * binding key — every surface draws the live one. Absent from an instance too
+     * old to state it, for the reason `carried_rules` is.
+     */
+    kept_marks?: Array<{
+        alias: string;
+        model: OptionMark;
+        live: OptionMark;
+    }>;
+    /**
+     * ADOPTED fields the model marks whose marks the run did not write, by binding
+     * key, with the live options that wear none and that the model does not mark.
+     * Absent from an instance too old to state it, for the reason `carried_rules` is.
+     */
+    unwritten_marks?: Array<{
+        alias: string;
+        bare: string[];
+    }>;
     /**
      * Bound aliases this workspace calls something other than the model does.
      *
@@ -461,10 +515,16 @@ export interface ModelBinding {
     entities: Record<string, BoundEntity>;
     templates: Record<string, BoundTarget>;
     roles: Record<string, BoundTarget>;
+    /** Automation alias → the table workflow it became. Absent from an instance too old to bind one. */
+    automations?: Record<string, BoundTarget>;
     /** `<entity-alias>:<row-ref>` → the record that first row became. */
     rows: Record<string, string>;
     /** The path a row attached a document by → the file it was uploaded as. */
     documents: Record<string, string>;
+    /** A plan's app alias → the app created for it here. Absent from an instance too old to bind one. */
+    apps?: Record<string, BoundTarget>;
+    /** A connection alias → the connected account an apply chose for it. Absent from an instance too old to bind one. */
+    connections?: Record<string, BoundTarget>;
 }
 /**
  * A workspace read BACK as a model — the inverse of the scaffold above.
@@ -832,6 +892,14 @@ export declare class LoticsClient {
     recordModelDocuments(documents: Record<string, string>): Promise<{
         recorded: number;
     }>;
+    /**
+     * Record which app each of a plan's app aliases became — stated by the create
+     * that made it, since an app row is made from a name and the alias is the
+     * author's file. What a sibling act naming that app resolves through.
+     */
+    recordModelApps(apps: Record<string, string>): Promise<{
+        recorded: number;
+    }>;
     /** Renames (and re-settings) the CURRENT workspace — the endpoint reads the
      *  target from the request's workspace, never a path id. */
     updateWorkspace(body: {
@@ -1060,6 +1128,8 @@ export declare class LoticsClient {
             label?: string;
             fields?: Record<string, string>;
         }>;
+        /** The copier's own account each connection alias pushes through, by `cac_` id. */
+        connections?: Record<string, string>;
     }): Promise<{
         /** Each app's deploy, in contract order. `error` set and `deployed` null when one did not land. */
         apps: Array<{
@@ -1107,6 +1177,7 @@ export declare class LoticsClient {
      *  promises, snapshotting the broken contract as a new version. */
     opts?: {
         acknowledge_breaking_api_change?: boolean;
+        connections?: Record<string, string>;
     }): Promise<AppUpgradeResult>;
     /**
      * Capture live records from this workspace as a starter's sample data.

package/dist/src/client.js

@@ -447,6 +447,14 @@ var LoticsClient = class {
   async recordModelDocuments(documents) {
     return this.request("PUT", "/v1/workspaces/model/binding/documents", { documents });
   }
+  /**
+   * Record which app each of a plan's app aliases became — stated by the create
+   * that made it, since an app row is made from a name and the alias is the
+   * author's file. What a sibling act naming that app resolves through.
+   */
+  async recordModelApps(apps) {
+    return this.request("PUT", "/v1/workspaces/model/binding/apps", { apps });
+  }
   /** Renames (and re-settings) the CURRENT workspace — the endpoint reads the
    *  target from the request's workspace, never a path id. */
   async updateWorkspace(body) {
@@ -594,11 +602,10 @@ var LoticsClient = class {
    * refusals, both before any write. Admin-only.
    */
   async upgradeApp(app_id, opts = {}) {
-    return this.request(
-      "POST",
-      `/v1/apps/${encodeURIComponent(app_id)}/upgrade`,
-      opts.acknowledge_breaking_api_change ? { acknowledge_breaking_api_change: true } : {}
-    );
+    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/upgrade`, {
+      ...opts.acknowledge_breaking_api_change ? { acknowledge_breaking_api_change: true } : {},
+      ...opts.connections === void 0 ? {} : { connections: opts.connections }
+    });
   }
   /**
    * Capture live records from this workspace as a starter's sample data.

package/docs/building_an_app.md

@@ -13,30 +13,43 @@ using one to find out whether something works is the slowest possible way to lea
 ## 1 — Scaffold, or pull what exists
 
 ```
+lotics app preview model.json#<app> --shots shots/   # the plan rendered over its rows: no workspace
 lotics app create "<name>"          # new: a real Vite + React + TS project, deps installed
-lotics app create "<name>" --from model.json#<app>   # new, from a checked plan: one screen per entry
+lotics app create "<name>" --from model.json#<app>   # new, from a checked plan: app.json, rendered
 lotics app create "<name>" --api    # new, no screens: its declarations are the whole surface
-cd <dir> && lotics app regenerate   # existing + generated: fold a later generation into it
+cd <dir> && lotics app regenerate   # existing + generated: rewrite its spec from the plan
 cd <dir> && lotics app pull <app_id>   # existing: refresh to the latest first, then read its README
 lotics workspace build model.json      # the whole plan: check, apply, then every app in it
 ```
 
-`lotics workspace build` is the four lines above in one, for a model that declares several apps:
-`scaffold check`, `scaffold apply` where this workspace differs from the model, then per app
-`create --from` into `<dir-of-model>/<alias-with-dashes>` when that directory does not exist and
-`regenerate` there when it does, then `app check` — and `app deploy` under `--deploy`. An app that
-conflicts or checks red is named and the rest still run, because the one you are going to fix is
-not a reason to leave the others in a state nobody knows. `--dry-run` writes nothing and says which
-apps it would create and which it would regenerate.
-
-`--from` takes the model file `lotics scaffold check` approved and the app in it, and scaffolds
-each screen as the registry shape over the live table its entity became — a `LifecycleDesk`, a
-`PartyRegister`, … from `@lotics/ui`, its slots reading the fields the plan bound. The tables
+`lotics workspace build` is the create and regenerate lines above in one, for a model that
+declares several apps: `scaffold check`, `scaffold apply` where this workspace differs from the
+model or the model declares a table automation, then per app `create --from` into
+`<dir-of-model>/<alias-with-dashes>` when that directory does not exist and `regenerate` there when
+it does, then `app check` — and `app deploy` under `--deploy`. Each app is built after every sibling
+it names that the run creates, since a hand-off is written off the app its alias became; otherwise
+in the model's order. Two apps that name each other cannot both go second, so the one built first
+is built again once the other exists, and a hand-off binds on the first run. An app that conflicts or checks
+red is named and the rest still run, because the one you are going to fix is not a reason to leave
+the others in a state nobody knows. `--dry-run` writes nothing and says which apps it would create
+and which it would regenerate.
+
+**Look at the plan before anything exists.** `lotics app preview <model.json>#<app>` binds the app
+against the model's own ids, answers every read from the model's `rows`, renders every screen and
+record at 1280 and 375, and runs the probes `app check --screens` runs — no workspace, no
+credential, nothing created. `--shots <dir>` writes what it measured as PNGs. What a clause of the
+plan draws is `lotics docs clauses`; the preview is how you see it drawn over your own rows.
+
+`--from` takes the model file `lotics scaffold check` approved and the app in it, and writes
+**`app.json`** — the bound plan: its one register with the shape and slots, the record each row
+opens, the create panels and the acts, addressing the live `tbl_`/`fld_`/`opt_` ids its entities
+became — beside a five-line `src/main.tsx` that mounts `@lotics/app-runtime` over it, one
+`src/workflows/<alias>.ts` per write and an empty `src/components/index.ts`. The runtime draws the
+spec; there is no screen source to edit (`node_modules/@lotics/app-runtime/AGENTS.md`). The tables
 have to exist (`lotics scaffold apply` first); a table or field the workspace lacks is refused by
-name. A `custom` screen arrives as a register of the cells its roles name, cut to what still reads
-at a phone's width — its slot list is a checklist of what the rows know, never a layout. The
-project's `README.md` is the plan in prose: the app, its screens with their routes and shapes, and
-the tables behind them.
+name. The app is recorded against its plan alias, so a second `--from` for the same alias is
+refused and a sibling's hand-off to it opens this app. The project's `README.md` is the plan in
+prose: the app, its register and record, and the tables behind them.
 
 `--api` scaffolds the app something OUTSIDE Lotics calls (§ 9): the manifest, `src/workflows/`, a
 CI job and the two briefs, with no `index.html`, no `src/App.tsx`, no Vite config and no kit. Its
@@ -56,14 +69,13 @@ arrives fully editable rather than as an archive you have to reconstruct.
 
 **The plan changes after the app is built, and `lotics app regenerate` is how it lands.** Run it
 inside the app; the plan is the one `package.json#lotics.plan` remembers, unless `--from` names
-another. Each generation leaves a copy of what it wrote under `.lotics/generated/`, so the next one
-is a three-way merge: a generated file you have not touched is overwritten, one you have edited
-keeps your edit and takes the generator's, and a clash writes conflict markers, names the file and
-ends non-zero once every other file is folded. A file you wrote yourself is never touched; one the
-generator retired goes only if you left it alone. Every file it leaves as yours is named with
-the reason, so the next author can tell a hand dialog from a generated one. The manifest is reconciled
-by the same rule — the generator's aliases are replaced, retired ones removed, yours kept — then
-codegen and `app check` run.
+another. The generator owns what it emits: `app.json` is derived from the plan and rewritten
+whole, and a workflow body is rewritten too, with the text it replaced parked in
+`.lotics/regenerate-dropped.patch`. `src/components/` is the one exception — seeded where it is
+absent, never rewritten — because it is the hatch: `lotics app eject <screen|section|act>` hands
+ONE part of the spec to a component there, and a regeneration carries that hand-over onto the new
+spec. The manifest is reconciled by ownership — the generator's aliases replaced, the ones it
+retired removed, the ones you added kept — then codegen and `app check` run.
 
 **Nothing is pushed.** What the live app RUNS changes at `lotics app deploy` and nowhere else: the
 bundle production serves was built against the bindings it has, so a regeneration that replaced a
@@ -71,9 +83,7 @@ live workflow body left a deployed dialog posting inputs that workflow no longer
 summary names what a deploy will add, change and leave bound instead. `--bind-new` binds the
 aliases the app does not have YET — `lotics app dev` forwards queries to production, so a new alias
 cannot be tried before something binds it — and refuses, naming them, to touch one that already
-exists. `--dry-run` prints the whole fold and writes nothing. The alternative
-is diffing two trees by hand and re-applying every edit, which is where generated apps stop being
-regenerated.
+exists. `--dry-run` prints the whole run and writes nothing.
 
 ## 2 — Clarify what is being asked, before modelling it
 
@@ -263,35 +273,39 @@ Authoring rules for the body itself: `lotics docs workflows`.
 
 ## 7 — Screens
 
-**Before any JSX**, read `lotics docs ui` — the catalog and the composition grammar. A screen the
-plan named is a registry shape, and the shape is a kit component (`@lotics/ui/lifecycle_desk`,
-`@lotics/ui/party_register`, …) that owns the strip, the columns, the fit at a phone's width and
-the record's door: give it the rows and the slots, and swap a slot's device through its `render`
-rather than rebuilding the frame. For a screen no shape covers, the kit's `examples/` are whole
-screens as source; if the pattern is genuinely missing, build it as a kit component rather than
-a local one-off, or the next screen re-derives it differently.
-
-**The record half is the same deal.** A screen is `[tabs] + list → record`, and the record is one
-frame too: `@lotics/ui/record_page` over the section bodies the record's field roles decide. Which
-roles become which sections is `lotics scaffold docs` § Apps and screens; which component each
-section kind names is `node_modules/@lotics/ui/docs/templates.md` § The record. A drawer and a page
-draw the same list of sections; `lotics scaffold check` prints it per screen, and `--from` emits it.
-A section's ADD act rides its heading row, never inside its body.
-
-**A screen no shape fits** is declared in the plan as `"shape": "custom"` with its slots as roles
-(`lotics scaffold docs` § Apps and screens) — never a shape bent to fit — and built from the kit
-like any other. Then file `lotics report` with `wanted` opening `shape <name>`: a custom slot set
-that recurs becomes a shape, and the report is how the next build gets it.
-
-Two rules that cause most of the rework:
+**A plan-built app's screens are its `app.json`, and `@lotics/app-runtime` draws them.** The
+register, the record each row opens, its sections, the creates and the acts are all stated by the
+plan, so a correction is a change to the PLAN followed by `lotics app regenerate` — or, where the
+ruling is about how every app draws, a change to the runtime that reaches every app on its next
+install. Every row the runtime draws — a register's subject, a list item, a card, a record's stop, a
+log entry — is one anatomy read off the plan's roles (`node_modules/@lotics/app-runtime/AGENTS.md`),
+and how a register is laid out is the screen's `presentation` clause. `lotics scaffold check`
+prints what each screen will draw, with every value the plan left to the runtime marked
+`(default)`, so the printout is where a screen is reviewed before one exists; `lotics app preview`
+is where it is looked at.
+
+**Where the plan has no word for a screen, a section or an act,** the spec names one of the app's
+own components — `lotics app eject` writes it from exactly what the runtime was drawing, one part at
+a time, and `lotics docs components` says what it is handed. A screen no shape fits is declared in
+the plan as `"shape": "custom"` with its slots as roles (`lotics scaffold docs` § Apps and screens)
+— never a shape bent to fit — and then `lotics report` with `wanted` opening `shape <name>`: a custom
+slot set that recurs becomes a shape, and the report is how the next build gets it. A component
+the kit lacks is built into the kit, never hand-rolled in one app.
+
+**A hand-written app composes the kit itself.** Before any JSX, read `lotics docs ui` — the catalog
+and the composition grammar; the shape components (`@lotics/ui/lifecycle_desk`,
+`@lotics/ui/party_register`, …) and `@lotics/ui/record_page` own the strip, the columns, the fit at
+a phone's width and the record's door, so give them rows and slots rather than rebuilding a frame.
+
+Two rules for any code the app writes itself — a component or a hand-written screen:
 
 - **Never copy server data into `useState`.** Derive from `useQuery` / `useWorkflow` with
   `useMemo`; a copy goes stale the moment anything else writes.
 - **Design the loading, empty and error states.** Reserve their space so the layout does not jump.
 
-**The kit is a strong recommendation, not a requirement.** `@lotics/app-sdk` is data and RPC only —
-its peers are `react`, `react-dom` and `react-router`, nothing else — so an app can be plain DOM
-React with your own CSS and still use every hook, deploy the same way, and run the same server-side.
+**The kit is a strong recommendation, not a requirement.** `@lotics/app-runtime/sdk` is data and
+RPC only — its peers are `react`, `react-dom` and `react-router` — so an app can be plain DOM React
+with your own CSS and still use every hook, deploy the same way, and run the same server-side.
 What the scaffold buys you is the part that is hard to get right by hand: a screen that looks
 deliberate, states that are already designed, and behaviour that matches the rest of the product.
 Building without it means owning all of that, so reach for it unless you have a specific reason not
@@ -407,8 +421,9 @@ brief travels with the app rather than living in whoever built it.
 Once scaffolded, everything below happens locally:
 
 ```
-edit src/workflows/<alias>.ts        # or a screen, or a query
-lotics app regenerate --dry-run      # when the PLAN moved: what the new generation would do
+edit src/workflows/<alias>.ts        # or a component, or a query
+lotics app preview model.json#<app> --shots shots/   # when the PLAN moved: see it before a table does
+lotics app regenerate --dry-run      # then: what the new generation would do to this app
 lotics app codegen                   # after any schema change
 npm run typecheck                    # honest, because codegen is current
 lotics run run_app_workflow '{"app_id":…,"alias":…}'   # prove the mutation path
@@ -419,14 +434,20 @@ lotics app workflow set <alias>      # push the body; the server verifies
 lotics app deploy -m "…"             # pushes pending bindings, then ships
 ```
 
-**Proving a change to `@lotics/ui` or `@lotics/app-sdk` before it is published** is
-`lotics app kit <path-to-that-package-in-your-checkout>`: it builds the package, packs it into this
-app's `.lotics/kit/`, installs it by file specifier and hashes one built file on both sides to
-prove the install took — a repack under the same name is otherwise served from the lockfile's first
-tarball, and every other signal reads as success. `app check` then says the app depends on a build
-that exists on one machine, and `app deploy` refuses it (the tarball is not in the source archive,
-so a clone could not install) unless you pass `--allow-local-kit`. `lotics app kit <path>
---published` puts the registry version back.
+**An app lists `@lotics/app-runtime` and nothing else of ours** — its SDK is every app's data
+layer, and it depends on the kit it draws with. Where the app's own code imports the kit, it lists
+`@lotics/ui` at **the runtime's range**, never its own; `lotics app kit` keeps the two in step.
+**Proving a change to the runtime before it is published** is
+`lotics app kit <path-to-packages/app-runtime>`: it builds the runtime, packs it into this app's
+`.lotics/kit/`, installs it by file specifier and hashes one built file on both sides to prove the
+install took — a repack under the same name is otherwise served from the lockfile's first tarball,
+and every other signal reads as success. `app check` then says the app depends on a build that
+exists on one machine, and `app deploy` refuses it (the tarball is not in the source archive, so a
+clone could not install) unless you pass `--allow-local-kit`. `lotics app kit --published` puts
+back the range the app listed before the first checkout — an app with none recorded moves to the
+registry version — and migrates an app still on `@lotics/app-sdk`, the package the SDK was before
+it moved into the runtime (`lotics docs migration`). A kit change reaches an app through the runtime that depends on
+it; `LOTICS_UI_SRC` links the kit's source into `lotics app dev`.
 
 A deploy pushes any workflow body, agent prose or query that is ahead of the app **before** it
 ships the bundle, so a forgotten `set` cannot ship a bundle typed against a binding that does not

package/docs/clauses.md

@@ -0,0 +1,128 @@
+# Plan clauses
+
+Every clause an app in a model's `apps` can state, what it draws, and an example
+value. `[]` is every element of a list or a map; `as` is one form a key takes.
+Each clause's rules are `lotics scaffold docs` § Apps and screens.
+
+`lotics app preview <model.json>#<app> --shots <dir>` renders an app stating any
+of them, over the rows of your own model, before a table exists.
+
+## On the app
+
+| Clause | Draws | Example |
+|---|---|---|
+| `alias` | Stable app alias, unique within the contract | `"vans"` |
+| `name` | What the app is called wherever its members open it | `"Vans"` |
+| `description` | What the app is for, in a sentence shown beside its name | `"What is on the shelf, against what has to be."` |
+| `icon` | A Lucide icon name, kebab-case | `"users"` |
+| `theme` | The app's colour | `{"color":"sky"}` |
+| `theme.color` | Theme color for the app | `"sky"` |
+| `scope` | Narrow every read of this app to one row of an entity, the pick shared with every app that names it | `{"entity":"order","param":"order_id"}` |
+| `reads` | "shared": this app's queries and writes carry no entity's read_scope — whoever the app is shared with reads and writes every row it draws. Absent, each read_scope binds the viewer. | `"shared"` |
+
+## On its screen
+
+| Clause | Draws | Example |
+|---|---|---|
+| `alias` | Stable screen alias, unique within the app | `"vans"` |
+| `label` | What the screen is called in the app | `"Vans"` |
+| `shape` | A shape, or "custom" with its own `roles` | `"custom"` |
+| `entity` | The entity whose rows this screen is over | `"van"` |
+| `record` | How one record opens from the list — "drawer", "page", or "expand" to reveal it in the row; absent, the shape decides | `"page"` |
+| `tabs` | The entity's lifecycle select, whose stages are the tab strip; null for none; absent, the shape decides. Any other select is a `filters` entry — except on a shape whose strip means something of its own (a reconciliation's runs, a trend's series, a worksheet's versions), which takes any select | `"run"` |
+| `slots` | Slot → the field that fills it, where roles alone cannot decide; null leaves an optional slot unbound | `{"contact":"phone"}` |
+| `slots[] as list of alias (at least 2)` | The tiers this slot folds by, outermost first — or the measures one level column stacks, each against its own limit | `["load","cube"]` |
+| `slots[] as Quick slot` | The field AND the reader's own control for it, drawn as the column | `{"field":"hours","quick":true}` |
+| `slots[].order` | A lifecycle whose stages are a WALK: the cell advances to the next one rather than offering them all | `"sequence"` |
+| `roles` | For "custom" only: slot → the role that fills it | `{"identity":"identity","scan":"mark","filed":"when"}` |
+| `columns` | Extra fields drawn after the slots, in this order — at most 4, each holding ONE value; never a files field, and never a field a slot already draws. `{"field", "age", "more"}` draws a lookup of a related row's category as that category's chip | `["headroom"]` |
+| `columns[] as Chip column` | A related row's category drawn as ONE chip, with how long ago it was and how many others stand behind it | `{"field":"latest_kind","age":"latest_seen","more":"enquiry_count"}` |
+| `columns[].age` | A date of this entity dating the row the chip's ordered lookup picks — a `latest`/`earliest` rollup of the order's date, or a lookup ordered the same way — drawn after the chip as how long ago it was | `"latest_seen"` |
+| `columns[].more` | A count rollup of this entity over the SAME link — drawn beside the chip as how many OTHER rows there are | `"enquiry_count"` |
+| `sources` | Other entities whose rows this register reads beside its own, in ONE read sorted by its order — each declares a field for every role the register's slots draw and, under the same alias, every other field it draws, orders or narrows by; a row opens in its own entity's record, and the create and row acts are this screen's entity's | `["consigned_item"]` |
+| `create` | The fields a new row is asked for, in this order — at most 12, each a field of this entity a draft can ask for, and every field the row cannot be written without among them; absent, the draft asks for every field a person states | `["name","company","page","phone"]` |
+| `writes` | false makes this screen's record read-only — no field editor, no stage advance; "children" draws the record at rest and leaves the rows it owns operable; "record" leaves the record operable and draws the rows it owns at rest; absent, both are operable | `false` |
+| `acts` | The papers this register makes — from one row, from a ticked set, and from the whole view | `{"row":[{"kind":"agent","label":"Find the contact","agent":"contact_finder","fills":["phone","email"]}],"expo…` |
+| `acts.row` | The acts in every row's ⋯ menu, in this order | `[{"kind":"sibling","label":"Open the order","app":"orders","record":"order"}]` |
+| `acts.row[] as Agent act` | A run of an app agent over the row, whose proposed values the reader reviews before one write Also `acts.record[] as Agent act`, `acts.selection[] as Agent act`, `section_acts[][] as Agent act`. | `{"kind":"agent","label":"Find the contact","agent":"contact_finder","fills":["phone","email"]}` |
+| `acts.row[].place` | Draw this act ON the row rather than in its ⋯ menu — at most one per screen | `"cta"` |
+| `acts.row[].when` | Offer this act only while the row stands at one of these stages | `{"field":"state","in":["ready"]}` |
+| `acts.row[].needs` | Fields of this entity — the act is offered only while at least one of them holds a value | `["name"]` |
+| `acts.row[].confirm` | Ask before this act runs, with its own label as the commit word — for a press that cannot be taken back | `true` |
+| `acts.row[] as Workflow act` | The row handed to a workflow the app binds, run on the press Also `acts.record[] as Workflow act`, `acts.selection[] as Workflow act`, `section_acts[][] as Workflow act`. | `{"kind":"workflow","label":"Hand to despatch","workflow":"hand_to_despatch","inputs":{"order_id":"record"},"w…` |
+| `acts.row[].asks` | What the reader states in the act's panel before it runs: the workflow's own input name → the field whose editor asks it | `{"owner":"owner"}` |
+| `acts.row[].moves` | The stage of this entity's lifecycle the body lands the row at — the act's alone: no stage picker, ladder or board of this app moves a row there | `"converted"` |
+| `acts.row[] as Sibling act` | A record of this row opened in a sibling app of this plan, in place Also `acts.record[] as Sibling act`, `acts.selection[] as Sibling act`, `section_acts[][] as Sibling act`. | `{"kind":"sibling","label":"Open the order","app":"orders","record":"order"}` |
+| `acts.row[] as Recording act` | A call, a visit, a walk-through recorded onto the row and filed through a workflow once transcribed Also `acts.record[] as Recording act`, `acts.selection[] as Recording act`, `section_acts[][] as Recording act`. | `{"kind":"recording","label":"Record a call","workflow":"log_call","inputs":{"prospect_id":"record"}}` |
+| `acts.row[] as Paper act` | A paper made from a template this model declares — from the row, or from every ticked row at once Also `acts.record[] as Paper act`, `acts.selection[] as Paper act`, `section_acts[][] as Paper act`. | `{"label":"Chase the papers","template":"chaser"}` |
+| `acts.record` | The acts in the RECORD's own header menu, in this order — the same reach as a row's, with the work open | `[{"label":"Print the order file","template":"order_file"}]` |
+| `acts.selection` | The acts over the TICKED rows — each a `template`, generating ONE document over the set | `[{"label":"Remittance advice","template":"remittance"}]` |
+| `acts.export` | Save the rows in view — true for a workbook of the drawn columns, or a template this model declares | `true` |
+| `acts.export as Export template` | The rows in view as a paper laid out by the trade's own template | `{"template":"customer_book"}` |
+| `acts.import` | Turn a file into rows — mapped, validated per row, previewed, then upserted by the entity's natural key | `{"kind":"import","label":"Import the statement","entity":"payment","key":"reference","columns":["date","amoun…` |
+| `acts.import.columns` | The fields the file may fill, in this order — absent, every field a person states | `["date","amount","direction","state"]` |
+| `section_acts` | Acts on the RECORD's own sections, keyed by the alias each section is derived from — a field alias (its progress, its prose, its set, its charge, its files) or a child entity's alias (its register, its desk, its run, its log) | `{"document":[{"label":"Chase the papers","template":"chaser"}]}` |
+| `sections` | How a section of the RECORD is DRAWN, keyed by the child entity alias its register is derived from — or `{"heading": …}`, `{"facts": […]}` or both alone to rename any section of the rows it owns or head it with the record's facts | `{"order_line":{"draw":"worksheet","cost":"line_cost","sell":"line_total"}}` |
+| `sections[] as Worksheet section` | Priced lines the reader works down in place, each part footed and the sheet closing under them | `{"draw":"worksheet","cost":"line_cost","sell":"line_total"}` |
+| `sections[].heading` | What this section is headed on the record; absent, the child entity's own label | `"Touches"` |
+| `sections[].facts` | Fields of THIS record drawn at the head of the section, above its rows — filed here, and so in no band of the record's facts | `["outstanding"]` |
+| `sections[].cost` | The child's field holding what a line COSTS — the base the margin is taken against | `"line_cost"` |
+| `sections[].sell` | The child's field holding what it SELLS for — the figure the sheet is read for | `"line_total"` |
+| `sections[] as Ledger section` | A book of movements — closes on its total, read against the record's rollup that sums it | `{"draw":"ledger","facts":["outstanding"]}` |
+| `sections[] as Itinerary section` | A run of stops read a day at a time — stated to place the child's fields on the stop where the roles' placement is not the reading | `{"draw":"itinerary","lines":[["window","fitting_hours","buyer"],["line_total"]],"badge":"status"}` |
+| `sections[].name` | The child's field that NAMES the entry and leads it; absent, its `identity` | `"subject"` |
+| `sections[].words` | The child's text field the entry SAYS; absent, its `body`, else (on a log) its first markdown text | `"words"` |
+| `sections[].lines` | The entry's supporting lines, at most 2, each the child's fields it reads in order, at most 4; absent, a log reads its selects, the parties it was with and the address it reached them at, and a stop reads its slot and its party, with its amount on a second line | `[["with_party"]]` |
+| `sections[].badge` | The child's select drawn as the entry's status at the right — a lifecycle or a category; absent, a stop's lifecycle, and nothing on a log | `"status"` |
+| `sections[].figure` | The child's number worn at the trailing end of the entry's head; absent, a log's amount, and nothing on a stop | `"hours_open"` |
+| `sections[].evidence` | The child's fields drawn under the words as what the entry shows, a playable file played; absent, its `recording` | `["photos"]` |
+| `sections[].detail` | The child's fields kept behind one fold under the words; absent, its `verbatim` | `["desk_note"]` |
+| `sections[] as Claim section` | Lines claimed against a priced schedule, one period at a time — the contract, before, now, to date and what is left | `{"draw":"claim","quantity":"now","contract":"contract_qty","price":"price","previous":"before","unit":"unit",…` |
+| `sections[].unit` | The child's field naming what the line is counted in | `"unit"` |
+| `sections[].retention` | A percentage field of THIS record — the share held back from what is claimed | `"retention"` |
+| `sections[] as Tree section` | The rows nested under each other, each money figure summed up the tree | `{"draw":"tree","nest":"part_of"}` |
+| `sections[] as Gantt section` | The rows as bars across the calendar — from each row's `when`, for the days its measure counts | `{"draw":"gantt","until":"finishes","nest":"part_of","depends_on":"after","baseline":{"start":"planned_start",…` |
+| `sections[].until` | The child's date field each bar is drawn TO; absent, a bar runs for the days its measure counts | `"finishes"` |
+| `sections[].nest` | The child's one-row link to its own entity — folds a row's bars under the row it sits under | `"part_of"` |
+| `sections[].depends_on` | The child's link to its own entity naming the rows that must finish before a row starts | `"after"` |
+| `sections[].baseline` | The child's date fields each row was PLANNED to start and end on, drawn under its bar | `{"start":"planned_start","end":"planned_end"}` |
+| `sections[] as Curve section` | Two figures of the rows, each added up to date along the rows' `when` and drawn as two lines | `{"draw":"curve","planned":"planned_value","actual":"earned_value"}` |
+| `sections[] as Log section` | Dated entries read in the words each states — stated to place the child's fields on the entry where the roles' placement is not the reading | `{"draw":"log","name":"subject","words":"message","evidence":["photos"],"detail":["desk_note"],"lines":[["with…` |
+| `sections[] as Publish section` | One row per destination this record stands on — the strip, the preview, and the press that sends them | `{"draw":"publish","states":{"queued":"queued","published":"out","failed":"refused","by_hand":"by_hand"},"text…` |
+| `sections[].text` | A plain text on the child — what this one destination goes out with instead of the body | `"wording"` |
+| `sections[].permalink` | A link-formatted text on the child — where the post landed | `"address"` |
+| `sections[].error` | A text on the child holding the platform's own refusal | `"fault"` |
+| `sections[].link` | A link-formatted text of THIS entity — the address the post carries as its card | `"source"` |
+| `sections[].when` | Offer the desk's Publish only while THIS record stands at one of these stages | `{"field":"state","in":["ready"]}` |
+| `sections[] as Acts section` | Acts waiting for a person — the words, where to reach them, and the sheet that records what came of it | `{"draw":"acts","heading":"Next steps","states":{"queued":"waiting","done":"done","skipped":"passed"},"verb":"…` |
+| `sections[].why` | A text on the child — why this is worth doing now | `"why_now"` |
+| `sections[].reason` | A text or a single select on the child — why it was passed over | `"pass_reason"` |
+| `sections[].reach` | Verb option → where that act is done; a verb this map leaves out is done wherever the reader already is | `{"reply":{"at":"enquiry.source","by":"link"},"message":{"at":"page","by":"link"},"call":{"at":"phone","by":"p…` |
+| `sections[].withhold` | A yes/no of THIS entity — while it reads yes, no act reaches out, and the reach verb says why | `"quiet"` |
+| `sections[].cta` | The register's row wears this record's NEXT waiting act as its verb — the one press that reaches the person | `true` |
+| `sections[] as Section heading` | Rename a section of the rows this record owns, or head it with the record's facts that frame them, however the roles draw it | `{"heading":"Touches"}` |
+| `children` | The child entities whose rows the RECORD draws in this app, in this order — only these; absent, every one its links derive | `["works_task","claim_line"]` |
+| `filters` | The chips beside the search — a single-select or select_member field's alias, `{"field": …, "default": "mine"}` to open a member field on the reader's own rows, or a lens this model states as predicates over the entity's fields | `["kind"]` |
+| `filters[] as Lens` | A lens the MODEL states as predicates over the entity's fields, where no select holds the answer | `{"label":"Shelf","predicates":[{"label":"Empty","tone":"rose","where":{"node_type":"group","logic":"and","chi…` |
+| `filters[].sort` | The order the rows are read in while the lens is on | `{"field":"next_due","order":"asc"}` |
+| `filters[].sort.order` | "asc" (the default) puts the soonest or smallest first; a row holding none goes last | `"asc"` |
+| `filters[] as Member lens` | A member field's lens, opened on the reader's own rows | `{"field":"handled_by","default":"mine"}` |
+| `facts` | How the record's facts are BANDED — where the aside's fields group under captions | `{"groups":[{"caption":"The movement","fields":["date","direction"]},{"caption":"Where it was banked","fields"…` |
+| `summary` | What the rows in view come to, stated before or after their names | `{"above":"counts"}` |
+| `summary.totals` | Number fields the whole view adds up — under the column that draws one, else in a band beneath the register | `["lines"]` |
+| `summary.above` | A band of figures over the register: "counts" for how many rows and how many need attention, or number fields — each added up over the window, or `{"field": …, "at": "end"}` for a stock STANDING at its end | `"counts"` |
+| `summary.above[] as Stock` | A stock standing at the end of the window, beside the sums over it | `{"field":"in_yard","at":"end"}` |
+| `summary.ageing` | How old the money over this register is — the amount split by how many days past its date each row is | `{"amount":"outstanding","due":"due_date","buckets":[14,30,60]}` |
+| `summary.ageing.buckets` | The bucket edges, in days past due, ascending — absent, 30, 60, 90 | `[14,30,60]` |
+| `summary.trend` | Which way this figure moved across the window the reader is reading — needs a `period` to be a window of | `{"field":"amount","direction":"up"}` |
+| `summary.curve` | Planned against actual, each added up to date over the rows' dates and drawn as two lines — read along the `period`, else the `when` | `{"planned":"planned_value","actual":"earned_value"}` |
+| `period` | A date field on the entity the reader narrows the view by; absent, the view is every row | `"day"` |
+| `presentation` | How this screen and the record it opens are DRAWN, where the shape's own answer is not the one wanted | `{"lead":"none"}` |
+| `presentation.lead` | What each row leads with; absent, what the shape's rows are decides | `"none"` |
+| `presentation.density` | How many lines a row's subject may take; absent, what the shape's rows are decides | `"dense"` |
+| `presentation.layout` | How the rows are arranged; absent, a table | `"gantt"` |
+| `presentation.line` | The register row's supporting line, in this order — at most 2 fields of this entity, each a plain text or a single select; absent, the key the row is filed under | `["company","role"]` |
+| `presentation.until` | For a gantt: the date field each bar is drawn TO; absent, the bar runs for the days its measure counts | `"due_back"` |
+| `presentation.nest` | A one-row link from this entity to itself — the row each row sits under; affords `layout: "tree"` and nests a gantt's bars | `"part_of"` |
+| `presentation.depends_on` | For a gantt: a link from this entity to itself naming the rows that must finish before a row starts | `"after"` |
+| `presentation.baseline` | For a gantt: the date fields the row was PLANNED to start and end on, drawn under its bar | `{"start":"planned_start","end":"planned_end"}` |