@synap-core/cli 1.2.0 → 1.5.0

package/skills/synap-ui/view-types.md

@@ -0,0 +1,259 @@
+# View types — reference
+
+Each view type has its own `config` shape. This file covers the 12 implemented types with their required/optional fields.
+
+All views share a base shape:
+
+```ts
+{
+  name: string,
+  type: ViewType,
+  profileSlug?: string,          // which entity profile to query (required for entity views)
+  description?: string,
+  config: ViewTypeConfig         // type-specific, see below
+}
+```
+
+Common sub-objects:
+
+```ts
+// Filter — combine in arrays for AND; use { or: [...] } for OR
+type Filter = {
+  property: string;
+  op:
+    | "eq"
+    | "neq"
+    | "gt"
+    | "gte"
+    | "lt"
+    | "lte"
+    | "in"
+    | "nin"
+    | "contains"
+    | "exists";
+  value: unknown;
+};
+
+// Sort
+type Sort = { property: string; direction: "asc" | "desc" };
+
+// Column (for tabular views)
+type Column = { slug: string; width?: number; label?: string };
+```
+
+---
+
+## `table`
+
+Dense data. Sort, filter, resize columns.
+
+```ts
+config: {
+  columns: Column[],
+  filters?: Filter[],
+  sort?: Sort[],
+  pageSize?: number,         // default 50
+  groupBy?: { property: string }  // optional row grouping
+}
+```
+
+Best for: tasks with many fields, deals with pipeline data, contacts with CRM attributes.
+
+## `list`
+
+Scan-friendly rows. Shows title + 2–3 properties per row.
+
+```ts
+config: {
+  primaryField: string,      // usually "title"
+  secondaryFields: string[], // 2–3 properties shown as meta
+  filters?: Filter[],
+  sort?: Sort[]
+}
+```
+
+Best for: tasks, notes, messages, action items.
+
+## `grid`
+
+Uniform card grid.
+
+```ts
+config: {
+  cardFields: string[],      // properties shown on each card
+  filters?: Filter[],
+  sort?: Sort[],
+  density?: "compact" | "comfortable" | "spacious"
+}
+```
+
+Best for: mixed content where title + 2 properties is enough.
+
+## `gallery`
+
+Image-forward cards. Requires a property that holds an image URL.
+
+```ts
+config: {
+  imageProperty: string,     // e.g., "thumbnail", "favicon", "cover"
+  titleProperty?: string,    // default "title"
+  captionProperty?: string,
+  filters?: Filter[],
+  sort?: Sort[]
+}
+```
+
+Best for: articles, bookmarks, products, books, photos.
+
+## `kanban`
+
+Status pipeline. Requires `groupBy` on an enum/status property.
+
+```ts
+config: {
+  groupBy: { property: string },  // MUST be set — column grouping
+  cardFields: string[],
+  filters?: Filter[],
+  sort?: Sort[],
+  columnOrder?: string[]          // force column order
+}
+```
+
+Best for: tasks by status, deals by stage, drafts by workflow step.
+
+## `matrix`
+
+2-axis grid. Requires two `groupBy` properties.
+
+```ts
+config: {
+  xAxis: { property: string, buckets?: string[] | number[] },
+  yAxis: { property: string, buckets?: string[] | number[] },
+  cardFields?: string[],
+  filters?: Filter[]
+}
+```
+
+Best for: priority × urgency (Eisenhower), effort × impact, stage × owner.
+
+## `masonry` / `feed`
+
+Pinterest-style, variable-size cards. Default for Library.
+
+```ts
+config: {
+  cardFields: string[],
+  filters?: Filter[],
+  sort?: Sort[],
+  variableHeight: true      // cards size themselves to content
+}
+```
+
+Best for: mixed content types, inspiration boards, library browsing.
+
+## `calendar`
+
+Date-indexed. Requires a date property.
+
+```ts
+config: {
+  dateProperty: string,           // e.g., "dueDate", "startDate"
+  endDateProperty?: string,       // for events with duration
+  view?: "month" | "week" | "day" | "agenda",
+  titleProperty?: string,
+  colorBy?: { property: string },
+  filters?: Filter[]
+}
+```
+
+Best for: events, tasks with dueDate, drafts with publishDate.
+
+## `flow`
+
+Node-edge graph. Fully custom — mostly used for automations and mindmaps.
+
+```ts
+config: {
+  nodes: { id, type, position: {x,y}, data }[],
+  edges: { id, source, target, type? }[],
+  fitView?: boolean
+}
+```
+
+Best for: automations, workflow diagrams, mind maps, decision trees. Usually populated programmatically by the automation builder, not hand-authored.
+
+## `bento`
+
+A mixed composition of cells. See `widget-catalog.md` and `bento-recipes.md` for block kinds and ready-to-use layouts.
+
+```ts
+config: {
+  blocks: BentoBlock[],     // see bento section
+  gridColumns?: 12,         // default 12
+  rowHeight?: number        // px per grid row
+}
+```
+
+Best for: dashboards, workspace home pages, project overview pages.
+
+## `branch_tree`
+
+Hierarchical data with parent-child relationships.
+
+```ts
+config: {
+  parentProperty: string,   // e.g., "parentTaskId", "parentProjectId"
+  titleProperty?: string,
+  cardFields?: string[],
+  expandDepth?: number      // default 2
+}
+```
+
+Best for: projects with subtasks, topic hierarchies, org charts, file trees.
+
+## `whiteboard`
+
+Free-form canvas. Sparse config — most state is in the canvas itself.
+
+```ts
+config: {
+  canvasId: string,         // links to the yjs doc
+  defaultTool?: "pen" | "rect" | "arrow" | "text"
+}
+```
+
+Best for: brainstorming, sketches, visual thinking. Rarely generated by AI — user-authored.
+
+---
+
+## Picking a view type
+
+Work from the data, not from the request:
+
+| User says                       | Look at data                         | Pick                                                   |
+| ------------------------------- | ------------------------------------ | ------------------------------------------------------ |
+| "track tasks"                   | has `status` (enum)                  | `kanban`                                               |
+| "what's due this week"          | has `dueDate`                        | `calendar`                                             |
+| "my reading list"               | articles / bookmarks with thumbnails | `gallery`                                              |
+| "dashboard for X"               | mixed data, 4+ types of info         | `bento`                                                |
+| "pipeline", "stages"            | has ordered enum property            | `kanban`                                               |
+| "roadmap", "timeline"           | has start + end dates                | defer (unsupported) — use `calendar` or `list` grouped |
+| "team directory"                | people with photos                   | `gallery`                                              |
+| "urgent vs. important"          | has 2 enum dimensions                | `matrix`                                               |
+| "project hierarchy"             | has parent-child relation            | `branch_tree`                                          |
+| "everything", "library"         | mixed profiles                       | `masonry`/`feed` or `bento`                            |
+| "data", "database", "inventory" | dense, many columns                  | `table`                                                |
+
+If in doubt: `list` is the safe default for any entity type. Always better than guessing wrong.
+
+## Updating vs. creating
+
+- `POST /views` — create new view (auto-approved for agents)
+- `PATCH /views/:viewId` — update config (proposal-gated by default; the user owns their views)
+- `POST /views/:viewId/arrange` — bento-specific, rearrange blocks (auto-approved)
+
+When the user says "change my kanban to group by priority instead of status," that's a PATCH — expect a proposal. Explain this to the user.
+
+## Multiple views over the same data
+
+Views are cheap. A single `task` profile can have 10 views: kanban by status, kanban by project, calendar by dueDate, list of overdue, matrix priority × urgency, gallery of completed. Each view is one `POST /views` call. Don't try to make one mega-view that satisfies every need.

