@synap-core/cli 1.11.0 → 1.12.2

package/skills/synap/_order.txt

@@ -1,6 +1,9 @@
 operating-mode.md
 reflexes.md
+concepts.md
+work-model.md
 escalation-ladder.md
+from-intent.md
 mental-model.md
 quick-reference.md
 lenses.md
@@ -12,6 +15,7 @@ linking-principle.md
 governance-rules.md
 capabilities.md
 writes.md
+writing-titles.md
 document-embeds.md
 creative-loop.md
 graph-gardening.md
@@ -35,3 +39,6 @@ recap.md
 showing.md
 user-model.md
 north-star.md
+processes.md
+mcp-remote-servers.md
+hand-off.md

package/skills/synap/_skill.yaml

@@ -12,7 +12,7 @@ description: >
   when the user asks about their own data. Do NOT use this skill for extending
   the schema (use synap-schema) or building dashboards and views (use synap-ui).
 metadata:
-  openclaw:
+  synap:
     requires:
       env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
       optional_env:

package/skills/synap/automations.md

@@ -39,6 +39,21 @@ Filters narrow the event to specific conditions:
 }
 ```
 
+### Status changes: the transitioned event
+
+A status move (a kind's own lifecycle, or a role's) emits ONE event, `entity.transition.completed` (the verb "transitioned"), whatever moved it: a person, a board drag, an agent through `update_entity` + `expectedStatus`, a sync. Filter it on `lifecycleProfile` (the kind or ROLE whose lifecycle moved; `profileSlug` stays the entity's kind even for a role) and `to` / `from` / `property`:
+
+```json
+{
+  "eventPattern": "entity.transition.completed",
+  "filters": { "lifecycleProfile": "lead", "to": "qualified" }
+}
+```
+
+Prefer it to `entity.update.completed` for any status. For a ROLE it is the only one: a role's status lives on its facet, so an update rule never sees it.
+
+**A worker usually beats a hand-written rule.** "When a post enters Review, run the review" is an activator on the playbook (`on: enters_status`), and "once 5 leads wait in qualified" is `on: count` + `min`; both compile to a governed rule like the one above, fire once per thing per transition, and are throttled by `maxPendingApprovals`. Write the rule by hand only for work no method owns. Workers: `processes`.
+
 ### Cron Expressions
 
 Standard 5-field cron (minute hour day month weekday):

package/skills/synap/capture.md

@@ -8,6 +8,11 @@ entities[]  → you already know the kind + fields
 entities[] + relations[]  → a graph; refs link things that don't exist yet, reviewed as ONE proposal
 ```
 
+**Titles and kinds:** each entity's title is linted — the receipt's `titleLint`
+(per `ref`) names what to rewrite, and `validate: true` shows it before you
+write. Status reports, decisions, open bugs and ideas are not `knowledge`; see
+`writing-titles.md` for the routing rule.
+
 There is no wrong door to pick, because there is one door. `text` alone is the old "capture"; `entities[]` is the old "rich create"; `entities[] + relations[]` is the composite graph. All three go through `synap_capture`.
 
 ## One call → one receipt (no plan-and-commit)

package/skills/synap/cli-operations.md

@@ -40,10 +40,11 @@ synap list entities --profile=task --workspace=<id> --json
 synap get entity <id> --json
 ```
 
-**Capturing a decision (the AI structures — it never `note`s):**
+**Recording a decision as its own graph entity:**
 
 ```bash
-synap capture --type decision --claim "Use Typesense for entity search" --json
+synap create entity --profile=decision --name="Use Typesense for entity search" \
+  --props='{"summary":"Use Typesense for entity search","decisionStatus":"accepted"}' --json
 # Retrieve later with the one read verb: synap ask "Typesense decision"
 ```
 
@@ -52,27 +53,32 @@ synap capture --type decision --claim "Use Typesense for entity search" --json
 **Structured knowledge (durable, typed, searchable — preferred for engineering learnings):**
 
 ```bash
