@synap-core/cli 1.8.0 → 1.10.0

package/skills/synap/writes.md

@@ -0,0 +1,156 @@
+## Core writes
+
+### Create an entity (schema-first, complete intent)
+
+Before this call, use `/discover?userId=…&profileSlugs=<kind>` to read the
+real fields, required/default values, constraints and reference targets. Omit
+`workspaceId` for the pod/base schema and normal profile placement; pass it
+only when the user or routing decision explicitly selected that workspace.
+
+```json
+POST /api/hub/entities
+{
+  "userId": "{userId}",
+  "profileSlug": "task",          // from /discover — never guess
+  "title": "Weekly team sync",
+  "description": "Recurring planning sync",
+  "properties": { "status": "todo", "dueDate": "2026-07-21" },
+  "content": "# Agenda\n- Priorities\n- Risks",
+  "projectId": "{existingProjectId}",
+  "source": "agent"
+}
+```
+
+The response has legacy `status`/`id` fields plus `writeReceipt`:
+`pending` means a proposal exists and no entity is live; `applied` means the
+reported direct write completed; `partial` means a follow-up (for example a
+facet) failed after the entity applied. Never claim completion from `pending`,
+and only enrich again when the receipt identifies a real missing fact.
+
+For several entities, creation-time roles/facets, or relations that need one
+review, submit one `POST /api/hub/capture/graph` plan instead of sequencing
+independent creates. It returns a pending receipt and materializes on human
+approval.
+
+### Update an entity
+
+```json
+PATCH /api/hub/entities/{entityId}
+{ "userId": "{userId}", "title": "…", "properties": { "status": "done" } }
+```
+
+**Properties are deep-merged — send only the keys you want to change.** An update with `{ "status": "done" }` leaves all other properties untouched. You never need to re-send the full properties object.
+
+### Create a document (attach to an entity)
+
+```json
+POST /api/hub/documents
+{
+  "userId": "{userId}",
+  "workspaceId": "{workspaceId}",
+  "title": "Meeting notes — 2026-04-20",
+  "content": "# Attendees\n- …\n\n# Decisions\n- …",
+  "type": "markdown",              // "markdown" | "html" | "text" | "code"
+  "entityId": "ent_event_..."      // attach to an entity for context
+}
+```
+
+`type: "html"` stores self-contained HTML. The browser renders it via the `html-doc` cell in a sandboxed iframe. Use for AI-generated reports, rich visualisations, custom charts, or anything beyond markdown.
+
+**Full HTML cell workflow** (AI → visible custom UI in any bento):
+
+```json
+// 1. Create the HTML document
+POST /api/hub/documents
+{ "userId": "{userId}", "workspaceId": "{workspaceId}",
+  "title": "Q2 Revenue Report", "type": "html",
+  "content": "<!DOCTYPE html><html>…</html>",
+  "entityId": "ent_project_..." }
+// → { "document": { "id": "doc_abc" }, ... }
+
+// 2. Place the html-doc cell in any bento view
+POST /api/hub/views/{bentoViewId}/arrange
+{ "userId": "{userId}", "workspaceId": "{workspaceId}",
+  "widgets": [
+    { "id": "b1", "kind": "html-doc", "config": { "documentId": "doc_abc" },
+      "layout": { "x": 0, "y": 0, "w": 8, "h": 6 } }
+  ] }
+
+// 3. Update the HTML (cell auto-refreshes)
+PATCH /api/hub/documents/doc_abc
+{ "userId": "{userId}", "content": "<!DOCTYPE html>…updated…</html>" }
+```
+
+The iframe uses `sandbox="allow-scripts"` — scripts run but have no same-origin access to the parent app. The HTML is fully isolated.
+
+### Update a document (title and/or content)
+
+```json
+PATCH /api/hub/documents/{documentId}
+{
+  "userId": "{userId}",
+  "title": "Updated title",          // optional
+  "content": "# Full replacement\n…" // full string — not a diff
+}
+```
+
+Content is a **full replacement**, not a patch. Fetch the current content first if you want to append: `GET /api/hub/documents/{id}?userId={userId}` → `.content`, append, then PATCH.
+
+The reverse lookup is `entities WHERE documentId = ?`. Always attach the document to a meaningful entity (the meeting event, the project, the person) — a floating document is another orphan.
+
+### Store a fact (memory) — use sparingly
+
+```json
+POST /api/hub/memory
+{ "userId": "{userId}", "fact": "User prefers async communication over meetings" }
+```
+
+Always auto-approved. **Memory is for loose, unstructured, hard-to-title facts only.** The seductive thing about memory is it has zero friction — no dedup, no linking, no proposals. That makes it easy to misuse.
+
+**The test:** if the user later asked "show me all X," can memory answer? Memory can only keyword-match — it has no structure. So:
+
+| Input                                                   | Use                                                             |
+| ------------------------------------------------------- | --------------------------------------------------------------- |
+| "User prefers async communication"                      | memory — it's a preference                                      |
+| "Garage code is 4321"                                   | memory — throwaway fact                                         |
+| "Should we use LangGraph or CrewAI for Eve?"            | **entity `question`** — substantive inquiry, start of flow      |
+| "Here's what I found comparing LangGraph and CrewAI…"   | **entity `research`** — investigation with sources + conclusion |
+| "We decided to use LangGraph over OpenClaude's native…" | **entity `decision`** — has title, rationale, project           |
+| "Key insight: tasks need better retry logic"            | **entity `note` with tag "insight"** + link to project          |
+| "John is now head of engineering at Acme"               | **update `contact` entity** — that's a property change          |
+| "Launch date moved to May 15"                           | **update `project` entity** — change the startDate              |
+| "Action item from meeting: ship MVP by Friday"          | **entity `task`** linked to the `event` (meeting)               |
+| "Agreed with Sarah: we'll split backend & frontend"     | **entity `decision`** linked to Sarah + the project             |
+
+**Rule of thumb:** if it has a title-worthy noun OR context to link to (a project, a person, a meeting) OR a lifecycle (status/supersession) — it's an entity, not memory. Memory is the fallback, not the default.
+
+**For decisions specifically** — use the `decision` system profile:
+
+```json
+POST /api/hub/entities
+{
+  "userId": "{userId}",
+  "profileSlug": "decision",
+  "title": "Use LangGraph orchestrator over OpenClaude native",
+  "properties": {
+    "decisionStatus": "accepted",
+    "decidedAt": "2026-04-20",
+    "summary": "Dedicated orchestrator service; OpenClaude CLI as UX",
+    "rationale": "Separates the Orchestration Brain (LangGraph) from the UX (OpenClaude CLI).",
+    "alternatives": "Standardize entirely on OpenClaude's multi-agent logic.",
+    "projectId": "ent_project_eve"
+  }
+}
+```
+
+This creates a first-class decision entity linked to Project Eve. It shows up in traversals, can be superseded later (`supersededBy: newDecisionId`), and survives governance. Memory can't do any of that.
+
+### Post to the user's personal channel
+
+```
+GET  /api/hub/channels/personal?userId={userId}&workspaceId={workspaceId}
+       → { id, name, … }       (get-or-create, needs hub-protocol.write scope)
+
+POST /api/hub/threads/{threadId}/messages
+       { "userId": "{userId}", "role": "user", "content": "…" }
+```

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).