@synap-core/cli 1.10.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

@@ -1,180 +1,83 @@
-# Capture pipeline — reference
+# Capture — the one write door
 
-Use the capture pipeline when the user pastes a block of unstructured text (email, meeting transcript, LinkedIn bio, article, screenshot of a whiteboard) and you need to extract multiple entities with their relations.
+`synap_capture` (CLI: `synap capture`) is THE door for writing what you learn into the pod. **Never classify your input first.** The payload is a _gradient_ — send as much structure as you already have, in ONE call. Precision comes from sending MORE structure in the SAME call, never from picking a different tool and never from a second "commit" step.
 
-Chaining manual `POST /entities` + `POST /relations` for this is wasteful — the pipeline extracts everything in one server-side LLM call and returns proposals you can review before committing.
-
-## Two-step flow
-
-### 1. Structure the text
-
-```json
-POST /api/hub/capture/structure
-{
-  "userId":      "{userId}",
-  "workspaceId": "{workspaceId}",
-  "text":        "Had lunch with Sarah Chen from Acme Corp today. \
-                  She's leading their Series B and asked me to send \
-                  our sales deck by Friday. Mentioned her VP Engineering \
-                  Tom Walker also wants a demo.",
-  "context":     { "source": "chat", "channelId": "ch_…" },  // optional
-  "profileSlugs": ["person", "company", "task", "event"]     // optional filter
-}
 ```
-
-Response:
-
-```json
-{
-  "proposals": [
-    {
-      "tempId": "t1",
-      "profileSlug": "person",
-      "title": "Sarah Chen",
-      "properties": { "companyId": "t2" },
-      "action": "create"
-    },
-    {
-      "tempId": "t2",
-      "profileSlug": "company",
-      "title": "Acme Corp",
-      "properties": {},
-      "action": "create"
-    },
-    {
-      "tempId": "t3",
-      "profileSlug": "person",
-      "title": "Tom Walker",
-      "properties": { "role": "VP Engineering", "companyId": "t2" },
-      "action": "create"
-    },
-    {
-      "tempId": "t4",
-      "profileSlug": "task",
-      "title": "Send sales deck to Sarah",
-      "properties": {
-        "status": "todo",
-        "dueDate": "2026-04-24",
-        "assignee": null
-      },
-      "action": "create"
-    },
-    {
-      "tempId": "t5",
-      "profileSlug": "event",
-      "title": "Lunch with Sarah",
-      "properties": { "startDate": "2026-04-20", "attendees": ["t1"] },
-      "action": "create"
-    }
-  ],
-  "relations": [
-    {
-      "sourceTempId": "t4",
-      "targetTempId": "t1",
-      "relationType": "for_person"
-    },
-    {
-      "sourceTempId": "t4",
-      "targetTempId": "t5",
-      "relationType": "from_meeting"
-    }
-  ],
-  "followUp": "Should I also schedule a reminder to follow up with Tom?"
-}
+text        → free prose; the AI structures it into the right entities (raw text kept as provenance)
+entities[]  → you already know the kind + fields
+entities[] + relations[]  → a graph; refs link things that don't exist yet, reviewed as ONE proposal
 ```
 
-**`tempId` is only valid within this response.** It's used to link proposals together before they have real entity IDs.
+**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.
 
-**`action` can be:**
+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`.
 
-- `"create"` — new entity
-- `"update"` — existing entity found by title match; `existingEntityId` will be set
-- `"skip"` — duplicate already exists, nothing to do
+## One call → one receipt (no plan-and-commit)
 
-### 2. Execute (commit) after user confirmation
+You are an agent, so a capture is **one call**. The backend derives that from your identity (agent key ⇒ agent mode) — you never pass a mode. Policy decides the terminal automatically:
 
-Present the proposals to the user. Let them edit, remove, or add items. Then:
+- every op is safe/whitelisted → **auto-applied**
+- any op is destructive or non-whitelisted → the whole graph is **proposed** (atomic, all-or-nothing)
 
-```json
-POST /api/hub/capture/execute
-{
-  "userId":      "{userId}",
-  "workspaceId": "{workspaceId}",
-  "entities":    [ /* edited proposals array */ ],
-  "relations":   [ /* edited relations array */ ]
-}
-```
-
-Response:
+It always returns the same receipt:
 
 ```json
