zinkee 0.1.24 → 0.1.26

package/.claude/settings.local.json

@@ -43,7 +43,14 @@
       "Bash(git -C /home/guillermo/dev/cli branch --show-current)",
       "Bash(git -C /home/guillermo/dev/cli diff --stat)",
       "Bash(git fetch *)",
-      "Bash(pnpm exec *)"
+      "Bash(pnpm exec *)",
+      "Bash(echo \"=== exit $? \\(grep\\) ===\")",
+      "Bash(grep -rn \"resourceType\" src/)",
+      "Bash(grep -rn \"automation-folders/\\\\${\\\\|/automations:move\\\\|{folderId}/automations\" src/)",
+      "Bash(grep -rn \"navigation resources move.*--type\\\\|resourceType\" docs/ README.md)",
+      "Bash(zinkee --version)",
+      "Bash(zinkee --json profiles list)",
+      "Bash(zinkee displays *)"
     ]
   }
 }

package/README.md

@@ -338,7 +338,7 @@ zinkee --json logs list <schema-slug> <record-uuid>
 
 ## Navigation
 
-Organize schemas into database folders.
+Organize schemas into database folders. The navigation menu holds databases, so only schemas can be moved here.
 
 ```bash
 # List folders with contents
@@ -348,13 +348,16 @@ zinkee --json navigation folders list
 zinkee navigation folders create --name "CRM" --order 1
 
 # Move a schema into a folder
-zinkee navigation resources move <schema-uuid> --type SCHEMA --to "CRM"
+zinkee navigation resources move <schema-uuid> --to "CRM"
 
-# Delete folder (resources move back to root silently)
+# Move a schema back to the workspace root
+zinkee navigation resources move <schema-uuid> --to 00000000-0000-0000-0000-000000000000
+
+# Delete folder (schemas move back to root silently)
 zinkee navigation folders delete "CRM"
 ```
 
-Root folder cannot be deleted.
+Only schemas can be moved (schedules and sub-schemas follow their parent schema). Root folder cannot be deleted; its UUID is always `00000000-0000-0000-0000-000000000000`.
 
 ---
 
@@ -388,6 +391,27 @@ zinkee teamspace resources publish projects --to "Other Folder"
 
 Displays are dashboards composed of widgets that visualize data from schemas.
 
+### Display folders
+
+Organize displays into folders in the displays menu. Folders are flat (name only) and only displays can be moved into them.
+
+```bash
+# List display folders (non-root folders plus the root bucket)
+zinkee --json displays folders list
+
+# Create a folder
+zinkee displays folders create --name "Executive Dashboards"
+
+# Rename a folder
+zinkee displays folders update "Executive Dashboards" --name "Executive Dashboards (2026)"
+
+# Move a display into a folder
+zinkee displays folders move <display-uuid> --to "Executive Dashboards"
+
+# Delete a folder (its displays move back to the root folder)
+zinkee displays folders delete "Executive Dashboards"
+```
+
 ### Creation flow
 
 1. Create the display
@@ -462,9 +486,51 @@ zinkee --json displays widgets create <display-uuid> \
     "chart":{"yAxisSeries":[{"typeCalc":"SUM","fieldCalc":"hours-field-slug","axisType":"PRIMARY"}]}
   }'
 
