@synap-core/cli 1.8.0 → 1.11.0

package/skills/synap-schema/SKILL.md

@@ -27,6 +27,8 @@ metadata:
 
 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.
@@ -42,6 +44,61 @@ GET /api/hub/property-defs?userId={userId}&workspaceId={workspaceId}&profileId={
 
 The `synap` skill's `scripts/orient.sh` already fetches profiles — reuse its output.
 
+---
+
+## Read before you write
+
+Synap data is a typed graph — never write blind. Before creating or updating an
+entity, work the loop the same way you'd read a file before editing it:
+
+1. **MAP** — know what types exist: `list_profiles` (the cheap map of entity
+   profiles), `list_views` for views.
+2. **SEARCH** — `search_unified({ query: <title>, collections: ["entities"] })`.
+   If a close match exists, LINK to it (relation or entity_id property) — do NOT
+   create a duplicate. Create only when there is genuinely no match.
+3. **READ THE SCHEMA** — before writing to a profile you haven't inspected this
+   session, call `get_profile({ slug })` for its real property defs (exact keys,
+   value types, enum options, link targets). For views, read the config
+   (`get_bento_schema`) before `create_view`.
+4. **WRITE INTO THE REAL FIELDS** — map each value to its correct typed property:
+   right `key`, valid `valueType` (dates as ISO, numbers as numbers), enum values
+   that satisfy the constraint, links via the property's `linksTo` target. Don't
+   invent property keys. A value with no matching property goes into
+   description/content, or propose a new one with `create_property_def` — never
+   drop it into a stray key.
+5. **CONNECT** — every new entity links to at least one other. Duplicates and
+   orphans are the two ways the graph degrades; avoid both.
+
+## Complete intent, governed outcome
+
+`title` + `content` is only a minimum payload, not Synap's data model. Once
+you have read the schema, send the complete intent that is known: `profileSlug`,
+title, typed `properties`, short `description`, long-form `content`, an existing
+`projectId`, links, and source/session provenance. Include role `facets` in the
+same composite plan whenever they must be reviewed with the entity.
+
+- **One entity with known fields and no creation-time role change** → use
+  `create_entity` / `POST /entities`.
+- **Several entities, facets, or relations that belong in one review** → use the
+  composite graph/capture-plan door, never a loose sequence of creates.
+- **Raw input whose structure is unknown** → use capture to produce a plan;
+  preserve an original file with `keepRaw` when supplied. Raw source is not the
+  same thing as an entity's edited content.
+
+Workspace is an explicit lens: omit it to read the pod/base schema and let the
+profile's placement rule apply. Pass a workspace only when the user or a
+reviewed routing decision actually selected it; then its overlays are valid.
+Never fill it from a configured/default workspace.
+
+Read the write receipt before continuing. `pending` means a proposal exists and
+no entity has materialized; `applied` means the reported operations completed;
+`partial` means independent follow-up operations failed and must be repaired or
+surfaced. Do not send a speculative second update merely because a write
+completed — enrich only when you learned genuinely new information or the
+receipt identifies a specific missing field.
+
+---
+
 ## 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.
@@ -67,21 +124,41 @@ Custom workspace templates (devplane, content, etc.) add their own profiles enti
 
 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
+---
+
+## When to extend an existing profile vs. create a new one vs. attach a facet
+
+There are three moves, not two. Before extending or creating, ask whether the thing is really a **role** the entity plays rather than a new kind of entity at all — that's a facet, and it's the move people skip.
+
+**Kind + Facets, the rule:** one entity = one kind (`profiles.profileKind = 'kind'`). Roles the entity plays — client, partner, investor, prospect — are role-profiles (`profileKind = 'role'`, `applicableKinds[]`) attached via `entity_facets`: additive, workspace-lensed, NOT entities. A facet cascades with its parent entity; only promote a role to a full kind if it accrues its own independent life.
+
+**The litmus test:**
+
+- Both sides of a connection are independently-alive kinds → it's a **relation** (e.g. person "works at" company — two entities, linked).
+- One side is just wearing a hat with no independent lifecycle → it's a **facet** (e.g. "client" on a company — attach the role, don't create a new entity).
+- The connection itself accrues its own multi-entity lifecycle (stages, money, deadlines, outcomes) → it gets **promoted to its own kind**. `deal` is the precedent: a buyer × seller × stage relationship-thing has its own life (pipeline stage, amount, close date) independent of either party, so it's kept as a primary kind, never a facet.
+
+Attach when:
+
+- The thing is a role/hat the entity is wearing (client, partner, investor, prospect, sponsor) — it has no properties or lifecycle independent of the parent entity
+- AI-driven creation: resolve identity FIRST (strong signals — email, phone, url) before creating anything; if the entity already exists, `attach_facet` the new role onto it — never spin up a second entity for a hat
 
 Extend when:
 