-{
-  "created":  [{ "tempId": "t1", "entityId": "ent_real_1" }, …],
-  "updated":  [{ "tempId": "t2", "entityId": "ent_existing" }, …],
-  "skipped":  [{ "tempId": "t5", "reason": "duplicate" }],
-  "relations": { "created": 2, "failed": 0 },
-  "status":   "approved"
-}
+{ "status": "applied" | "proposed" | "rejected",
+  "scope":  { "workspaceId": "…", "projectId": "…", "sessionId": "…" },
+  "writeReceipt": { … } }
 ```
 
-The executor goes through governance (see `governance.md`). Expect the same three `status` values.
-
-## Placement — existing lenses only
-
-Capture **never invents a workspace** (or other meta-structure) to "find a home"
-for extracted entities. Route into **existing** workspaces/projects/profiles the
-user already has — orient + list_profiles first when placement is ambiguous.
-Structure emerges progressively: capture into what exists; suggest a new profile only when the user repeatedly tracks a thing that fits none, and a view only once that profile has 3+ entities — never impose schema upfront. Missing structure is an escalation-ladder L2→L3 conversation (discover, then
-propose), not a side effect of capture. See `reflexes.md` / `escalation-ladder.md`.
+**`status: "proposed"` is SUCCESS**, not a failure — the write is queued for the user's review like a PR. Surface the `reviewUrl` and keep working. Never report "done" for a `proposed` result, and there is **no** separate step you must call after capture — the one call is the whole write.
 
-## When to use the pipeline vs. manual CRUD
+## capture vs create_entity
 
-| Situation                                                        | Use                                                 |
-| ---------------------------------------------------------------- | --------------------------------------------------- |
-| User pastes a chunk of text with multiple people/companies/tasks | Pipeline                                            |
-| User says "create a task to call Sarah at 3pm"                   | Manual create (1 entity)                            |
-| User forwards an email                                           | Pipeline                                            |
-| User asks "remind me to X"                                       | Manual create                                       |
-| OCR'd screenshot, meeting transcript, article body               | Pipeline                                            |
-| User edits an existing entity                                    | Manual PATCH                                        |
-| User wants to save a webpage they're on                          | Manual create (article) + optional capture for body |
+- **`synap_create_entity`** — use ONLY when you already have exactly ONE fully-structured, typed entity (a known `profileSlug` + fields). Deterministic, direct.
+- **`synap_capture`** — everything else: unstructured text, several entities, a graph, or **when in doubt**. It handles the whole gradient; you don't have to decide "loose fact vs structured object."
 
-Rule of thumb: **one intent, one call.** Multi-entity content, use the pipeline.
+## Worked examples
 
-**Degrade path (MCP `synap_capture`, the single-call door):** when the structuring pipeline fails or finds nothing to extract, it degrades to a single flat note carrying the raw text verbatim — it never drops the input. Use `synap_capture` only for genuinely unstructured input where you don't yet know the entities; if you already know the exact profileSlug and field values, call `synap_create_entity` instead (deterministic, direct write, no degrade path).
+```json
+// 1 — raw text (the AI structures it)
+{ "text": "Met Ada Lovelace of Acme at the conference — she owns their data platform and wants a demo in March." }
+
+// 2 — one structured entity with a long body
+{ "entities": [
+  { "profileSlug": "person", "title": "Ada Lovelace",
+    "properties": { "email": "ada@acme.com", "role": "Head of Data" },
+    "content": "## Notes\nOwns the data platform. Wants a March demo." }
+] }
+
+// 3 — a small graph (refs link entities that don't exist yet)
+{ "entities": [
+    { "ref": "p1", "profileSlug": "person",  "title": "Ada Lovelace", "properties": { "email": "ada@acme.com" } },
+    { "ref": "c1", "profileSlug": "company", "title": "Acme Corp",    "properties": { "website": "https://acme.com" } }
+  ],
+  "relations": [ { "sourceRef": "p1", "targetRef": "c1", "type": "works_at" } ] }
+```
 
-## Dedup within the pipeline
+## Dedup — strong signals only
 
-The pipeline does its own duplicate check per entity (by title + profileSlug within workspace). When it finds a match, `action` becomes `"update"` with `existingEntityId` set, so the real entity is updated in place, not duplicated.
+The dedup signals are the exact property keys `email`, `phone`, `website`, `linkedinUrl`, `twitterHandle`, `githubUsername`. Sending a URL under any other key (e.g. a bare `url`) is **not** a dedup signal and will duplicate the entity.
 
-You can still prefix with a manual search if you want to show the user "I found 3 existing people that might match" before running capture. But the pipeline alone is usually good enough.
+A same-title hit in a _different_ kind is **advisory** (`crossKindCandidates`), never an auto-merge. So "no exact match" does **not** mean "safe to create" when advisory candidates come back — review them first. To link to something that already exists, give it a `ref` plus `existingEntityId`.
 
-## Presenting proposals to the user
+## Name-refs — never ask for a UUID
 
-A good UX turn:
+Reference an existing project by **name**, not id — the server resolves `{ project: { name: "Synap" } }` against the caller's own projects. Exact match ⇒ it files there; no match ⇒ it proposes/creates, never silently mis-files. Never ask the user for a UUID.
 
-> I picked up **5 things** from that paste:
->
-> - **Sarah Chen** — person at Acme Corp (new)
-> - **Acme Corp** — company (new)
-> - **Tom Walker** — person at Acme (new)
-> - **Task**: Send sales deck to Sarah, due Friday
-> - **Event**: Lunch with Sarah today
->
-> Plus 2 connections: task → Sarah, task → lunch.
->
-> Ship it?
+## Placement — existing lenses only
 
-Keep the user in control. Don't auto-execute without confirmation unless the user explicitly told you to.
+Capture **never invents a workspace** (or other meta-structure) to "find a home". It routes into **existing** workspaces/projects/profiles — `synap orient` + `list_profiles` first when placement is ambiguous. Structure emerges progressively: capture into what exists; suggest a new profile only when the user repeatedly tracks a thing that fits none, and a view only once that profile has 3+ entities. Missing structure is an escalation-ladder L2→L3 conversation (discover, then propose), not a side effect of capture. `global: true` stores a pod-wide runbook (text lane only).
 
-## Edge cases
+## Rejection is a correct outcome — don't retry
 
-- **Empty text → empty proposals.** Don't call execute with zero entities.
-- **Ambiguous references ("he", "they").** The pipeline will often return null properties. Prompt the user to clarify before executing.
-- **Dates.** Always absolute in responses (ISO 8601). If the input says "Friday," the pipeline resolves it against today.
-- **Custom profiles.** If you want the pipeline to consider custom profiles, pass `profileSlugs` in the request. Otherwise it defaults to system profiles only.
-- **Rate limits.** 20 captures/hour per user. If you hit the limit, fall back to manual CRUD.
+`status: "rejected"` means the door protected the graph on purpose. Read the `reason` and act, don't loop:
 
-## Followup question
+- **`already-known`** — a lone entity carrying nothing but identity signals that already resolve to an existing one. Its id is returned; re-send with content / extra properties / relations to **enrich** it instead.
+- **`no-durable-content`** — nothing storable was sent (empty / whitespace / punctuation-only). Don't call capture with zero substance.
+- **`structuring-unavailable`** — text lane only: the AI structurer is down. Tell the user and retry later.
 
-The response includes a `followUp` field — a single sentence question the pipeline thinks is worth asking next. Surface it to the user verbatim. It's a cheap way to deepen capture without extra prompts.
+(There is no "recall-loop" rejection.)

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/common-mistakes.md

@@ -10,3 +10,4 @@
 8. **Forgetting that `GET /channels/personal` needs `hub-protocol.write`** scope — it's get-or-create, not a pure read.
 9. **Routing known-structure data through free-text capture.** If you already know the profileSlug + fields, create the entity directly — smart capture can degrade to a single flat note.
 10. **Paragraph session goals.** The goal is one line; put detail and deliverables in expectedOutputs.
+11. **Creating a `file`/`document`-kind entity to hold text you wrote.** A pitch deck, plan, or note body you authored is `content` on a real CONTENT-kind entity (`note`, `knowledge`, a domain kind) — Synap auto-materializes it into a document. `file` is only for real uploaded bytes you actually have; an agent with no filesystem almost never needs it.

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

@@ -0,0 +1,92 @@
+## Content OS — the editorial model
+
+Some workspaces run an editorial engine: `pillar`, `post`, `platform`, `newsletter`, plus the reused `campaign` and `sponsor`. Content OS is a **derived lens**, not a silo — the journey it can reason about is a function of what else exists in the pod. Understand this before proposing posts, pillars, or a content plan.
+
+**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` 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.
+
+**The journey layer (optional, additive):**
+
+- **`journey-stage`** — where a reader is. Each stage names the belief it installs, the doubt it dissolves, and the action that advances them. Unordered _tagging_.
+- **`series`** — an ordered curriculum, prerequisite-bearing: chapter by chapter.
+- **`offer`** — the thing being sold. Owned by the `foundation` workspace, pod-wide. **Frequently absent — see the degradation rule.**
+
+A post joins these through `post-stage`, `post-series`, `post-offer`; a repurposed post points at its source with `derived-from`.
+
+**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.
+
+- **No offer-bearing domain, no `offer` entities** → the journey is pure audience-building. **Do NOT invent commerce.** No CTA to a product that does not exist, no fabricated `offer`, no "book a call" the operator never mentioned. Reason on the curriculum and stage axes and stop there.
+- **`foundation` exists** → bind pillars to its real `audience`, `pain-point` and `positioning` entities rather than inventing personas. A pillar aimed at a persona you made up is worse than a pillar with no audience named.
+- **`journey-stage` / `series` / `offer` absent from `list_profiles`** → this pod runs the plain editorial model. Do not reference those slugs at all.
+
+Absence is information, not a hole to fill.
+
+## Pillars before posts
+
+A creator known for two to four themes compounds; one posting about everything stays noise. If the operator hands you a dozen post ideas but cannot name the themes underneath, surface THAT before filling the calendar. Every post you propose hangs off a pillar — `post-pillar` plus a `belongs_to_pillar` relation. An unpillared post is drift.
+
+## AI behavior — placing a post on the journey
+
+When the operator describes a content idea, propose the post WITH its placement — never a bare title:
+
+```json
+POST /api/hub/entities
+{ "userId": "{userId}", "workspaceId": "{wsId}",
+  "profileSlug": "post",
+  "title": "Why your pricing page loses the sale",
+  "properties": {
+    "post-status": "Idea",
+    "post-format": "Article",
+    "post-platform": "LinkedIn",
+    "post-pillar": "ent_pillar_positioning",
+    "post-stage": "ent_stage_evaluating"
+  }
+}
+
+POST /api/hub/relations
+{ "userId": "{userId}",
+  "sourceEntityId": "ent_post_pricing",
+  "targetEntityId": "ent_pillar_positioning",
+  "type": "belongs_to_pillar"
+}
+```
+
+Omit `post-stage` when no `journey-stage` exists, and omit `post-offer` when no `offer` exists. An empty commercial field is correct; a fabricated one is a defect. Use `derived-from` when the post is a repurpose of an existing one — one idea legitimately becomes a thread, a video, and a newsletter section.
+
+## Gap analysis — proposing the next piece
+
+"What should I write next" is an audit, not a brainstorm:
+
+1. **Read the corpus** — one batched `list_entities` pass over `post` and `pillar`. Never one call per post; that is a cost failure.
+2. **Map it** — each post to its pillar × its stage (or its place in a series). Build the grid before judging it.
+3. **Find the holes** — a pillar with nothing at the earliest stage; a stage every pillar skips; a series that stops mid-curriculum; a pillar whose last post is months old.
+4. **Propose the hole, not a topic** — "Pillar X has nothing that removes the pricing objection" beats "here are ten content ideas". Name the pillar, the stage, the belief to install, and the format.
+5. **Ground it** — a proposed post cites the pillar it serves and, when `foundation` exists, the real `audience` or `pain-point` entity it answers. Otherwise it is a guess dressed as a plan.
+
+Rank gaps by what the operator is actually known for, not what they wish they were known for.
+
+## Resolution discipline — resolve BEFORE you create
+
+Standard resolve-before-create applies (search once, batched, before proposing anything). Domain-specific matching keys: **platforms** resolve on handle or URL, **offers** on name, **pillars** on theme. Never placeholder — no pillar named "General", no `platform` for an account the operator doesn't have, no `offer` invented so a post has something to sell. Every post you propose attaches to at least a pillar; a post with no pillar and no stage is a note, not content.
+
+## Kind vs facets, and governed writes
+
+`sponsor` is a role-profile (`profileKind: role`) — per ENTITY MODEL, resolve the real company first, then `attach_facet`; a sponsoring company is never a second entity, and graph links attach to the parent, not the facet.

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.