-# Work lane (default): a domain gotcha/lesson/decision → knowledge entity in the ACTIVE workspace
-synap capture --type gotcha --claim "Hono static routes must come before /:id" \
-  --why "First-match routing; dynamic routes eat static ones" \
-  --tags "repo:synap-backend,layer:routing" --json
-
-synap capture --type lesson --claim "code-read ≠ runtime-true for library APIs" \
-  --evidence "tldraw 2.4.6 binding API changed silently from props.start.boundShapeId"
-
-# A quick decision-note is a typed knowledge entry (ek_type=decision):
-synap capture --type decision --claim "Use Typesense for entity search" \
-  --why "pgvector deferred to V1; Typesense ships now" --json
-
-# Global lane: a runbook/best-practice that holds across ALL projects → pod-wide knowledge_keys
-synap capture --global --type reference --claim "Always fix the canonical path, never a workaround" \
+# Work lane: one explicit Knowledge form. Keep the Markdown body on the
+# linked document; these properties remain compact/queryable metadata.
+synap create entity --profile=knowledge --name="Hono static route ordering" \
+  --workspace=<id> \
+  --props='{"knowledgeForm":"caution","ek_claim":"Static routes must come before /:id","ek_tags":["repo:synap-backend","layer:routing"]}' \
+  --content=$'## Why\\n\\nStatic routes must come before `/:id`.' --json
+
+synap create entity --profile=knowledge --name="Verify library APIs at runtime" \
+  --workspace=<id> \
+  --props='{"knowledgeForm":"fact","ek_claim":"Code-read is not runtime-true for library APIs"}' \
+  --content=$'Validate the installed version before depending on an API.' --json
+
+# A Decision is its own lifecycle entity; link it to the supporting Knowledge.
+synap create entity --profile=decision --name="Use Typesense for entity search" \
+  --props='{"summary":"pgvector deferred to V1; Typesense ships now","decisionStatus":"accepted"}' --json
+
+# A Reference is source material, not a Knowledge form. Create/use a source
+# entity or document and link it as evidence; global runbooks remain knowledge_keys.
+synap capture --global "Always fix the canonical path, never a workaround" \
   --key "principle:root-cause" --json
 
 # Retrieve any of it later with the one read verb (it spans every lane):