package/skills/synap-ui/widget-catalog.md

@@ -0,0 +1,305 @@
+# Widget catalog — reference
+
+Widgets (cells) are the universal rendering unit. A bento is composed of cells. Views embed cells. Side panels host cells.
+
+**Never guess a widget kind.** Always call `GET /api/hub/widget-definitions?workspaceId={workspaceId}` first — the response is the authoritative registry for what's installed.
+
+This file is a categorized snapshot of what typically exists in a Synap pod. Use it for planning ("can I build X?") — but verify against the registry before committing.
+
+## How widget references work in bentos
+
+```json
+{
+  "id": "block-123",
+  "kind": "widget",
+  "widgetKind": "stat-card",
+  "config": {
+    /* widget-specific, see configSchema in registry */
+  },
+  "layout": { "x": 0, "y": 0, "w": 4, "h": 2 }
+}
+```
+
+`widgetKind` is a string matching a registered cell. `config` must validate against the cell's `configSchema` (returned by `/widget-definitions`).
+
+## Categories
+
+The registry tags each widget with a category:
+
+- `core` — universal layout primitives (stat, section-header, quick-access)
+- `data` — entity-driven (entity-card, entity-gallery, view embeds)
+- `ai` — AI outputs (proactive cards, proposals, chat)
+- `entity` — entity-detail views and editors
+- `communication` — channels, threads, messages
+- `governance` — proposals, approvals
+- `content` — documents, articles, rich media
+
+## Core widgets (layout primitives — always available)
+
+### `stat-card`
+
+Single metric on a card. Best for top-of-dashboard KPIs.
+
+```json
+{
+  "widgetKind": "stat-card",
+  "config": {
+    "label": "Tasks completed this week",
+    "metric": "count",
+    "filter": {
+      "profileSlug": "task",
+      "properties.status": "done",
+      "updatedAt.gte": "this-week"
+    },
+    "trend": true, // show vs. last period
+    "icon": "check-circle"
+  }
+}
+```
+
+### `section-header`
+
+Title + optional subtitle. Separator for bento rows.
+
+```json
+{
+  "widgetKind": "section-header",
+  "config": { "title": "This week", "subtitle": "Updated just now" }
+}
+```
+
+### `quick-access`
+
+Shortcut grid — a row of entity or view pins.
+
+```json
+{
+  "widgetKind": "quick-access",
+  "config": {
+    "items": [
+      { "kind": "view", "viewId": "...", "label": "Inbox" },
+      {
+        "kind": "entity",
+        "entityId": "ent_project_...",
+        "label": "Current project"
+      },
+      { "kind": "url", "url": "https://...", "label": "Calendar" }
+    ]
+  }
+}
+```
+
+### `feed`
+
+Activity feed — recent entity mutations, AI actions, proposals.
+
+```json
+{
+  "widgetKind": "feed",
+  "config": {
+    "sources": ["entity.create", "entity.update", "proposal.approved"],
+    "limit": 20,
+    "filter": { "profileSlug": ["task", "note"] } // optional
+  }
+}
+```
+
+### `inbox`
+
+Unread + actionable items. Proposals, mentions, due tasks.
+
+```json
+{
+  "widgetKind": "inbox",
+  "config": { "categories": ["proposals", "mentions", "due_today"] }
+}
+```
+
+## Data widgets
+
+### `entity-card`
+
+One entity, rich rendering.
+
+```json
+{
+  "widgetKind": "entity-card",
+  "config": {
+    "entityId": "ent_...",
+    "fields": ["title", "status", "dueDate", "assignee"],
+    "showRelations": true
+  }
+}
+```
+
+### `entity-gallery`
+
+Gallery of entities filtered by a query.
+
+```json
+{
+  "widgetKind": "entity-gallery",
+  "config": {
+    "profileSlug": "article",
+    "filters": [{ "property": "status", "op": "eq", "value": "unread" }],
+    "sort": [{ "property": "createdAt", "direction": "desc" }],
+    "limit": 12,
+    "imageProperty": "thumbnail"
+  }
+}
+```
+
+### `entity-spotlight`
+
+One featured entity, large format. Often the "current project" or "today's focus."
+
+```json
+{
+  "widgetKind": "entity-spotlight",
+  "config": { "entityId": "ent_...", "showDocument": true }
+}
+```
+
+### `view` (generic view embed)
+
+Any saved view rendered inside a bento. Usually easier than configuring widgets individually.
+
+```json
+{
+  "kind": "view",
+  "viewId": "<savedViewId>",
+  "layout": { "x": 0, "y": 0, "w": 12, "h": 6 }
+}
+```
+
+Note: `{ "kind": "view", "viewId": … }` is a bento block type, not a widget. Use it when you have a saved view and just want to embed it.
+
+### `view-kanban` / `view-table` / `view-calendar` / `view-grid` / `view-list`
+
+Inline view configs — no saved view required. Good for one-off dashboard pieces.
+
+```json
+{
+  "widgetKind": "view-kanban",
+  "config": {
+    "profileSlug": "task",
+    "groupBy": { "property": "status" },
+    "filters": [{ "property": "projectId", "op": "eq", "value": "ent_current" }]
+  }
+}
+```
+
+## Entity widgets (for entity-detail pages / side panels)
+
+- `entity-detail` — the full entity view (fields, properties, related)
+- `document-editor` — rich markdown editor for a document
+- `entity-relationships` — graph/list of connected entities
+- `entity-properties` — the properties panel (forms)
+
+Mostly used inside entity pages, not bentos.
+
+## AI widgets
+
+### `proactive-feed`
+
+AI nudges and insights the user's agents posted proactively.
+
+```json
+{
+  "widgetKind": "proactive-feed",
+  "config": { "limit": 10, "categories": ["insight", "nudge", "digest"] }
+}
+```
+
+### `morning-briefing` / `weekly-digest` / `health-check` / `insight`
+
+Proactive cards rendered individually. Usually only appear after the Proactive Intelligence Layer has posted — not manually composed by an agent.
+
+### `ai-chat`
+
+Embedded chat surface targeting a specific channel.
+
+```json
+{
+  "widgetKind": "ai-chat",
+  "config": { "channelId": "ch_...", "mode": "compact" }
+}
+```
+
+### `recent-chats`
+
+List of recent AI conversations.
+
+### `agent-activity`
+
+What the user's agents have been doing (actions, proposals, writes). Good for governance bentos.
+
+## Governance widgets
+
+- `proposals-list` — pending proposals needing review
+- `proposal-detail` — single proposal card
+- `proposal-timeline` — history of proposal approvals/rejections
+
+```json
+{
+  "widgetKind": "proposals-list",
+  "config": { "status": "pending", "limit": 10 }
+}
+```
+
+## Communication widgets
+
+- `channel` — full channel (messages + composer)
+- `channel-navigator` — sidebar-style channel list
+- `channel-view` — read-only channel embed
+- `channel-feed` — activity-style feed of messages
+
+## Intelligence widgets (Intelligence Service specific)
+
+- `service-status` — IS health
+- `usage` — token consumption, model usage
+- `agents` — registered agents list
+- `agent-detail` — one agent's config
+- `skills` — installed skills
+- `tasks` — IS-managed tasks (not entities)
+
+## Workflow widgets
+
+- `workflow-list` — all automations
+- `automation-detail` / `automation-flow` / `automation-status`
+- `command-detail` — one command config
+- `trigger-button` — a button that runs a command
+- `run-history` — past automation runs
+
+## Layout guidelines
+
+The bento grid is 12 columns. Typical widget sizes:
+
+| Widget             | Typical `w`, `h` |
+| ------------------ | ---------------- |
+| `stat-card`        | 3×2              |
+| `section-header`   | 12×1             |
+| `quick-access`     | 6×2 or 12×2      |
+| `view-kanban`      | 8×4 or 12×6      |
+| `view-calendar`    | 8×4 or 12×6      |
+| `entity-spotlight` | 4×4              |
+| `entity-gallery`   | 6×4 or 12×4      |
+| `feed` / `inbox`   | 4×6 or 6×6       |
+| `proactive-feed`   | 4×6              |
+| `proposals-list`   | 6×4              |
+| `agent-activity`   | 6×4              |
+
+Rules of thumb:
+
+- Don't make anything shorter than 2 rows (too cramped).
+- Tall narrow feeds (4×6) work better than short wide ones.
+- Put `section-header` (12×1) as the first row of a visual group.
+- Limit a bento to 8–12 blocks. Past that, split into a second bento or a dedicated view.
+
+## Common mistakes
+
+1. **Referencing a `widgetKind` that doesn't exist in the registry.** The bento will render an error block. Always fetch the registry first.
+2. **Passing a `config` that doesn't match the widget's `configSchema`.** Returns a validation error; the widget shows "invalid config" in UI.
+3. **Using a widget that depends on a missing profile.** If you use `entity-gallery` with `profileSlug: "podcast"` and `podcast` doesn't exist, the widget shows an empty state. Verify first.
+4. **Overlapping layout rectangles.** react-grid-layout will resolve it by shifting blocks, but the output won't match your intent. Double-check `x + w <= 12` and no two blocks share the same cells.
+5. **Putting an `ai-chat` widget on a dashboard.** It works but rarely what the user wants — the chat app is already one tab away. Reserve for edge cases like project-specific chat pinned to a project home.