@synap-core/cli 1.10.0 → 1.12.2

package/templates/automations/bookmark-enrichment.automation.json

@@ -4,41 +4,318 @@
   "status": "active",
   "triggerConfig": {
     "eventPattern": "entity.create.completed",
-    "filters": { "profileSlug": "bookmark" }
+    "filters": {
+      "profileSlug": "bookmark"
+    }
   },
   "flowDefinition": {
     "nodes": [
       {
         "id": "trigger",
         "type": "trigger",
-        "position": { "x": 0, "y": 0 },
+        "position": {
+          "x": 0,
+          "y": 0
+        },
         "data": {
           "triggerType": "event",
           "label": "Bookmark created",
           "config": {
             "eventPattern": "entity.create.completed",
-            "filters": { "profileSlug": "bookmark" }
+            "filters": {
+              "profileSlug": "bookmark"
+            }
           }
         }
       },
       {
-        "id": "enrich",
-        "type": "skill",
-        "position": { "x": 0, "y": 120 },
+        "id": "read",
+        "type": "entity_read",
+        "position": {
+          "x": 0,
+          "y": 120
+        },
         "data": {
-          "label": "Bookmark Enrichment",
-          "skillName": "bookmark-enrichment",
-          "skillTitle": "Bookmark Enrichment",
+          "label": "Read the bookmark",
+          "entityId": "{{trigger.payload.subjectId}}"
+        }
+      },
+      {
+        "id": "graph-context",
+        "type": "related_entities",
+        "position": {
+          "x": 0,
+          "y": 240
+        },
+        "data": {
+          "label": "What the graph already connects (deterministic)",
+          "entityId": "{{trigger.payload.subjectId}}",
+          "direction": "both",
+          "limit": 10
+        }
+      },
+      {
+        "id": "channel-talk",
+        "type": "messages_query",
+        "position": {
+          "x": 0,
+          "y": 360
+        },
+        "data": {
+          "label": "What was being discussed (deterministic)",
+          "channelId": "{{steps.read.output.entity.properties.sourceChannelId}}",
+          "limit": 10,
+          "errorHandling": {
+            "continueOnError": true
+          }
+        }
+      },
+      {
+        "id": "sharer-lookup",
+        "type": "query",
+        "position": {
+          "x": 0,
+          "y": 480
+        },
+        "data": {
+          "label": "Resolve the sharer to a person entity (deterministic)",
+          "profileSlug": "person",
+          "filter": "{\"title\": \"{{steps.read.output.entity.properties.sharedBy}}\"}",
+          "limit": 5
+        }
+      },
+      {
+        "id": "has-sharer-name",
+        "type": "condition",
+        "position": {
+          "x": 0,
+          "y": 600
+        },
+        "data": {
+          "label": "Bookmark carries a sharer name?",
+          "expression": "steps.read.output.entity.properties.sharedBy !== ''"
+        }
+      },
+      {
+        "id": "sharer-matches",
+        "type": "condition",
+        "position": {
+          "x": 0,
+          "y": 720
+        },
+        "data": {
+          "label": "Matched person's title equals the sharer name exactly?",
+          "expression": "steps.sharer-lookup.output.entities.0.title === steps.read.output.entity.properties.sharedBy"
+        }
+      },
+      {
+        "id": "link-sharer",
+        "type": "output",
+        "position": {
+          "x": 0,
+          "y": 840
+        },
+        "data": {
+          "label": "Link bookmark → the person who shared it",
+          "outputType": "relation_create",
+          "config": {
+            "fromEntityId": "{{trigger.payload.subjectId}}",
+            "toEntityId": "{{steps.sharer-lookup.output.entities.0.id}}",
+            "relationType": "created_by"
+          }
+        }
+      },
+      {
+        "id": "classify",
+        "type": "capability",
+        "position": {
+          "x": 0,
+          "y": 1200
+        },
+        "data": {
+          "label": "Describe + classify (AI) — title only if the captured one is unusable",
+          "verbId": "ai.generate",
           "inputMapping": {
-            "entityId": "{{trigger.payload.subjectId}}"
+            "system": "You name saved links for a personal knowledge base. Answer with a JSON object and nothing else: {\"title\": string, \"description\": string, \"category\": string}. `title` is a short human-readable name for the link (max 70 chars, no URL, no quotes). `description` is one factual sentence (max 200 chars). `category` is ONE lowercase word from: article, video, tool, repo, docs, social, media, other. You CANNOT open the link. Use ONLY the URL, the already-resolved graph context and the surrounding conversation you are given. `description` and `category` are ALWAYS used. `title` is used ONLY when the link has no usable name yet — when 'Current name' below already reads like a real title, it is kept and yours is discarded, so never optimise for replacing it. If the material does not tell you what the page is, set `title` to the empty string rather than guessing.",
+            "prompt": "URL: {{steps.read.output.entity.properties.url}}\nCurrent name: {{steps.read.output.entity.title}}\nShared by: {{steps.read.output.entity.properties.sharedBy}}\n\nAlready connected in the graph:\n{{steps.graph-context.output.entities}}\n\nSurrounding conversation in the source channel:\n{{steps.channel-talk.output.messages}}\n\nThe message it arrived in:\n{{steps.read.output.entity.preview}}",
+            "json": "true",
+            "maxTokens": "2000"
+          }
+        }
+      },
+      {
+        "id": "apply-enrich",
+        "type": "output",
+        "position": {
+          "x": -400,
+          "y": 1500
+        },
+        "data": {
+          "label": "Write description + category back (always)",
+          "outputType": "entity_update",
+          "config": {
+            "entityId": "{{trigger.payload.subjectId}}",
+            "properties": {
+              "description": "{{steps.classify.output.description}}",
+              "category": "{{steps.classify.output.category}}"
+            }
+          }
+        }
+      },
+      {
+        "id": "title-present",
+        "type": "condition",
+        "position": {
+          "x": 400,
+          "y": 1350
+        },
+        "data": {
+          "label": "Did the link arrive with a name?",
+          "expression": "steps.read.output.entity.title !== ''"
+        }
+      },
+      {
+        "id": "title-not-url",
+        "type": "condition",
+        "position": {
+          "x": 400,
+          "y": 1470
+        },
+        "data": {
+          "label": "…and is that name more than the raw URL?",
+          "expression": "steps.read.output.entity.title !== steps.read.output.entity.properties.url"
+        }
+      },
+      {
+        "id": "usable-title",
+        "type": "guard",
+        "position": {
+          "x": 0,
+          "y": 1320
+        },
+        "data": {
+          "label": "Only rename when the model produced a real title",
+          "checks": [
+            {
+              "path": "steps.classify.output.title",
+              "minLength": 3,
+              "message": "ai.generate returned no usable title — leaving the bookmark's captured name untouched."
+            }
+          ]
+        }
+      },
+      {
+        "id": "apply-title",
+        "type": "output",
+        "position": {
+          "x": 0,
+          "y": 1440
+        },
+        "data": {
+          "label": "Write the AI title back (only when the captured one was unusable)",
+          "outputType": "entity_update",
+          "config": {
+            "entityId": "{{trigger.payload.subjectId}}",
+            "title": "{{steps.classify.output.title}}",
+            "properties": {
+              "title": "{{steps.classify.output.title}}"
+            }
           }
         }
       }
     ],
-    "edges": [{ "id": "e1", "source": "trigger", "target": "enrich" }]
+    "edges": [
+      {
+        "id": "trigger->read",
+        "source": "trigger",
+        "target": "read"
+      },
+      {
+        "id": "read->graph-context",
+        "source": "read",
+        "target": "graph-context"
+      },
+      {
+        "id": "graph-context->channel-talk",
+        "source": "graph-context",
+        "target": "channel-talk"
+      },
+      {
+        "id": "channel-talk->sharer-lookup",
+        "source": "channel-talk",
+        "target": "sharer-lookup"
+      },
+      {
+        "id": "sharer-lookup->has-sharer-name",
+        "source": "sharer-lookup",
+        "target": "has-sharer-name"
+      },
+      {
+        "id": "has-sharer-name->sharer-matches",
+        "source": "has-sharer-name",
+        "target": "sharer-matches",
+        "sourceHandle": "yes"
+      },
+      {
+        "id": "sharer-matches->link-sharer",
+        "source": "sharer-matches",
+        "target": "link-sharer",
+        "sourceHandle": "yes"
+      },
+      {
+        "id": "link-sharer->classify",
+        "source": "link-sharer",
+        "target": "classify"
+      },
+      {
+        "id": "has-sharer-name->classify",
+        "source": "has-sharer-name",
+        "target": "classify",
+        "sourceHandle": "no"
+      },
+      {
+        "id": "sharer-matches->classify",
+        "source": "sharer-matches",
+        "target": "classify",
+        "sourceHandle": "no"
+      },
+      {
+        "id": "classify->apply-enrich",
+        "source": "classify",
+        "target": "apply-enrich"
+      },
+      {
+        "id": "classify->title-present",
+        "source": "classify",
+        "target": "title-present"
+      },
+      {
+        "id": "title-present->title-not-url",
+        "source": "title-present",
+        "target": "title-not-url",
+        "sourceHandle": "yes"
+      },
+      {
+        "id": "title-present->usable-title",
+        "source": "title-present",
+        "target": "usable-title",
+        "sourceHandle": "no"
+      },
+      {
+        "id": "title-not-url->usable-title",
+        "source": "title-not-url",
+        "target": "usable-title",
+        "sourceHandle": "no"
+      },
+      {
+        "id": "usable-title->apply-title",
+        "source": "usable-title",
+        "target": "apply-title"
+      }
+    ]
   },
   "metadata": {
     "source": "bridge-template",
-    "note": "The skill node carries `skillName`; the CLI seed command resolves it to the live `skillId` at install time (GET /skills by name)."
+    "note": "DETERMINISTIC-FIRST. Everything reachable without a network call runs BEFORE the AI: `related_entities` (what the graph already connects to this bookmark — the capture flow's `references` edge to the channel's bound entity lands here), `messages_query` on the captured `sourceChannelId` (what was being discussed), and a `query` on `person` resolving the captured `sharedBy` display name to a real person entity, linked with the EXISTING `created_by` relation def (no new def, no new node type). ai.generate is now the LAST RESORT: it runs only when the captured name is empty OR is the raw URL — the branch `title-present`→`title-not-url` — so a human-written message preview is never overwritten by a guess, and when the AI does run it is handed the deterministic context instead of a bare URL. Two condition merges (`title-present`, `classify`) rely on markDescendantsSkipped's live-parent rule (graph-topology.ts) — a merge node survives as long as ONE incoming edge is unpruned. `sharer-lookup` uses the STRING filter form on purpose: `parseQueryFilterConditions` template-resolves a STRING filter but pushes an OBJECT filter's values RAW, so the object form would have compared the literal `{{...}}` text and silently matched nothing. The `sharer-matches` exact-equality condition is the containment for that string form: if a name with a quote breaks JSON.parse the filter is dropped and the query widens, and this check refuses to link a non-identical title. `messages_query` carries `continueOnError` because it THROWS when the channel is not visible in the automation's workspace. NOT expressible today: host→company/tool matching. `transform` has no host/hostname pipe and the query filter compiles only exact equality ($eq/$gt/$gte/$lt/$lte/$ne — no substring/LIKE), so a host could never be matched against a `website` property holding a full URL. A page `fetch` is deliberately still absent."
   }