-synap ask "hono routing gotcha" --json
+synap ask "hono routing caution" --json
 ```
 
-`synap capture --type` writes a typed **`knowledge`** entity in the **active workspace** (the Work lane); `ek_type` (gotcha|lesson|decision|reference) discriminates the kind — **one store, type tags, not a residual dump**. It's workspace-scoped, so the active workspace supplies the domain — a Builder gotcha ≠ a marketing one (there is no `engineering_knowledge`). Add **`--global`** to write a pod-wide cross-cutting runbook to `knowledge_keys` instead. A formal **decision RECORD** (rationale, alternatives, superseded-by lifecycle) is a different artifact — use smart `synap capture "<free text>"` or `synap create entity --profile=decision`. Retrieve everything with `synap ask`.
+`knowledge` has exactly one canonical `knowledgeForm`: `fact`, `caution` or `convention` (a legacy `insight` is read as `fact`). It is workspace-scoped, so the active workspace supplies the domain. `ek_claim` (the "Claim") is required — the full sentence; the title is its short handle, never the claim cut off. Readable long form belongs in the entity's linked Markdown document. Status reports, decisions, open problems (`issue`) and ideas are not knowledge — see `writing-titles.md`. A formal **Decision** has its own rationale/lifecycle entity, and a **Reference** is source material linked as evidence — neither is a Knowledge form. The legacy `synap capture --type gotcha|lesson|decision|reference` command is still accepted for compatibility, but new automation must use the canonical entity properties above. Retrieve everything with `synap ask`.
 Use `capture` for anything worth remembering across sessions and projects.
 
 **Open (the one display door):**

package/skills/synap/concepts.md

@@ -0,0 +1,28 @@
+## Concepts — one word per idea
+
+The ONE glossary; other skills point here. Word = what the user sees; internal = tools and tables.
+
+| Word          | Internal                | Answers                            | Test · e.g. · not                                                                                                                                                    |
+| ------------- | ----------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Space**     | workspace               | which domain: kinds + tools?       | owns kinds, never done · CRM · not a project or method; findable, not emphasised                                                                                     |
+| **Project**   | project                 | what am I committed to, with whom? | ends with the commitment; spans spaces · a launch · not a task, method, or the owner's company                                                                       |
+| **Track**     | project_tracks          | what lasting intent am I pursuing? | inside ONE project, lasts, never completes; direction, instructions, goal; turns workers on; work in it = sessions · grow the newsletter · no stages                 |
+| **Step**      | stage                   | where does this work stand?        | = the subject's status: move the thing, the step follows · legacy: steps of a track started from a method                                                            |
+| **Work**      | focus_session           | what am I doing this sitting?      | one goal · no noun: "Start work"                                                                                                                                     |
+| **Template**  | playbook                | how do I reuse it?                 | kind DERIVED, never declared: scope session = work template (a method a session or worker follows), project = track template (legacy); also space and rule templates |
+| **Pack**      | suite                   | which templates come together?     | a bundle; depends on space templates, never creates a space                                                                                                          |
+| **Rule**      | automation              | what runs by itself, when?         | standing · "every Monday…" · not Approvals                                                                                                                           |
+| **Approvals** | governance rules        | which AI writes wait for me?       | decides review vs auto, does no work                                                                                                                                 |
+| **Tools**     | capability, skill, tool | what can it act with?              | one word; the detail shows the kind                                                                                                                                  |
+| **To review** | proposal                | what awaits my approval?           | `proposed` is success                                                                                                                                                |
+| **Role**      | role profile + facet    | which hat does it wear?            | one role per name, pod-wide; spaces add properties by overlay; its entities show in all · client · never a twin                                                      |
+| **Thing**     | entity                  | what is being worked on?           | one kind, maybe roles · a post, a lead · never a twin for a hat                                                                                                      |
+| **Status**    | lifecycle               | where does it stand?               | ONE list per kind or role, declared on its profile; category open·active·paused·done·lost · moved only through the door (`expectedStatus`)                           |
+| **Pipeline**  | pipeline view           | what is in each status?            | computed from a lifecycle, never created · not an object                                                                                                             |
+| **Worker**    | playbook activator      | what starts work by itself?        | a method + trigger (enters status · schedule · count · manual) + size (per thing · per batch); a track or project turns it on                                        |
+
+Doors: `start_track`, `start_session`, `create_rule`, `attach_facet`, `update_entity` + `expectedStatus` (a status). How they fit (sizes, workers, tenses): `work-model`.
+
+A lasting goal on a project: `list_tracks` → none? `start_track` (`name`, `direction`, a `kpi` only if the person names one; no method needed); work in it = `start_session` + `trackId`, as many sessions as it takes. Detail: `from-intent`.
+
+Existing work can be filed into a track with `update_session` `trackId` (proposed; the session keeps its space). Track stages are legacy: only a track started from a track template has them (`start_stage_session`; never `advance_track` without the user).

package/skills/synap/content-os.md

@@ -5,7 +5,7 @@ Some workspaces run an editorial engine: `pillar`, `post`, `platform`, `newslett
 **The editorial core:**
 
 - **`pillar`** — a recurring theme the audience knows the operator for. Two to four, not twelve. `pillar-status` (Active, Developing, Paused, Retired), `pillar-goal`, `pillar-formats`, `posting-frequency`.
-- **`post`** — the atomic unit. `post-status` moves Idea → Briefed → In Draft → Review → Scheduled → Published → Archived. Plus `post-format`, `post-platform`, `publish-date`, `post-hook`, `post-cta`; measured by `engagement-score` and `post-reach`.
+- **`post`** — the atomic unit. `post-status` is the post's ONE lifecycle: Idea → Briefed → Scripted → In Draft → Review → Scheduled → Published, or Archived (see below). Plus `post-format`, `post-platform`, `publish-date`, `post-hook`, `post-cta`; measured by `engagement-score` and `post-reach`.
 - **`platform`** — a publishing account (social, newsletter publication, podcast). Carries its own cadence and audience metrics.
 - **`newsletter`** — one issue of the owned channel. `newsletter-status`, `newsletter-pillar`.
 - **`campaign`** and **`sponsor`** — reused from marketing / foundation, not owned here.
@@ -20,6 +20,15 @@ A post joins these through `post-stage`, `post-series`, `post-offer`; a repurpos
 
 **Two axes, both optional, composable:** CURRICULUM (`series` — ordered, "which chapter is this?") and AUDIENCE STAGE (`journey-stage` — an unordered tag, "where is the reader?"). A post carries at most one of each. With neither, Content OS still works exactly as a post tracker — that is a valid end state, not an incomplete one.
 