-- The thing fits an existing category (a "client" is a kind of `contact` — consider inheritance)
+- The thing fits an existing category (a `client` **facet** is the role; if you instead need a distinct persisted sub-kind with its own fields, 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
+- None of the system profiles fits, and it's not a role of an existing entity
 - 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…)
+- It's a relationship-thing that accrues its own independent lifecycle (the `deal` precedent above)
 
-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.
+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. But if `client` is really just a role a `company` or `person` plays (no independent properties of its own), it shouldn't be a profile at all — it's a facet, attached via `attach_facet`, never a second entity.
+
+---
 
 ## Creating a new profile
 
@@ -101,6 +178,8 @@ POST /api/hub/profiles
 
 Then add properties one by one (see below). You do NOT declare properties inline on the profile — they're separate rows.
 
+---
+
 ## Creating properties
 
 ```json
@@ -131,6 +210,8 @@ For linking properties, always use `entity_id` with `targetProfileSlug` in const
 
 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`:
@@ -154,6 +235,8 @@ Use cases:
 
 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:
@@ -163,6 +246,8 @@ Profiles have an `entityScope` that determines where entities of that type live:
 
 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:
@@ -182,6 +267,8 @@ POST /api/hub/relation-defs
 
 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`.
@@ -213,7 +300,9 @@ Defining a relation def is rarely worth it — `related_to` + a property usually
 
 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
+---
+
+## Common mistakes — schema extension
 
 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`.
@@ -223,7 +312,9 @@ Defining a relation def is rarely worth it — `related_to` + a property usually
 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
+---
+
+## When you need more — schema extension
 
 - Full `valueType` reference + constraints + uiHints → **`property-types.md`**
 - Inheritance, overlay scope semantics, pod-wide caveats → **`property-types.md`** §Scope

package/skills/synap-schema/_order.txt

@@ -0,0 +1,13 @@
+profiles.md
+before-you-touch.md
+read-before-write.md
+discover-profiles.md
+extend-vs-create.md
+creating-profiles.md
+property-defs.md
+overlay-properties.md
+entity-scope.md
+relations.md
+worked-example.md
+common-mistakes.md
+more.md

package/skills/synap-schema/_skill.yaml

@@ -0,0 +1,22 @@
+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

package/skills/synap-schema/before-you-touch.md

@@ -0,0 +1,14 @@
+## 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.

package/skills/synap-schema/common-mistakes.md

@@ -0,0 +1,9 @@
+## Common mistakes — schema extension
+
+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.

package/skills/synap-schema/creating-profiles.md

@@ -0,0 +1,17 @@
+## 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.

package/skills/synap-schema/discover-profiles.md

@@ -0,0 +1,24 @@
+## 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.

package/skills/synap-schema/entity-scope.md

@@ -0,0 +1,8 @@
+## 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.

package/skills/synap-schema/extend-vs-create.md