-}
+}

package/templates/automations/url-bookmark-capture.automation.json

@@ -22,18 +22,36 @@
         }
       },
       {
-        "id": "extract",
+        "id": "content",
         "type": "transform",
         "position": { "x": 0, "y": 120 },
         "data": {
-          "label": "Extract URLs",
-          "expression": "{{trigger.payload.data.content}} | url_extract"
+          "label": "Trim message text",
+          "expression": "{{trigger.payload.data.content}} | trim"
+        }
+      },
+      {
+        "id": "title-src",
+        "type": "transform",
+        "position": { "x": 0, "y": 240 },
+        "data": {
+          "label": "Human text (title source)",
+          "expression": "{{trigger.payload.data.messagePreview}} | trim"
+        }
+      },
+      {
+        "id": "extract",
+        "type": "transform",
+        "position": { "x": 0, "y": 360 },
+        "data": {
+          "label": "Extract URLs · drop bare-link noise",
+          "expression": "{{trigger.payload.data.content}} | url_extract | unique | filter:item !== steps.content.output.result | slice:5"
         }
       },
       {
         "id": "url-loop",
         "type": "loop",
-        "position": { "x": 0, "y": 240 },
+        "position": { "x": 0, "y": 480 },
         "data": {
           "label": "For each URL",
           "iteratorExpression": "steps.extract.output.result",
@@ -43,28 +61,72 @@
       {
         "id": "create-bookmark",
         "type": "output",
-        "position": { "x": 0, "y": 360 },
+        "position": { "x": 0, "y": 600 },
         "data": {
           "label": "Create bookmark",
           "outputType": "entity_create",
           "config": {
             "profileSlug": "bookmark",
-            "title": "{{loop.item}}",
+            "title": "{{steps.title-src.output.result}}",
             "dedupeBy": "url",
+            "body": "{{steps.content.output.result}}",
             "properties": {
               "url": "{{loop.item}}",
+              "sourceChannelId": "{{trigger.payload.data.channelId}}",
+              "sourceThreadId": "{{trigger.payload.data.threadId}}",
               "sourceMessageId": "{{trigger.payload.data.messageId}}",
-              "sourceChannelId": "{{trigger.payload.data.threadId}}"
+              "sourceProvider": "{{trigger.payload.data.provider}}",
+              "sharedBy": "{{trigger.payload.data.participantName}}"
             }
           }
         }
+      },
+      {
+        "id": "has-bookmark-id",
+        "type": "condition",
+        "position": { "x": 0, "y": 720 },
+        "data": {
+          "label": "Bookmark row exists?",
+          "expression": "steps.create-bookmark.output.entityId !== ''"
+        }
+      },
+      {
+        "id": "has-context-entity",
+        "type": "condition",
+        "position": { "x": 0, "y": 840 },
+        "data": {
+          "label": "Channel bound to an entity?",
+          "expression": "trigger.payload.data.entityId !== ''"
+        }
+      },
+      {
+        "id": "link-context",
+        "type": "output",
+        "position": { "x": 0, "y": 960 },
+        "data": {
+          "label": "Link bookmark → channel's entity",
+          "outputType": "relation_create",
+          "config": {
+            "fromEntityId": "{{steps.create-bookmark.output.entityId}}",
+            "toEntityId": "{{trigger.payload.data.entityId}}",
+            "relationType": "references"
+          }
+        }
       }
     ],
     "edges": [
-      { "id": "e1", "source": "trigger", "target": "extract" },
-      { "id": "e2", "source": "extract", "target": "url-loop" },
-      { "id": "e3", "source": "url-loop", "target": "create-bookmark" }
+      { "id": "e1", "source": "trigger", "target": "content" },
+      { "id": "e2", "source": "content", "target": "title-src" },
+      { "id": "e3", "source": "title-src", "target": "extract" },
+      { "id": "e4", "source": "extract", "target": "url-loop" },
+      { "id": "e5", "source": "url-loop", "target": "create-bookmark" },
+      { "id": "e6", "source": "create-bookmark", "target": "has-bookmark-id" },
+      { "id": "e7", "source": "has-bookmark-id", "target": "has-context-entity", "sourceHandle": "yes" },
+      { "id": "e8", "source": "has-context-entity", "target": "link-context", "sourceHandle": "yes" }
     ]
   },