+## The post lifecycle and who moves it
+
+The lifecycle is declared on the `post` kind (work model: `load_skill system/synap/work-model`). Categories: Idea = open; Briefed, Scripted, In Draft, Review, Scheduled = active; Published = done; Archived = lost and **human-only**.
+
+- **Nothing publishes itself.** Your move to Published is a proposal the person approves on the preview. Never set Archived.
+- **Every move goes through the door:** `update_entity` with `post-status` = the new option AND `expectedStatus` = the status you read. A `conflict` means someone moved it; re-read. Never invent an option.
+- **Workers, as the model maps them:** **Draft** (per post, when it enters Briefed) · **Review prep** (per post, when it enters Review; ends by proposing the publish date) · **Ideas** (per batch, weekly; creates posts at Idea). Today the catalog ships them as Produce Content (enters Briefed, a person approves the script and the draft), Repurpose (enters Published) and Plan Next Content (weekly, off until the operator turns it on).
+- **Results go on each post**, not only in a summary. "What to make next" = read the pipeline (the Posts board): gaps per pillar, posts waiting per status.
+
 ## The degradation rule — check before you assume
 
 Read the world before you reason about it: `list_profiles` tells you the vocabulary actually provisioned, and the `## Pod Domains` block in your context tells you which domains exist.

package/skills/synap/creative-loop.md

@@ -6,12 +6,12 @@ The loop has three moves that compound. Each takes a one-off act and, if it's wo
 
 | Do-once (author)                        | → Crystallize (curate)              | Tool                          |
 | --------------------------------------- | ----------------------------------- | ----------------------------- |
-| Work a multi-step goal in a **session** | → a **playbook** (the process)      | `promote_session_to_playbook` |
+| Work a multi-step goal in a **session** | → a **work template** (the process) | `promote_session_to_playbook` |
 | Show a result in a **cell**             | → a **renderer** for an entity type | `promote_cell_to_renderer`    |
 
 ### 1. Open a session for real work
 
-When the task is a unit of work with a deliverable — research, a build, an investigation, a sprint — and there's no active session, **`start_session`** with a clear `goal` and `expectedOutputs`. The session is the spine that accrues results (see the focus-sessions skill). Don't open one for a one-shot lookup or a casual reply.
+When the task is a unit of work with a deliverable — research, a build, an investigation, a sprint — and there's no active session, **`start_session`** with a clear `goal` and `expectedOutputs`. The start door hands back the pod's matching playbooks (`playbooks.candidates`) — read them before working ad-hoc, and start again with `templateId` when one fits. The session is the spine that accrues results (see the focus-sessions skill). Don't open one for a one-shot lookup or a casual reply.
 
 ### 2. Create a cell to REPORT — don't dump data into chat
 
@@ -22,22 +22,27 @@ When you have something to _show_ the user — a list of leads, a summary, a com
 
 ### 3. Promote a good cell to a renderer — recurring presentation
 
-When a cell is a _good, recurring way to present a whole entity type or step_ — e.g. every `bookmark`'s detail view, every `lead`'s list row — promote it with `promote_cell_to_renderer`:
+Every kind already has a built-in card — the readable-first default nobody has to ask for (a brand-new user kind even gets one AUTOMATICALLY, built from its schema). Don't reach for this move by default; reach for it when the user explicitly asks for a different look and a cell has already proven it once.
 
-- Pick the `profileSlug` (the entity type), the `slot` (`list` | `detail` | `dashboard`), and the `cellKey` from `create_cell`.
-- This is **governed**: for you it returns `{ status: "proposed", proposalId }`. That is the point — you author the renderer, the user reviews and curates it before it becomes every entity's view. Surface the proposal plainly ("I've proposed this as the detail view for bookmarks — review it when you like"), don't treat it as a failure.
-- Use `scope: "pod"` only when the presentation should apply in every workspace; default to workspace scope.
+When a cell is a _good, recurring way to present a whole entity type or step_ — e.g. every `bookmark`'s small card, every `lead`'s list row — promote it with `promote_cell_to_renderer`:
 
-### 4. Promote a finished session to a playbook — recurring process
+- Pick the `profileSlug` (the entity type), the `slot` (`list` | `card` | `detail` | `dashboard` — `card` is the small embeddable block; most "change how X looks" requests mean this one, not `detail`), and the `cellKey` from `create_cell`.
+- This is **governed**: for you it returns `{ status: "proposed", proposalId }`. That is the point — you author the renderer, the user reviews and curates it before it becomes every entity's view. Surface the proposal plainly ("I've proposed this as the card for bookmarks — review it when you like"), don't treat it as a failure.
+- Use `scope: "pod"` only when the presentation should apply in every workspace; default to workspace scope. Bind PER KIND — never as a blanket replacement for every kind's card.
+- Once it lands, tell the user where to find or revert it: **"⋯ → Customize display"** on that kind's page.
 