@@ -0,0 +1,31 @@
+## When to extend an existing profile vs. create a new one vs. attach a facet
+
+There are three moves, not two. Before extending or creating, ask whether the thing is really a **role** the entity plays rather than a new kind of entity at all — that's a facet, and it's the move people skip.
+
+**Kind + Facets, the rule:** one entity = one kind (`profiles.profileKind = 'kind'`). Roles the entity plays — client, partner, investor, prospect — are role-profiles (`profileKind = 'role'`, `applicableKinds[]`) attached via `entity_facets`: additive, workspace-lensed, NOT entities. A facet cascades with its parent entity; only promote a role to a full kind if it accrues its own independent life.
+
+**The litmus test:**
+
+- Both sides of a connection are independently-alive kinds → it's a **relation** (e.g. person "works at" company — two entities, linked).
+- One side is just wearing a hat with no independent lifecycle → it's a **facet** (e.g. "client" on a company — attach the role, don't create a new entity).
+- The connection itself accrues its own multi-entity lifecycle (stages, money, deadlines, outcomes) → it gets **promoted to its own kind**. `deal` is the precedent: a buyer × seller × stage relationship-thing has its own life (pipeline stage, amount, close date) independent of either party, so it's kept as a primary kind, never a facet.
+
+Attach when:
+
+- The thing is a role/hat the entity is wearing (client, partner, investor, prospect, sponsor) — it has no properties or lifecycle independent of the parent entity
+- AI-driven creation: resolve identity FIRST (strong signals — email, phone, url) before creating anything; if the entity already exists, `attach_facet` the new role onto it — never spin up a second entity for a hat
+
+Extend when:
+
+- The thing fits an existing category (a `client` **facet** is the role; if you instead need a distinct persisted sub-kind with its own fields, 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, and it's not a role of an existing entity
+- 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…)
+- It's a relationship-thing that accrues its own independent lifecycle (the `deal` precedent above)
+
+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. But if `client` is really just a role a `company` or `person` plays (no independent properties of its own), it shouldn't be a profile at all — it's a facet, attached via `attach_facet`, never a second entity.

package/skills/synap-schema/more.md

@@ -0,0 +1,6 @@
+## When you need more — schema extension
+
+- 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/overlay-properties.md

@@ -0,0 +1,22 @@
+## 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.

package/skills/synap-schema/profiles.md

@@ -0,0 +1,3 @@
+# 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.

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

@@ -0,0 +1,29 @@
+## 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.

package/skills/synap-schema/read-before-write.md

@@ -0,0 +1,50 @@
+## Read before you write
+
+Synap data is a typed graph — never write blind. Before creating or updating an
+entity, work the loop the same way you'd read a file before editing it:
+
+1. **MAP** — know what types exist: `list_profiles` (the cheap map of entity
+   profiles), `list_views` for views.
+2. **SEARCH** — `search_unified({ query: <title>, collections: ["entities"] })`.
+   If a close match exists, LINK to it (relation or entity_id property) — do NOT
+   create a duplicate. Create only when there is genuinely no match.
+3. **READ THE SCHEMA** — before writing to a profile you haven't inspected this
+   session, call `get_profile({ slug })` for its real property defs (exact keys,
+   value types, enum options, link targets). For views, read the config
+   (`get_bento_schema`) before `create_view`.
+4. **WRITE INTO THE REAL FIELDS** — map each value to its correct typed property:
+   right `key`, valid `valueType` (dates as ISO, numbers as numbers), enum values
+   that satisfy the constraint, links via the property's `linksTo` target. Don't
+   invent property keys. A value with no matching property goes into
+   description/content, or propose a new one with `create_property_def` — never
+   drop it into a stray key.
+5. **CONNECT** — every new entity links to at least one other. Duplicates and
+   orphans are the two ways the graph degrades; avoid both.
+
+## Complete intent, governed outcome
+
+`title` + `content` is only a minimum payload, not Synap's data model. Once
+you have read the schema, send the complete intent that is known: `profileSlug`,
+title, typed `properties`, short `description`, long-form `content`, an existing
+`projectId`, links, and source/session provenance. Include role `facets` in the
+same composite plan whenever they must be reviewed with the entity.
+
+- **One entity with known fields and no creation-time role change** → use
+  `create_entity` / `POST /entities`.
+- **Several entities, facets, or relations that belong in one review** → use the
+  composite graph/capture-plan door, never a loose sequence of creates.
+- **Raw input whose structure is unknown** → use capture to produce a plan;
+  preserve an original file with `keepRaw` when supplied. Raw source is not the
+  same thing as an entity's edited content.
+
+Workspace is an explicit lens: omit it to read the pod/base schema and let the
+profile's placement rule apply. Pass a workspace only when the user or a
+reviewed routing decision actually selected it; then its overlays are valid.
+Never fill it from a configured/default workspace.
+
+Read the write receipt before continuing. `pending` means a proposal exists and
+no entity has materialized; `applied` means the reported operations completed;
+`partial` means independent follow-up operations failed and must be repaired or
+surfaced. Do not send a speculative second update merely because a write
+completed — enrich only when you learned genuinely new information or the
+receipt identifies a specific missing field.

