@synap-core/cli 1.11.0 → 1.13.0

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/code-skills.md

@@ -0,0 +1,70 @@
+# code-skills
+
+How a CODE skill runs, so you can write one that works on the first approval. Author it with `synap_create_skill` (`code` + `body`); for a single deterministic HTTP call on an installed tool, `synap_create_verb` is simpler and needs no code.
+
+## The wrapper
+
+Your `code` is the BODY of an async function. The runtime wraps it as:
+
+```js
+(async function (args, context) {
+  /* your code */
+})(args, context);
+```
+
+- `args`: the run's parameters (what the caller passed to `synap_run_capability`), shaped by your `parameters` schema.
+- `context`: `{ userId, workspaceId, agentUserId }`.
+- `return` a JSON-serialisable value: it is the run's result. Top-level `await` works.
+
+## Limits
+
+- Memory: 64 MB per run (isolated-vm isolate).
+- Time: `timeoutSeconds`, default 30, at most 300. Set it on `synap_create_skill` when the skill waits on a slow provider.
+- Only ECMAScript built-ins plus `URL`, `URLSearchParams`, `TextEncoder`, `TextDecoder`, `btoa`, `atob`, `structuredClone`. There is NO `fetch`, `crypto`, `require`, `process` or `Buffer`: a skill that names one is refused at save time.
+
+## The host bridges
+
+### `callProvider(tool, method, path, body?, opts?)`
+
+Calls an installed tool's API with ITS credential (you never see the key).
+
+- `tool`: the tool's name, as `synap_list_capabilities` lists it (e.g. `"apify_api"`).
+- `method`: `"GET" | "POST" | "PUT" | "DELETE"`.
+- `path`: relative to the tool's base URL. If the base URL already ends in a version (`https://api.apify.com/v2`), do NOT repeat it: `"/acts/{actorId}/runs"`, not `"/v2/acts/…"`.
+- `opts`: `{ headers?, baseUrlOverride? }`.
+
+Returns `{ status, headers, body }` on success, or `{ proposed: true, proposalId }` when the call was filed for review. It THROWS `callProvider failed: …` on a provider or auth failure. Always branch on `proposed` before reading `body`.
+
+A GET runs inline. A POST/PUT/DELETE by an agent is governed: it proposes, UNLESS the tool is one the skill declared in `requiredTools` on `synap_create_skill`. Then the verb's own approval covers it, and the run does not stop for a second review.
+
+### `hubProtocol` (reads, as the user)
+
+- `hubProtocol.getEntities({ profileSlug, limit })`: entities of one kind.
+- `hubProtocol.search(query, opts)`: search across the pod.
+- `hubProtocol.getDocument(documentId)`: one document.
+
+Use the STORED slugs: `synap_define_kind` normalises them (`botScore` becomes `botscore`) and says so in its result.
+
+### `propose.entity({ profileSlug, title, properties?, description?, reasoning?, workspaceId? })`
+
+The governed write-back. Returns `{ status, proposalId, proposedEntityId, message }`. It goes through the same governance as any agent write: it proposes unless a rule lets it apply.
+
+### `secrets.get(ref)` and `host.fetch(url, opts)`
+
+`secrets.get("vault://…")` returns a granted secret, or `null`. `host.fetch` reaches only the hosts in the skill's approved `allowedHosts` and returns `{ ok, status, headers, body }` or `{ error, message }`. Prefer `callProvider` for an installed tool.
+
+## Before the first run
+
+1. The skill is born unapproved: the user approves the `skill/create` proposal. That one approval also turns it on: there is no separate enable step.
+2. It can still be off: when the person who approved may not turn verbs on (the approval result says so in `refusals`), or after its code changed (an edit turns it off until approved again). `synap_list_capabilities` then shows it as `blocked: "not_enabled"` with an `enable.url`: hand that link to the user instead of running it.
+3. `console.log` goes to the pod log, not to your result: return what you need to see.
+
+## Box scripts (packages, files, Python or Node)
+
+When the work needs packages, files or another language (chart a CSV with pandas, convert a file, scrape with a headless browser), write a BOX script instead: `synap_create_skill` with `executionMode: "box"`, the script in `code` (a whole program, not a function body) and `box: { language: "python" | "node", packages: [{ name, version }], hosts: ["api.example.com"], limits? }`.
+
+- It runs on the person's own computer, in a fresh box per run: no pod access, no secrets, network only to the `hosts` you declare (packages install from their registry first). Pin every package to an exact version.
+- Parameters arrive as `/in/parameters.json`; write output files to `/out` (they come back on the run and in the session). Print what you want the person to read: the log is kept.
+- `synap_run_capability` QUEUES it and returns `{ status: "queued", boxRunId }`: the run is not finished yet. Its log, files and exit code show on the run (Runs, the session's runs). The person must have turned on "Runs scripts" for one of their computers; otherwise the run is refused with that setting named: tell the person.
+- It has no preview: a dry-run answers that it runs only on the person's computer.
+- The reviewer approves the code, the packages and the hosts together; changing any of them needs a new approval. A box script cannot be declared `readOnly`.

package/skills/synap/concepts.md

@@ -0,0 +1,36 @@
+## 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                                                                        |
+| **Goal**            | project_tracks          | what goal am I pursuing?           | in ONE project; open while it matters, or its judge closes it with a verdict; criteria say when it is done; work = sessions · grow the newsletter · tools say "track" |
+| **Step**            | stage                   | where does this work stand?        | = the subject's status: move the thing, the step follows · legacy: steps of a goal started from a method                                                              |
+| **Work**            | focus_session           | what am I doing this sitting?      | one aim · 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 = goal 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 goal or project turns it on                                          |
+| **Inbox**           | needs-you signals       | what needs me?                     | one list: decisions, questions, routine changes, broken · not Work                                                                                                    |
+| **Questions**       | owed slot ask           | what did an agent ask me?          | an Inbox filter · answer it, the work resumes                                                                                                                         |
+| **Routine changes** | reversible proposal     | what can I approve in a batch?     | an Inbox filter · only reversible changes batch; undo says what it cannot restore                                                                                     |
+| **Broken**          | failed or stuck work    | what needs a fix?                  | an Inbox filter · a failed run, a stuck session                                                                                                                       |
+| **Library**         | data (things, files)    | what did we bring in?              | what you and your agents kept or made: things, files, imports · not a space                                                                                           |
+| **Unfiled**         | entity in no project    | what is not filed yet?             | things outside every project · file them into one                                                                                                                     |
+| **Agents**          | agent users + keys      | who acts for me?                   | Claude Code, Codex, any MCP client; each has its own page · not a Tool                                                                                                |
+| **Getting started** | first-run Home card     | what do I try first?               | goes away once done                                                                                                                                                   |
+
+Doors: `start_track`, `start_session`, `create_rule`, `attach_facet`, `update_entity` + `expectedStatus` (a status). How they fit (sizes, workers, tenses): `work-model`.
+
+A goal is a TRACK in every tool and field name (`start_track`, `trackId`); say "goal" to the person. A 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. A session's one-line `goal` is its **Aim** to the person. Detail: `from-intent`.
+
+Existing work can be filed into a goal with `update_session` `trackId` (proposed; the session keeps its space). Goal steps are legacy: only a goal started from a goal 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 **goal** for it on the project (`start_track`) and run this work template in it (`trackId`) — a goal 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:**