-When the session is done **and the work was a repeatable process** (not a one-off), promote it with `promote_session_to_playbook({ sessionId })`. This captures the goal, tasks, expected outputs, and steps as a reusable session template — so next time the process starts pre-built instead of from scratch.
+### 4. Promote a finished session to a template — recurring process
+
+When the session is done **and the work was a repeatable process** (not a one-off), promote it with `promote_session_to_playbook({ sessionId })`. This captures the goal, tasks, expected outputs, and phases as a reusable **work template** (one sitting) — so next time the process starts pre-built instead of from scratch. Words: `concepts`.
 
 - Do this at the _end_, once the promised outputs are produced and verified.
-- Judge repeatability honestly: a bespoke, never-again investigation is not a playbook. A "weekly competitor scan" or "new-client onboarding" is.
+- Judge repeatability honestly: a bespoke, never-again investigation is not a template. "New-client onboarding" is a work template.
+- If it should **run on its own** ("a weekly competitor scan"), that is a **Rule** that starts the work each cycle (`create_rule`), not a template alone.
+- If the work is a **lasting goal** worked over weeks, start a **track** for it on the project (`start_track`) and run this work template in it (`trackId`) — a track needs no template of its own.
 - Governed like the others — `promoted` (applied) or `proposed` (awaiting review) are both normal.
 
 ### The symmetry
 
-Sessions and cells are the two things you _do_; playbooks and renderers are the two things you _keep_. The instinct to build: **first do it once concretely, watch it work, then offer to crystallize it** — and let the user decide what becomes standing config. Never crystallize speculatively before the one-off has proven itself.
+Sessions and cells are the two things you _do_; templates and renderers are the two things you _keep_. The instinct to build: **first do it once concretely, watch it work, then offer to crystallize it** — and let the user decide what becomes standing config. Never crystallize speculatively before the one-off has proven itself.
 
 This is escalation ladder **L4**: crystallize only after proof. Blocked/missing structure climbs L2→L3 first (`escalation-ladder.md`); L4 is the success path, not a substitute for discovery.

package/skills/synap/crm.md

@@ -1,24 +1,23 @@
-## CRM Workspaces — 4-Entity Model
+## CRM Workspaces — identity, roles, deals
 
-Some workspaces use a CRM data structure with four entities: `person` and `company` (identity records), `deal` (pipeline record), and `client` (post-win relationship marker). Understand this pattern when proposing lead captures, deal updates, or campaign membership.
+A CRM workspace holds `person` and `company` (identity records), the `lead` and `client` ROLES those identities wear (facets, not entities), and `deal` (the sale). Understand this pattern when proposing lead captures, deal updates, or campaign membership.
 
-**The model:**
+**The model (one lifecycle per kind or role):**
 
 - **`person` + `company`** — Identity only, no sales state. Persist across deals.
-- **`deal`** — Pipeline record with `dealStage` property (lead, contacted, qualifying, proposal, negotiating, won, lost, inactive). Represents what people often call a "lead" (when stage=lead). Linked to person/company via `linked_to_deal` relation.
-- **`client`** — Post-win relationship marker. Created automatically when deal transitions to stage=won. Status: active, paused, or churned. Linked via `is_client` (party → client) and `produced_by_deal` (deal → client).
-- **`journey`** — Documents anchored to a deal (not a person). Linked via `has_journey`.
+- **`lead` role** — qualification only. Attach it with `attach_facet` to the person/company; its status is `leadStage`: new, researching, outreach, engaged, qualified, nurturing, converted, disqualified.
+- **`deal`** — the sale, and nothing before it. Its one lifecycle is `commercialStage`: draft, proposed, negotiating, won, lost. Linked to person/company via `linked_to_deal`. Open a deal only when a person chose to pursue the lead.
+- **`client` role** — attached to the party when a deal is won. Status `clientStatus`: prospect, active, paused, former, churned. An ended relationship is `clientStatus: churned` — never a separate `churned` role.
 
 **AI behavior — lead capture:**
 
-When the user describes a lead (inbound person, prospect, or company lead), propose the full bundle:
+When the user describes a lead (inbound person, prospect, or company lead):
 