-  "metadata": { "source": "bridge-template" }
+  "metadata": {
+    "source": "bridge-template",
+    "note": "Phase 1 is DETERMINISTIC — no AI. It keeps the context the trigger already hands it: data.channelId (the INTERNAL Synap channel UUID, not the Discord snowflake, which is kept separately as sourceThreadId), data.content (as the bookmark body) and data.entityId (the channel's bound entity, linked with a `references` relation). Title = the message's own 120-char preview; when the message is nothing but a link the item is dropped by the noise filter rather than named, so the title is never invented. Noise filter: `filter:item !== steps.content.output.result` keeps only links that arrived WITH human text — a Tenor/giphy GIF drop or a bare Google Photos paste is exactly a message whose whole trimmed text IS the URL. A host denylist is NOT expressible: the condition grammar (condition-eval.ts) has no substring/regex operator and `contains` is exact set intersection, so any 'tenor.com'-style match would silently never fire."
+  }
 }

package/templates/skills/authoring-playbooks/SKILL.md

@@ -32,7 +32,7 @@ A playbook is **not** authored as a standalone file. It ships **inside a Capabil
 2. It is materialized by `createCapabilityFromDefinition()` when the capability is applied via `POST /api/hub/capabilities/apply`. Playbooks REQUIRE a `workspaceId` at apply time.
 3. The Discord bridge seeds it by adding the capability key to `AGENCY_CAPABILITY_PLAN` in `synap-cli/src/commands/bridge-setup.ts` with `workspaceScoped: true` (the flag that tells the bridge this capability bundles playbooks, so it must be applied with a workspace).
 