-# KANBAN, TIMELINE, DETAIL also supported
+# KANBAN widget (field mapping lives in view.viewAdditionalProperties.viewState)
+zinkee --json displays widgets create <display-uuid> \
+  --type KANBAN \
+  --name "Status board" \
+  --origin-resource <schema-uuid> \
+  --field <name-field-uuid> --field <status-field-uuid> --field <amount-field-uuid> \
+  --column-field <status-field-uuid> \
+  --swimlane-field <owner-field-uuid> \
+  --card-title-field <name-field-uuid> \
+  --card-category1-field <status-field-uuid> \
+  --aggregation-method sum --aggregation-field <amount-field-uuid> \
+  --view-state '{"showNoValueColumn":true,"showNoValueSwimlane":true}'
+
+# TIMELINE widget (cardConfig uses category1/category2/category4, no category3)
+zinkee --json displays widgets create <display-uuid> \
+  --type TIMELINE \
+  --name "Customer schedule" \
+  --origin-resource <schema-uuid> \
+  --field <name-field-uuid> --field <start-field-uuid> --field <end-field-uuid> \
+  --start-date-field <start-field-uuid> \
+  --end-date-field <end-field-uuid> \
+  --label-field <name-field-uuid> \
+  --card-title-field <name-field-uuid> \
+  --view-state '{"granularity":"month","sidebarWidth":300}'
+
+# HIERARCHY widget (columns + root level + repeatable child levels)
+zinkee --json displays widgets create <display-uuid> \
+  --type HIERARCHY \
+  --name "Org tree" \
+  --origin-resource <schema-uuid> \
+  --field <name-field-uuid> --field <status-field-uuid> --field <amount-field-uuid> \
+  --hierarchy-label "Name" \
+  --hierarchy-info "col_1779975207355_zfndknslw:Status" \
+  --hierarchy-number "col_1779975261490_h8kd3nv9ws:Total amount:SUM" \
+  --hierarchy-root-name "Customers" \
+  --hierarchy-root-label-field <name-field-uuid> \
+  --hierarchy-root-info "col_1779975207355_zfndknslw:<status-field-uuid>" \
+  --hierarchy-root-number "col_1779975261490_h8kd3nv9ws:<amount-field-uuid>" \
+  --hierarchy-child '{"name":"Projects","schemaId":"<projects-schema-uuid>","childFieldId":"<project-customer-field-uuid>","labelFieldId":"<project-name-field-uuid>","infoMappings":[],"numberMappings":[{"columnId":"col_1779975261490_h8kd3nv9ws","fieldId":"<project-amount-field-uuid>"}]}'
 ```
 
+For KANBAN/TIMELINE, `cardConfig` differs by type: KANBAN exposes `category1Field`/`category2Field`/`category3Field` (`--card-category1-field`…`--card-category3-field`), TIMELINE exposes `category1Field`/`category2Field`/`category4Field` (`--card-category4-field`). UI-state scalars (`columnOrder`, `hiddenColumns`, `collapsedColumns`, `hideEmptyColumns`, `showNoValueColumn`, `showNoValueSwimlane`, `granularity`, `sidebarWidth`, `visibleFields`, `collapsedGroups`, `collapsedSubgroups`, `showUngroupedEvents`, `showUnsubgroupedEvents`) go through `--view-state '<json>'` / `--view-state-file <path>`.
+
+For HIERARCHY, `label` is required at every level but info/number mappings are optional; each child level relates to its parent through `childFieldId` (level 2 → root, level 3 → level 2, …). Numeric columns aggregate upward: a parent shows the aggregation of its children's values, falling back to the level's own mapped value when children have none. Column ids (the `id` in `--hierarchy-info`/`--hierarchy-number`, reused as `columnId` in every mapping) must be unique opaque identifiers you choose — not the column name; the frontend generates them as `col_<timestamp>_<random>` (e.g. `col_1779975207355_zfndknslw`). Pass the whole `hierarchyConfig` at once with `--hierarchy-config '<json>'` / `--hierarchy-config-file <path>` if you prefer.
+
 Widget types: `TABLE_OR_SUBTABLE`, `DETAIL`, `KPI`, `CHART`, `TIMELINE`, `KANBAN`, `HIERARCHY`.
 
 ### Set freeform layout
@@ -501,6 +567,8 @@ For comparators the parser does not cover yet (e.g. `NOT_CONTAINS`, `RANGE`) kee
 
 Slugs are resolved to UUIDs in: `--field`, `--source-schema`, `--source-field`, `--x-axis-field`, `--filter` field reference, `kpi.fieldCalc`, `chart.xAxisFieldId`, `chart.yAxisSeries[].fieldCalc`, `bindings.variableMap` values.
 
+**Exception:** field references inside the KANBAN/TIMELINE `viewState` (`--column-field`, `--start-date-field`, `--card-*-field`, `--aggregation-field`, …) and inside the HIERARCHY `hierarchyConfig` (`--hierarchy-root-label-field`, `--hierarchy-root-info`/`--hierarchy-root-number` field ids, child level `*FieldId`/`schemaId`) are **not** slug-resolved — the backend only resolves slugs in `view.fields`, so these must be canonical UUIDs.
+
 Display UUIDs are required for `displays widgets create/update` and `displays variables create`.
 
 ---