-1. Create `person` entity (if not exists) with email, role, company name
-2. Create `company` entity (if not exists)
-3. Create `deal` entity with `dealStage: "lead"` and `estimatedValue` (if known)
-4. Create `linked_to_deal` relation connecting person/company to deal
+1. Resolve the person/company first (email, domain, url); create only if none matches
+2. `attach_facet` the `lead` role with `leadStage: "new"`
+3. Do NOT open a deal yet — a deal starts when the person decides to pursue
 
-Never create a person with a sales-state flag. The deal is the lead container.
+A booked call (Cal.com) is lead evidence, not a deal. The booking already resolves the person (and company), attaches `lead` at `leadStage: "engaged"` — moving an earlier lead forward, never a qualified, nurturing, converted or disqualified one back — and links the call as an `event` `attended_by` the person. Do not open a deal for a booking.
 
 ```json
 POST /api/hub/entities
@@ -27,50 +26,19 @@ POST /api/hub/entities
   "title": "Alice Johnson",
   "properties": { "email": "alice@acme.com", "role": "VP Engineering" }
 }
-
-POST /api/hub/entities
-{ "userId": "{userId}", "workspaceId": "{wsId}",
-  "profileSlug": "deal",
-  "title": "Acme prospect",
-  "properties": { "dealStage": "lead", "estimatedValue": 50000 }
-}
-
-POST /api/hub/relations
-{ "userId": "{userId}",
-  "sourceEntityId": "ent_person_alice",
-  "targetEntityId": "ent_deal_acme",
-  "type": "linked_to_deal"
-}
+// then attach_facet { entityId: "ent_person_alice", facetSlug: "lead", properties: { "leadStage": "new" } }
 ```
 
-**AI behavior — moving deals to won:**
+**AI behavior — pursue, then win:**
 
-When a deal transitions to `dealStage: "won"`, also propose client creation if not yet linked:
+When the person chooses to pursue: create the `deal` at `commercialStage: "draft"`, link the party with `linked_to_deal`, and set the lead's `leadStage: "converted"`. When a person confirms the deal is won: set `commercialStage: "won"` and `attach_facet` the `client` role on the party with `clientStatus: "active"`. Moving a deal to won or lost is a person's call — propose it, never decide it.
+
+Every status move goes through the one door (work model: `load_skill system/synap/work-model`): send the new value AND `expectedStatus` = the status you read (`update_entity` for the deal's `commercialStage`; `update_facet` for a role's status where your tools list it). A `conflict` means someone moved it: re-read. `converted` and `won` are done, `lost` and `disqualified` are lost: an agent's move into them proposes, and `disqualified` is a person's call only.
 
 ```json
 PATCH /api/hub/entities/ent_deal_acme
-{ "properties": { "dealStage": "won" } }
-
-POST /api/hub/entities
-{ "userId": "{userId}", "workspaceId": "{wsId}",
-  "profileSlug": "client",
-  "title": "Acme (active)",
-  "properties": { "clientStatus": "active" }
-}
-
-POST /api/hub/relations
-{ "userId": "{userId}",
-  "sourceEntityId": "ent_person_alice",
-  "targetEntityId": "ent_client_acme",
-  "type": "is_client"
-}
-
-POST /api/hub/relations
-{ "userId": "{userId}",
-  "sourceEntityId": "ent_deal_acme",
-  "targetEntityId": "ent_client_acme",
-  "type": "produced_by_deal"
-}
+{ "properties": { "commercialStage": "won" } }
+// then attach_facet { entityId: "ent_company_acme", facetSlug: "client", properties: { "clientStatus": "active" } }
 ```
 
 **AI behavior — campaign membership:**
@@ -96,8 +64,9 @@ POST /api/hub/relations
 
 **Property names:**
 
-- `dealStage` (not `crmStatus` or `status`) — values: lead, contacted, qualifying, proposal, negotiating, won, lost, inactive
-- `clientStatus` (post-win only) — values: active, paused, churned
+- `commercialStage` on `deal` (never `dealStage`, `stage`, `crmStatus` or `status` — retired) — draft, proposed, negotiating, won, lost
+- `leadStage` on the `lead` facet — new, researching, outreach, engaged, qualified, nurturing, converted, disqualified
+- `clientStatus` on the `client` facet — prospect, active, paused, former, churned
 - Identities (person, company) carry no sales state
 
 **Why separate identity from state:**