package/skills/synap-schema/relations.md

@@ -0,0 +1,18 @@
+## 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).

package/skills/synap-schema/worked-example.md

@@ -0,0 +1,30 @@
+## 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.)

package/skills/synap-ui/SKILL.md

@@ -28,6 +28,8 @@ metadata:
 
 You build the surfaces the user sees: views over their data, bento dashboards, full workspaces tuned for a domain. The core rule: **emergent complexity.** A workspace is a lens; a view is a lens; a bento is a composition of lenses. Everything renders through the cell system, nothing is hardcoded.
 
+---
+
 ## Before you build anything
 
 Always inventory. Never hallucinate view types, widget kinds, or profiles.
@@ -49,6 +51,8 @@ GET /api/hub/views?userId={userId}&workspaceId={workspaceId}
 
 Widget definitions are the source of truth for which cells are installed and how to configure them. **Never guess cell kinds.** If a cell doesn't appear in the registry, don't reference it (unless it's a browser-native cell from the manifest).
 
+---
+
 ## Four things you can build
 
 1. **Views** — named queries + rendering config over entities of a given profile. Kanban of tasks, gallery of articles, calendar of events.
@@ -74,6 +78,8 @@ Widget definitions are the source of truth for which cells are installed and how
    - Always `GET /api/hub/widget-definitions` first — if a cell already covers the need, use it. New cell definitions are permanent; only create when genuinely novel.
    - For the full in-frame query/mutate/shell-actions API see the `synap` skill's **ViewFrame Cells** section (or load `synap-ui:SKILL` via `GET /api/hub/skills/system?sections=synap-ui:SKILL`).
 
+---
+
 ## View types (16 total, 12 implemented)
 
 Pick one that matches the data's shape AND the user's intent:
@@ -99,6 +105,8 @@ Pick one that matches the data's shape AND the user's intent:
 
 Decision: the data has statuses → `kanban`. Dates → `calendar`. Many columns → `table`. Mixed types → `masonry` or `bento`. Full reference in **`view-types.md`**.
 
+---
+
 ## Creating a view
 
 ```json
@@ -126,6 +134,8 @@ POST /api/hub/views
 
 The `config` shape varies by view type — kanban needs `groupBy`, calendar needs a date property, gallery needs an image property. When in doubt, fetch an existing view of the same type first and mirror its structure.
 
+---
+
 ## Bento layouts
 
 A bento is a 12-column react-grid-layout. Blocks reference **cells** by kind.
@@ -162,6 +172,8 @@ Block kinds:
 
 Full widget catalog in **`widget-catalog.md`**. Layout patterns in **`bento-recipes.md`**.
 
+---
+
 ## Creating or proposing a workspace
 
 **Always ask before creating.** Workspaces are big objects with profiles, views, members, bento, and seed data. Commit only after user confirms.
@@ -210,6 +222,8 @@ The canonical flow:
 
 4. **On no**, don't commit. Offer to adjust.
 
+---
+
 ## Proposing vs. extending
 
 Before proposing a new workspace, ask: does one of the user's existing workspaces fit? A "Content" workspace and a "Writing" workspace are the same lens. Adding a view to the existing workspace is almost always better than creating a new one.
@@ -222,6 +236,8 @@ Create new when:
 
 Otherwise: add a view, add a bento block, add properties — don't multiply workspaces.
 
+---
+
 ## Worked example — "Make me a CRM"
 
 1. Inventory. User already has `person`, `contact`, `company`, `deal`, `event` profiles (all system).
@@ -241,6 +257,8 @@ Otherwise: add a view, add a bento block, add properties — don't multiply work
 4. Show to user. Confirm.
 5. Commit via `POST /workspaces`.
 
+---
+
 ## Arranging a bento after creation
 
 ```json
@@ -250,7 +268,9 @@ POST /api/hub/views/{bentoViewId}/arrange
 
 `bento.arrange` is auto-approved by default. Safe to run without hesitation when the user rearranges or adds widgets.
 
-## Common mistakes
+---
+
+## Common mistakes — UI generation
 
 1. **Creating a workspace without asking.** Always propose + confirm. Workspaces are too big to auto-commit.
 2. **Guessing widget kinds.** Always `GET /widget-definitions` first. A `kind` that isn't in the registry won't render.
@@ -261,6 +281,8 @@ POST /api/hub/views/{bentoViewId}/arrange
 7. **Hardcoding config for view types you haven't checked.** Each view type's `config` shape is different. Get an example from `/views` first.
 8. **Forgetting entityScope implications.** A view on a pod-scope profile (`note`) will show entities from every workspace the user can access — filter appropriately if you want workspace-local results.
 
+---
+
 ## AI Companion integration
 
 When you create views or entities for the user inside the AI Companion, **always emit inline pattern chips** at the end of your reply so the user can jump directly to what you built.
@@ -289,7 +311,9 @@ These cell keys are registered in the browser app but may not appear in `GET /ap
 
 **Rule:** If a cell key is not in `GET /api/hub/widget-definitions`, do NOT reference it in bento config unless it is one of the four browser-native keys above. Unknown keys will silently fail to render.
 
-## When you need more
+---
+
+## When you need more — UI generation
 
 - Full per-view-type `config` shapes → **`view-types.md`**
 - Complete widget/cell catalog + configSchemas → **`widget-catalog.md`**

package/skills/synap-ui/_order.txt

@@ -0,0 +1,13 @@
+views.md
+before-you-build.md
+four-builds.md
+view-list.md
+creating-views.md
+bento-layouts.md
+workspaces.md
+proposing-vs-extending.md
+worked-example.md
+arranging-bento.md
+common-mistakes.md
+ai-companion.md
+more.md

package/skills/synap-ui/_skill.yaml

@@ -0,0 +1,23 @@
+name: synap-ui
+description: >
+  Use this skill when the user wants to BUILD interface in Synap — creating views,
+  dashboards, bento layouts, or whole workspaces over their data. Triggers:
+  "build me a dashboard for tracking X", "create a kanban for my projects",
+  "make a CRM workspace", "I want a feed view of my articles", "design a home
+  dashboard", "show my reading list as a gallery", "turn this into a
+  timeline/calendar/matrix", "generate a workspace for content creation /
+  sales / research / project management / fitness tracking", "arrange widgets
+  on my bento", "create a command / automation trigger". This skill PRESENTS
+  data — the underlying entities must already exist (use core `synap`) and
+  schema extensions happen via `synap-schema`. Always propose workspace creation
+  to the user before committing — workspaces are lenses on data, not silos,
+  and the user decides when a new lens is warranted.
+metadata:
+  openclaw:
+    requires:
+      env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
+    primaryEnv: SYNAP_HUB_API_KEY
+    homepage: https://synap.live
+    capabilities: [views, bento, workspaces, widgets]
+    os: [macos, linux, windows]
+    userInvocable: false