@synap-core/cli 1.2.0 → 1.5.0

package/skills/synap-schema/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: synap-schema
+description: >
+  Use this skill when the user needs to extend Synap's data model — defining a
+  new type of thing (entity profile) or adding/modifying fields (property defs)
+  on existing types. Triggers: "I need a new type for podcasts/recipes/workouts/
+  clients/books/plants/investments", "add a priority field to tasks", "create a
+  property for tracking budget", "I want to track Y and it's not in my current
+  schema", defining custom relations, setting up a profile for a specific domain
+  (real estate, music production, research, fitness, cooking). Also triggers on:
+  "do I already have a profile for X?", "what fields does <profile> have?",
+  extending an existing profile with workspace-specific overlay properties.
+  Do NOT use this skill for creating instances of existing types — the core
+  `synap` skill handles that. This skill changes the SCHEMA, not the data.
+metadata:
+  openclaw:
+    requires:
+      env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
+    primaryEnv: SYNAP_HUB_API_KEY
+    homepage: https://synap.live
+    capabilities: [schema, profiles, properties]
+    os: [macos, linux, windows]
+    userInvocable: false
+---
+
+# Synap — schema extension
+
+You extend a user's Synap pod schema: new entity profiles, new properties on existing profiles, overlay properties scoped to one workspace. The core rule: **reuse before extending.** Creating duplicate profiles fractures the graph.
+
+## Before you touch anything
+
+Always inventory first. Never assume the schema is empty.
+
+```
+GET /api/hub/profiles?userId={userId}&workspaceId={workspaceId}
+  → [{ slug, displayName, entityScope, parentProfileSlug,
+       properties: [{ slug, valueType, constraints, uiHints, targetProfileSlug? }] }]
+
+GET /api/hub/property-defs?userId={userId}&workspaceId={workspaceId}&profileId={profileId}
+  → [{ slug, valueType, constraints, uiHints, workspaceId /* null=base, uuid=overlay */ }]
+```
+
+The `synap` skill's `scripts/orient.sh` already fetches profiles — reuse its output.
+
+## Discover profiles — never assume
+
+**Always call `GET /api/hub/profiles?workspaceId={workspaceId}` first.** Profiles are dynamic — every pod and workspace has a different set depending on what was seeded and what the user created. Never assume a profile slug exists without verifying.
+
+```
+GET /api/hub/profiles?workspaceId={workspaceId}
+  → [{ slug, displayName, entityScope, parentSlug,
+       properties: [{ slug, valueType, required, ... }] }]
+```
+
+Read the response:
+
+- `entityScope: "pod"` — visible across all workspaces
+- `entityScope: "workspace"` — scoped to this workspace only (custom types, CRM profiles, template-seeded types)
+- `parentSlug` — inheritance chain (e.g. `contact` extends `person`)
+
+### Commonly seeded profiles (verify before using)
+
+Standard pods typically include: `note`, `task`, `project`, `event`, `person`, `contact`, `company`, `bookmark`, `website`, `article`, `capture`, `file`, `anchor`, `decision`, `question`, `research`
+
+CRM workspaces additionally have: `deal`, `client` — but **only** when a CRM workspace was created.  
+Custom workspace templates (devplane, content, etc.) add their own profiles entirely.
+
+Before creating a new profile: **does one of these already fit?** A podcast episode is arguably an `article`. A meeting is an `event`. A book to read is an `article` or `bookmark`. Err on the side of reuse + extension, not creation.
+
+## When to extend an existing profile vs. create a new one
+
+Extend when:
+
+- The thing fits an existing category (a "client" is a kind of `contact` — consider inheritance)
+- The user needs 1–3 extra fields on an existing type
+- The new fields are workspace-specific (use an overlay, see below)
+
+Create new when:
+
+- None of the system profiles fits
+- The thing has a clearly distinct set of properties (10+ fields)
+- The domain model genuinely calls for a new first-class type (recipe, workout, podcast episode, investment, plant, medication, vehicle, property listing…)
+
+Prefer **inheritance** over new profiles when a system parent fits. `contact extends person` is the pattern — a new `client` profile can `parentProfileSlug: "contact"` and only add the fields that differ.
+
+## Creating a new profile
+
+```json
+POST /api/hub/profiles
+{
+  "userId":          "{userId}",
+  "workspaceId":     "{workspaceId}",
+  "slug":            "podcast_episode",     // snake_case, unique
+  "displayName":     "Podcast Episode",
+  "description":     "An episode of a podcast the user listens to",
+  "parentProfileId": "<id of article or null>",  // optional, enables inheritance
+  "defaultValues":   { "status": "queued" },
+  "uiHints":         { "icon": "mic", "color": "purple" }
+}
+```
+
+Then add properties one by one (see below). You do NOT declare properties inline on the profile — they're separate rows.
+
+## Creating properties
+
+```json
+POST /api/hub/property-defs
+{
+  "userId":      "{userId}",
+  "workspaceId": "{workspaceId}",
+  "profileId":   "{profileId}",    // the profile this property belongs to
+  "slug":        "durationMinutes",
+  "valueType":   "number",
+  "constraints": { "min": 0, "max": 600 },
+  "uiHints":     { "format": "compact", "displayName": "Duration" }
+}
+```
+
+Value types: `string`, `number`, `boolean`, `date`, `entity_id`, `array`, `object`, `secret`. Full reference in **`property-types.md`**.
+
+For linking properties, always use `entity_id` with `targetProfileSlug` in constraints:
+
+```json
+{
+  "slug": "hostId",
+  "valueType": "entity_id",
+  "constraints": { "targetProfileSlug": "person" },
+  "uiHints": { "displayName": "Host" }
+}
+```
+
+This enables auto-sync (see `../synap/linking.md`) — the property becomes a typed link that shows up in graph traversals automatically.
+
+## Workspace overlay properties
+
+New concept (2026-04-10+). A single profile (say `task`) can have **different fields in different workspaces** without copying the profile. Set `overlay: true` on `POST /property-defs`:
+
+```json
+POST /api/hub/property-defs
+{
+  "userId":      "{userId}",
+  "workspaceId": "{workspaceId}",
+  "profileId":   "{taskProfileId}",
+  "slug":        "billableHours",
+  "valueType":   "number",
+  "overlay":     true               // this property only appears in this workspace
+}
+```
+
+Use cases:
+
+- "My consulting workspace needs `billableHours` on tasks; my personal workspace doesn't."
+- "Our sales workspace wants a `dealSize` on contacts; engineering doesn't."
+
+Overlays don't leak: workspace A can't see workspace B's overlay properties even though both share the profile. For the full scope model, read **`property-types.md`** §Overlay.
+
+## Entity scope (pod-wide vs. workspace-scoped)
+
+Profiles have an `entityScope` that determines where entities of that type live:
+
+- `entityScope: "pod"` — entities are pod-wide, visible in every workspace the user can access. Good for people, companies, notes, articles — things that cross contexts.
+- `entityScope: "workspace"` — entities live in the workspace they were created in. Good for deals, files, workspace-specific artifacts.
+
+Defaults to `workspace` if not set on the profile. The user can toggle this per profile in ProfileEditor Settings. If you're creating a profile for something clearly pod-wide (a person, a podcast the user follows, a book in their library), set `entityScope: "pod"` explicitly.
+
+## Custom relations
+
+If the user wants a typed edge that isn't in the convention list (see `../synap/linking.md`), you can define it:
+
+```json
+POST /api/hub/relation-defs
+{
+  "userId":        "{userId}",
+  "workspaceId":   "{workspaceId}",
+  "slug":          "mentored_by",
+  "displayName":   "Mentored by",
+  "sourceProfileSlug": "person",
+  "targetProfileSlug": "person",
+  "bidirectional": false
+}
+```
+
+Defining a relation def is rarely worth it — `related_to` + a property usually suffices. Only create one when the relationship is semantic enough that UI should treat it specially (e.g., show "mentored by Jane" on a person's profile card).
+
+## Worked example — "I want to track podcasts I listen to"
+
+1. Inventory. `GET /profiles` → no `podcast` profile, no `podcast_episode`.
+2. Decide scope. Podcasts/episodes are pod-wide (same podcast across workspaces).
+3. Create two profiles (podcast + episode) or one (episode only, with the show as a string property)? Decide based on the user's intent. If they want to group episodes by show → two profiles. If one-level is enough → one.
+4. For two profiles:
+
+   ```
+   POST /profiles { slug: "podcast", displayName: "Podcast", entityScope: "pod", uiHints: { icon: "radio" } }
+   POST /profiles { slug: "podcast_episode", displayName: "Podcast Episode", parentProfileId: <articleId>, entityScope: "pod" }
+   ```
+
+5. Add properties on `podcast`:
+
+   ```
+   POST /property-defs { slug: "host",      valueType: "string" }
+   POST /property-defs { slug: "rssUrl",    valueType: "string", uiHints: { inputType: "url" } }
+   POST /property-defs { slug: "category",  valueType: "string" }
+   ```
+
+6. Add properties on `podcast_episode`:
+
+   ```
+   POST /property-defs { slug: "podcastId",       valueType: "entity_id", constraints: { targetProfileSlug: "podcast" } }
+   POST /property-defs { slug: "durationMinutes", valueType: "number" }
+   POST /property-defs { slug: "listenedAt",      valueType: "date" }
+   POST /property-defs { slug: "rating",          valueType: "number", constraints: { min: 1, max: 5 } }
+   ```
+
+7. Tell the user. "I added `podcast` and `podcast_episode` to your pod with linking between them. You can create your first episode now, or want me to also add a view for it?" (Hand off to the `synap-ui` skill if they say yes.)
+
+## Common mistakes
+
+1. **Creating a profile that already exists (e.g., `meeting` when `event` fits).** Always inventory first.
+2. **Declaring properties inline on the profile object.** Properties are separate rows; use `POST /property-defs`.
+3. **Using `string` for what should be `entity_id`.** If the field refers to another entity (host of a podcast), use `entity_id` + `targetProfileSlug` — enables auto-sync and link UX.
+4. **Using `array` of strings for tags.** Tags are a built-in concept; reuse the `tags` property on `note`/`project` instead of creating a parallel field.
+5. **Forgetting `entityScope`.** Defaults to `workspace`. If the thing is pod-wide (people, books, podcasts), set it explicitly.
+6. **Creating an overlay when a base property is wanted.** Overlays only appear in one workspace. If the user wants the field everywhere, don't set `overlay: true`.
+7. **Creating a custom profile when extension would work.** `client extends contact` is cleaner than a parallel `client` profile.
+
+## When you need more
+
+- Full `valueType` reference + constraints + uiHints → **`property-types.md`**
+- Inheritance, overlay scope semantics, pod-wide caveats → **`property-types.md`** §Scope
+- Creating views over the new profile → install the **`synap-ui`** skill
+- Creating instances of the new profile → use the core **`synap`** skill

package/skills/synap-schema/property-types.md

@@ -0,0 +1,228 @@
+# Property types — reference
+
+Every property on a profile has a `valueType`. This is the authoritative list, what each type stores, and how to configure it.
+
+## Value types
+
+### `string`
+
+Plain text.
+
+```json
+{
+  "slug": "email",
+  "valueType": "string",
+  "constraints": { "maxLength": 200, "pattern": "^.+@.+\\..+$" },
+  "uiHints": { "inputType": "email" }
+}
+```
+
+**uiHints.inputType variants:** `email`, `phone`, `url`, `person`, `richtext`, `select`, `datetime`, `datetime-local`.
+**uiHints.displayAs variants:** `status`, `priority`, `progress`, `person` — used by list/table views for special badges.
+
+### `number`
+
+Integer or float.
+
+```json
+{
+  "slug": "price",
+  "valueType": "number",
+  "constraints": { "min": 0, "max": 1000000 },
+  "uiHints": { "format": "currency", "displayName": "Price" }
+}
+```
+
+**uiHints.format:** `locale`, `currency`, `percent`, `compact`.
+
+### `boolean`
+
+True/false.
+
+```json
+{
+  "slug": "isArchived",
+  "valueType": "boolean",
+  "uiHints": { "displayName": "Archived" }
+}
+```
+
+### `date`
+
+ISO 8601 date or datetime.
+
+```json
+{
+  "slug": "dueDate",
+  "valueType": "date",
+  "uiHints": { "includeTime": false, "displayName": "Due" }
+}
+```
+
+Set `includeTime: true` for datetime; false for date-only. Don't store durations as dates — use `number` in seconds/minutes.
+
+### `entity_id`
+
+**The important one.** A reference to another entity by UUID. Triggers the auto-sync behaviour (see `../synap/linking.md`).
+
+```json
+{
+  "slug": "projectId",
+  "valueType": "entity_id",
+  "constraints": { "targetProfileSlug": "project" },
+  "uiHints": { "linkedProfileSlug": "project", "displayName": "Project" }
+}
+```
+
+**Always set `targetProfileSlug`** (or `targetProfileSlugs: [...]` for multi-target). Without it, UI can't render a picker and auto-sync defaults to `related_to`.
+
+For linking to users (workspace members), use:
+
+```json
+{
+  "slug": "assignee",
+  "valueType": "entity_id",
+  "constraints": { "targetProfileSlug": "person" },
+  "uiHints": { "inputType": "person", "linkedTable": "workspace_members" }
+}
+```
+
+### `array`
+
+List of primitives OR list of entity references.
+
+For tags / free-text lists:
+
+```json
+{
+  "slug": "tags",
+  "valueType": "array",
+  "uiHints": { "itemValueType": "string" }
+}
+```
+
+For multi-entity lists (e.g., event attendees):
+
+```json
+{
+  "slug": "attendees",
+  "valueType": "array",
+  "uiHints": { "itemValueType": "entity_id", "linkedProfileSlug": "person" }
+}
+```
+
+Arrays of entity IDs **don't auto-sync** — if you want bidirectional linking for each item, create explicit relations.
+
+### `object`
+
+Arbitrary JSON. Only for data that genuinely has no fixed schema.
+
+```json
+{ "slug": "metadata", "valueType": "object" }
+```
+
+Avoid when possible. Objects don't index well and can't be filtered in views. Prefer breaking out properties.
+
+### `secret`
+
+Like `string` but masked in UI, encrypted at rest, never returned in list responses.
+
+```json
+{ "slug": "apiToken", "valueType": "secret" }
+```
+
+Use for credentials stored on an entity (e.g., a connector's OAuth refresh token). Never put actual user data here — use `string`.
+
+## Constraints
+
+The `constraints` object is value-type specific:
+
+| valueType   | Supported constraints                                         |
+| ----------- | ------------------------------------------------------------- |
+| `string`    | `minLength`, `maxLength`, `pattern` (regex), `enum: string[]` |
+| `number`    | `min`, `max`, `integer: true`, `enum: number[]`               |
+| `date`      | `min` (ISO), `max` (ISO)                                      |
+| `entity_id` | `targetProfileSlug`, `targetProfileSlugs` (multi)             |
+| `array`     | `minItems`, `maxItems`, `uniqueItems: true`                   |
+| `object`    | (none — prefer breaking into typed properties)                |
+
+Violations return a 400 from `POST /entities` with `{ error: "validation", field: "slug", issue: "..." }`.
+
+## uiHints reference
+
+```ts
+{
+  displayName?: string          // Label in UI forms and views
+  placeholder?: string          // Input placeholder
+  inputType?: "email" | "phone" | "url" | "person" | "richtext"
+             | "datetime" | "datetime-local" | "select"
+  displayAs?: "status" | "priority" | "progress" | "person"
+  format?:    "locale" | "currency" | "percent" | "compact"
+  includeTime?: boolean         // date only
+  linkedProfileSlug?: string    // entity_id rendering
+  linkedTable?: "workspace_members" | "free_text"
+  itemValueType?: "string" | "number" | "boolean" | "date" | "entity_id" | "url"
+  pluginHints?: Record<string, unknown>  // freeform for custom cells
+}
+```
+
+uiHints are cosmetic — they change rendering, not validation. If you need enforcement, use `constraints`.
+
+## Scope — three layers
+
+Every property def has two scope dimensions:
+
+| `profileId` | `workspaceId` | Layer             | Who sees it                            |
+| ----------- | ------------- | ----------------- | -------------------------------------- |
+| null        | null          | Global            | Every workspace, every profile         |
+| set         | null          | Profile-base      | Every workspace that uses this profile |
+| set         | set           | Workspace overlay | Only that workspace                    |
+
+The rendering rule for a given `(profile, workspace)`:
+
+```
+visible = global  ∪  profile-base  ∪  this-workspace's overlays on this profile
+```
+
+Other workspaces' overlays are filtered out at SQL level.
+
+### When to use each
+
+- **Global** (rare): properties that apply to all entity types (e.g., `createdBy`, `tags`). System only.
+- **Profile-base** (default): the property should appear for everyone using this profile. Creating a property for a workspace-owned profile → profile-base.
+- **Overlay**: the property is specific to one workspace extending a shared profile. Pass `overlay: true` in `POST /property-defs`.
+
+If you're extending a pod-wide profile (like `task` or `contact`) with a workspace-specific field, you **must** use overlay — otherwise you'd pollute every workspace.
+
+Entities can carry overlay property values even in workspaces that don't see the overlay — the values are preserved but invisible. This is by design.
+
+## Inheritance
+
+If a profile has `parentProfileSlug`, it inherits the parent's property defs. Own properties override parent properties by slug.
+
+Example: `contact` has `parentProfileSlug: "person"`. A contact entity has both `person.email` and `contact.role`. Set `email` on a contact and you satisfy the parent schema.
+
+When creating a child profile, don't re-declare the parent's properties. Only add what's new.
+
+## Validation semantics
+
+On `POST /entities` and `PATCH /entities`:
+
+1. Compute effective properties = profile-base ∪ global ∪ workspace overlays.
+2. For each property in the request body, check the def exists and the value passes `valueType` + `constraints`.
+3. Unknown properties (not in any layer) are stored in JSONB but never rendered. Avoid — they rot.
+
+Properties not in the request body are not cleared. Use `PATCH` with `{ "properties": { "x": null } }` to explicitly unset.
+
+## Performance note
+
+Every entity_id property is indexed via `entity_property_index.value_entity_id` for fast reverse-lookup ("find all entities whose `projectId` is X"). This is what makes Way 1 cheap at scale. Inventing a string property with UUIDs inside will work but won't be indexed — use `entity_id`.
+
+## Common mistakes
+
+- Using `string` for what should be `entity_id` (loses auto-sync + reverse-lookup).
+- Omitting `constraints.targetProfileSlug` on `entity_id` props (breaks pickers, breaks auto-sync routing).
+- Creating an `array` of entity_ids and expecting bidirectional linking (it doesn't — use explicit relations).
+- Using `object` when two `string` properties would suffice.
+- Reusing `tags` as an entity_id list (tags is free-text by convention; make a new `relatedProjects` property instead).
+- Overriding parent profile properties with weaker types (child `email` as `object` when parent is `string`) — creates validation drift.