-**GOTCHA — do not copy the vestigial file.** `synap-control-plane-api/templates/packs/deep-research.playbook.json` looks like a standalone playbook template but it is VESTIGIAL: its playbook-specific fields are dropped during materialization. Never copy it or treat it as the schema. The authoritative shape is the `playbooks[]` entry inside a `.capability.json`. For a real example **with ordered stages**, see `stellar-grant-client.capability.json` and `reference/worked-example.md` (note: `agency-skills.capability.json` bundles playbooks but their `stages` are `[]`, so it does not demo the stages contract).
+**GOTCHA — do not copy the vestigial file.** `synap-control-plane-api/templates/packs/deep-research.playbook.json` looks like a standalone playbook template but it is VESTIGIAL: its playbook-specific fields are dropped during materialization. Never copy it or treat it as the schema. The authoritative shape is the `playbooks[]` entry inside a `.capability.json`. For a real example **with ordered stages**, see the "Grant Process" playbook in `synap-app/packages/workspace-templates/src/grants.yaml` (a `scope: project` method with 6 stages) and `reference/worked-example.md` (note: `agency-skills.capability.json` bundles playbooks but their `stages` are `[]`, so it does not demo the stages contract).
 
 ## Playbook field reference
 
@@ -68,13 +68,16 @@ Stages are **ordered** and drive the session's progression. Read `reference/stag
 ```jsonc
 "stages": [
   {
-    "key": "scope",                       // stable id, referenced by currentStage
+    "key": "scope",                       // stable id, referenced by currentStage. Unique within the playbook.
     "name": "Scope",
+    "category": "started",                // REQUIRED. backlog | planned | started | paused | completed | canceled
     "description": "Understand the client and their problem.",
     "goal": "Produce a one-paragraph problem statement.",   // optional
     "grants": [{ "kind": "skill", "id": "client-brief" }],  // optional, advisory hint (not enforced)
     "expectedOutputs": [{ "kind": "note", "label": "Problem statement" }],
-    "suggestedTasks": ["Read the intake form", "List open questions"]
+    "suggestedTasks": ["Read the intake form", "List open questions"],
+    "position": 0,                                         // optional, orders WITHIN the category group
+    "indefinite": false                                    // optional, may a subject sit here forever?
   }
 ]
 ```

package/templates/skills/authoring-playbooks/reference/stages-contract.md

@@ -8,14 +8,28 @@ Stages are the first-class, ordered process steps of a playbook. They replaced t
 type PlaybookStage = {
   key: string;                       // stable identifier; what currentStage holds. Required.
   name: string;                      // human label. Required.
+  category: PlaybookStageCategory;   // closed rollup bucket. REQUIRED — see below.
   description?: string;              // what this stage is about
   goal?: string;                     // the concrete objective of this stage
   grants?: CapabilityRef[];          // advisory capability hints ({ kind: tool|skill|command, id }) — see note below
   expectedOutputs?: ExpectedOutput[];// deliverables expected before advancing ({ kind, label }; kind loosely typed)
   suggestedTasks?: string[];         // soft checklist the agent can turn into tasks
+  position?: number;                 // order WITHIN this stage's category group — not a global order
+  indefinite?: boolean;              // may a subject sit here forever? absent/false ⇒ a long dwell is worth surfacing
 };
+
+type PlaybookStageCategory =
+  | "backlog"    // not committed
+  | "planned"    // committed, not begun
+  | "started"    // work under way
+  | "paused"     // on hold
+  | "completed"  // terminal, succeeded
+  | "canceled";  // terminal, abandoned
 ```
 
+- `category` is **required and validated** — a write with a stage missing it, or carrying a value outside the six, is REJECTED at the door. `key`/`name` are your playbook's own vocabulary; `category` is the shared axis every playbook rolls up onto, so a board spanning several playbooks can group them without reconciling names (two playbooks' key sets are disjoint by construction). Pick the bucket by what the stage MEANS, not by its position: a stage named "Review" is `started` if someone is working it and `paused` if it is waiting on an outsider.
+- `key` values must be **unique within one playbook** — `currentStage` stores the bare key, so a duplicate makes the active stage ambiguous. Also rejected at the door.
+- `position` orders a stage **within its category group**, not globally. This is why ordering never needs cross-playbook reconciliation.
 - `key` is **stable** — `focus_sessions.currentStage` stores it, and `stage_changed` events carry it. Don't rename keys on a live playbook; add/deprecate instead.
 - Stages are **ordered** by their position in the `stages[]` array.
 - `grants` here are **advisory**: stored as opaque JSON and surfaced to the agent in the stage's kickoff prompt via `RunContext`, but NOT resolved into enforcement `capability` / `link` rows (hard enforcement is a documented follow-up). "Granting" a skill at a stage = telling the agent to use it there; the skill is already reachable via the pod skill catalog + `load_skill` regardless. Declare grants on stages, not at the playbook level — top-level playbook `grants` are dropped during materialization.
@@ -29,6 +43,7 @@ type PlaybookStage = {
 
 ## Design rules
 
+- Assign `category` honestly. Most working stages are `started`; reserve `paused` for genuinely blocked-on-someone-else, and use `completed`/`canceled` only for terminal stages. Marking every stage `started` makes a cross-playbook board useless.
 - Keep stages **few and meaningful** (3–6 is typical). Each stage should represent a real change in what the agent is doing or waiting on.
 - Give every stage a `goal` and at least one `expectedOutput` so "done with this stage" is observable.
 - Use `suggestedTasks` for the soft checklist; use `expectedOutputs` for the hard deliverables that gate advancement. For `expectedOutputs[].kind`, keep to the shared (loosely typed) vocab `note` | `document` | `report`.

package/templates/skills/authoring-playbooks/reference/worked-example.md

@@ -27,6 +27,7 @@ This is a `playbooks[]` entry inside a `.capability.json` (NOT a standalone file
     {
       "key": "scope",
       "name": "Scope",
+      "category": "started",
       "description": "Understand the company and the problem worth solving.",
       "goal": "Produce a one-paragraph problem statement grounded in the company context.",
       "grants": [{ "kind": "skill", "id": "client-brief" }],
@@ -36,6 +37,7 @@ This is a `playbooks[]` entry inside a `.capability.json` (NOT a standalone file
     {
       "key": "abstract",
       "name": "Abstract",
+      "category": "started",
       "description": "Turn the problem into a buildable specification.",
       "goal": "Write a spec: scope, constraints, success criteria, and the smallest first deliverable.",
       "expectedOutputs": [{ "kind": "document", "label": "Buildable spec" }],
@@ -44,6 +46,7 @@ This is a `playbooks[]` entry inside a `.capability.json` (NOT a standalone file
     {
       "key": "build",
       "name": "Build",
+      "category": "started",
       "description": "Ship the first deliverable against the spec.",
       "goal": "Produce a working first build and link it to the company.",
       "grants": [{ "kind": "tool", "id": "gdrive" }],

package/dist/commands/infra.d.ts

@@ -1,21 +0,0 @@
-/**
- * synap infra
- *
- * Infrastructure management via Dokploy — view servers, trigger deploys,
- * tail logs, and sync server state into Synap entities.
- *
- *   synap infra               — overview: servers + services status
- *   synap infra status        — same as above
- *   synap infra deploy <app>  — trigger a redeploy for a named app
- *   synap infra logs <app>    — tail logs for a service
- *   synap infra sync          — pull Dokploy state into Synap entities
- *   synap infra open          — open Dokploy dashboard in browser
- */
-export declare function infraStatus(): Promise<void>;
-export declare function infraDeploy(appName: string): Promise<void>;
-export declare function infraLogs(appName: string, opts: {
-    lines?: number;
-    follow?: boolean;
-}): Promise<void>;
-export declare function infraSync(podUrl: string, apiKey: string): Promise<void>;
-export declare function infraOpen(): void;