@synap-core/workspace-templates 0.23.0 → 0.24.1

package/src/stripe-capability.test.ts

@@ -0,0 +1,192 @@
+/**
+ * The Stripe capability (session 92e83544, "Stripe capability: read-write,
+ * governed"): reads run, every write is reviewed, and the call can only ever
+ * reach https://api.stripe.com/v1/.
+ *
+ * Pinned here, where the verbs are authored:
+ *  - a GET verb declares `metadata.readOnly: true` (the gate runs it at once);
+ *    a verb that writes (POST, DELETE) never does, so it stays on the propose
+ *    grant the pod seeds for every capability tool (`GRANT_DEFAULT_EXEC_MODE`)
+ *    and its provider call re-checks the tool gate (`isReadMethod`);
+ *  - a write verb declares no read intent (list_records / fetch_record), and
+ *    its name or description carries a whole-word write signal, so the pod's
+ *    `deriveVerbKind` files it as an `action`, never a `read`;
+ *  - the tool's host is fixed (`baseUrl`), its bodies are form-encoded
+ *    (`config.bodyEncoding: "form"`, Stripe v1 takes no JSON body);
+ *  - every path is under `/v1/`; the generic verbs take their resource path
+ *    through `encode: "path"` (the pod refuses "." / ".." / empty segments);
+ *  - every Stripe-native field travels through `bodyFrom` (`fields` on a typed
+ *    verb, `params` on a generic one), never a `body` template that would send
+ *    an absent optional as an empty value (which Stripe reads as "unset");
+ *  - the eight read verbs live pods already run are all still there.
+ *
+ * NOT covered: Stripe accepting the calls (checked against the API reference,
+ * docs.stripe.com/api, not the live account; no write is ever sent to it), and
+ * the pod's encoder and gate (backend: form-encode.test.ts,
+ * execute-provider-verb.body-from.test.ts, form-body.vault.test.ts).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const manifest = JSON.parse(
+  readFileSync(join(__dirname, "..", "capabilities", "stripe.capability.json"), "utf8"),
+);
+type Verb = {
+  name: string;
+  intent?: string;
+  kind: string;
+  description: string;
+  requires: string[];
+  parameters?: Record<string, string>;
+  metadata?: { readOnly?: boolean };
+  providerSpec: {
+    method: string;
+    pathTemplate: string;
+    body?: unknown;
+    bodyFrom?: string;
+    paramMapping?: Record<string, { encode?: string; required?: boolean }>;
+  };
+};
+const verbs: Verb[] = manifest.spec.skills;
+const isRead = (v: Verb) => /^(GET|HEAD)$/i.test(v.providerSpec.method);
+const reads = verbs.filter(isRead);
+const writes = verbs.filter((v) => !isRead(v));
+
+// A mirror of the pod's own word lists (synap-backend create-from-definition.ts
+// VERB_WRITE_SIGNALS / VERB_READ_SIGNALS): name first, then description,
+// whole words, write signals before read signals. Held equal to the pod's
+// source by the "mirror" describe below.
+const WRITE_SIGNALS = ["send", "invite", "post", "create", "write", "update", "delete", "reply", "message", "email", "publish", "comment", "add", "remove", "set", "run", "execute"];
+const READ_SIGNALS = ["search", "list", "get", "fetch", "read", "find", "lookup", "query", "pull"];
+const words = (t: string) => new Set(t.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+const classify = (t: string) => {
+  const w = words(t);
+  if (WRITE_SIGNALS.some((s) => w.has(s))) return "action";
+  if (READ_SIGNALS.some((s) => w.has(s))) return "read";
+  return null;
+};
+const derivedKind = (v: Verb) => classify(v.name) ?? classify(v.description) ?? "action";
+
+describe("stripe capability: reads run, writes are reviewed", () => {
+  it("has reads and writes", () => {
+    expect(reads.length).toBeGreaterThan(10);
+    expect(writes.length).toBeGreaterThan(10);
+  });
+
+  it("every GET verb is read-only (runs at once)", () => {
+    expect(reads.filter((v) => v.metadata?.readOnly !== true).map((v) => v.name)).toEqual([]);
+  });
+
+  it("no write verb is read-only: each stays on the propose grant", () => {
+    expect(writes.filter((v) => v.metadata?.readOnly === true).map((v) => v.name)).toEqual([]);
+  });
+
+  it("a write declares no read intent and the pod files it as an action", () => {
+    expect(writes.filter((v) => v.intent === "list_records" || v.intent === "fetch_record").map((v) => v.name)).toEqual([]);
+    expect(writes.filter((v) => derivedKind(v) !== "action").map((v) => v.name)).toEqual([]);
+    expect(reads.filter((v) => derivedKind(v) !== "read").map((v) => v.name)).toEqual([]);
+  });
+
+  it("covers what the founder asked for: tax settings, tax registrations, payment links, checkout, refunds, payouts", () => {
+    const has = (method: string, path: string) =>
+      writes.some((v) => v.providerSpec.method === method && v.providerSpec.pathTemplate === path);
+    expect(has("POST", "/v1/tax/settings")).toBe(true);
+    expect(has("POST", "/v1/tax/registrations")).toBe(true);
+    expect(has("POST", "/v1/payment_links")).toBe(true);
+    expect(has("POST", "/v1/checkout/sessions")).toBe(true);
+    expect(has("POST", "/v1/refunds")).toBe(true);
+    expect(has("POST", "/v1/payouts")).toBe(true);
+    expect(has("DELETE", "/v1/subscriptions/{{subscriptionId}}")).toBe(true);
+  });
+
+  it("keeps the eight read verbs live pods already run", () => {
+    const names = new Set(reads.map((v) => v.name));
+    for (const n of ["stripe_list_customers", "stripe_get_customer", "stripe_list_charges", "stripe_list_invoices", "stripe_list_subscriptions", "stripe_list_products", "stripe_list_payouts", "stripe_get_balance"])
+      expect(names.has(n), n).toBe(true);
+  });
+});
+
+describe("stripe capability: one host, form bodies, paths under /v1/", () => {
+  const tool = manifest.spec.tools.find((t: { name: string }) => t.name === "stripe");
+
+  it("the tool's host is fixed and its bodies are form-encoded", () => {
+    expect(tool.config.baseUrl).toBe("https://api.stripe.com");
+    expect(tool.config.bodyEncoding).toBe("form");
+    expect(tool.credentialRef).toBe("stripe");
+    expect(verbs.every((v) => v.requires.length === 1 && v.requires[0] === "stripe")).toBe(true);
+  });
+
+  it("every path starts with /v1/; every path parameter is encoded (uri for an id, path for a generic resource path)", () => {
+    for (const v of verbs) {
+      expect(v.providerSpec.pathTemplate.startsWith("/v1/"), v.name).toBe(true);
+      for (const [, name] of v.providerSpec.pathTemplate.matchAll(/\{\{(\w+)\}\}/g)) {
+        const m = v.providerSpec.paramMapping?.[name!];
+        expect(m?.required, `${v.name}.${name}`).toBe(true);
+        expect(["uri", "path"], `${v.name}.${name}`).toContain(m?.encode);
+      }
+    }
+  });
+
+  it("the generic verbs are one per method, each taking a /v1/-relative path", () => {
+    const generic = verbs.filter((v) => v.providerSpec.pathTemplate === "/v1/{{path}}");
+    expect(generic.map((v) => `${v.name} ${v.providerSpec.method}`).sort()).toEqual([
+      "stripe_api_delete DELETE",
+      "stripe_api_read GET",
+      "stripe_api_write POST",
+    ]);
+    for (const v of generic) {
+      expect(v.providerSpec.paramMapping?.path).toEqual({ required: true, encode: "path" });
+      expect(v.providerSpec.bodyFrom).toBe("params");
+    }
+  });
+
+  it("Stripe's own fields travel only through bodyFrom (no body template sending an absent optional as empty)", () => {
+    for (const v of verbs) expect(v.providerSpec.body, v.name).toBeUndefined();
+    for (const v of writes) {
+      expect(v.providerSpec.bodyFrom, v.name).toBeDefined();
+      expect(v.parameters?.[v.providerSpec.bodyFrom!], v.name).toMatch(/^object\??$/);
+    }
+  });
+
+  it("the connect copy names the restricted key and the permissions to grant", () => {
+    const param = manifest.spec.params.find((p: { name: string }) => p.name === "stripeApiKey");
+    expect(param.description).toMatch(/RESTRICTED/);
+    expect(param.description).toMatch(/Write only/);
+    expect(param.description).toMatch(/Tax Settings, Tax Registrations/);
+    expect(manifest.spec.description).toMatch(/ADAPTIVE PRICING/);
+  });
+});
+
+// ── The mirror: the word lists above equal the pod's ─────────────────────────
+// Read from synap-backend's source (a sibling checkout), so a word the pod
+// adds or drops turns this red instead of the classification above drifting
+// unseen. Skips, with the reason logged, when synap-backend is not a sibling.
+const POD_SOURCE = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../synap-backend/packages/api/src/services/capabilities/create-from-definition.ts",
+);
+const hasPodSource = existsSync(POD_SOURCE);
+if (!hasPodSource) console.warn(`[stripe signals mirror] SKIP: ${POD_SOURCE} is absent`);
+
+/** The string literals of `const <name> = [ ... ]` in `src`, in order. */
+function podList(src: string, name: string): string[] {
+  const m = new RegExp(`const ${name}\\s*=\\s*\\[([^\\]]*)\\]`).exec(src);
+  expect(m, `${name} is declared in create-from-definition.ts`).not.toBeNull();
+  return [...m![1]!.matchAll(/"([^"]+)"/g)].map((x) => x[1]!);
+}
+
+describe.skipIf(!hasPodSource)("stripe capability: the word lists mirror the pod's", () => {
+  const src = hasPodSource ? readFileSync(POD_SOURCE, "utf8") : "";
+  it("WRITE_SIGNALS equals VERB_WRITE_SIGNALS", () => {
+    const pod = podList(src, "VERB_WRITE_SIGNALS");
+    expect(pod.length).toBeGreaterThan(5);
+    expect(WRITE_SIGNALS).toEqual(pod);
+  });
+  it("READ_SIGNALS equals VERB_READ_SIGNALS", () => {
+    const pod = podList(src, "VERB_READ_SIGNALS");
+    expect(pod.length).toBeGreaterThan(3);
+    expect(READ_SIGNALS).toEqual(pod);
+  });
+});

package/src/template-documents.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Templates carry documents (`documents[]` + sidebar items
+ * `{kind: "document", documentSlug}`, plan 9ad4b2fc §5 lane 12). The pod
+ * installs them with the views (synap-backend `utils/template-documents.ts`);
+ * this file pins the authoring half:
+ *
+ *  (1) the catalog schema accepts `documents[]` and refuses an unknown key in one;
+ *  (2) both converters carry the documents verbatim, and a template WITHOUT
+ *      documents compiles to a definition with no `documents` key (so every
+ *      shipped template's body and content hash stay what they were);
+ *  (3) `validateTemplate` refuses a bad slug, a duplicate slug, a missing
+ *      title, an unknown scope, and a document sidebar item naming a document
+ *      neither the template nor a base it COMPOSES onto declares (a `require`
+ *      base keeps its own space, so its documents are not reachable);
+ *  (4) no shipped template declares documents while the control plane's
+ *      publish door cannot carry them (it strips `documents` and refuses a
+ *      `kind: "document"` sidebar item): the set is derived from `src/*.yaml`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { workspaceSpecSchema } from "../schema/workspace.ts";
+import { toPackageDefinition, toWorkspaceDefinition } from "./define.ts";
+import { readYamlTemplates } from "./generate.mjs";
+import type { WorkspaceYaml } from "./types.ts";
+import { validateTemplate } from "./validate.ts";
+
+const base = (overrides: Partial<WorkspaceYaml> = {}): WorkspaceYaml =>
+  ({
+    meta: {
+      slug: "docs-demo",
+      name: "Docs demo",
+      description: "d",
+      icon: "x",
+      color: "violet",
+    },
+    workspace: { name: "Docs demo", description: "d" },
+    profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
+    ...overrides,
+  }) as WorkspaceYaml;
+
+const DOCS = [
+  {
+    slug: "space-home",
+    title: "Space home",
+    content: 'Welcome.\n\n::synap-cell{cellKey="lens-section"}',
+    scope: "space" as const,
+  },
+  { slug: "notes", title: "Notes", content: "" },
+];
+
+const withDocs = base({
+  documents: DOCS,
+  layout: {
+    sidebarItems: [{ kind: "document", documentSlug: "space-home", label: "Home" }],
+  },
+});
+
+const rules = (tpl: WorkspaceYaml, opts = {}) =>
+  validateTemplate(tpl, opts).errors.map((e) => e.rule);
+
+describe("templates carry documents", () => {
+  it("(1) the catalog schema accepts documents[] and refuses an unknown key in one", () => {
+    const { meta: _meta, ...spec } = withDocs;
+    expect(workspaceSpecSchema.safeParse(spec).success).toBe(true);
+    const bad = { ...spec, documents: [{ ...DOCS[1], body: "typo" }] };
+    expect(workspaceSpecSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it("(2) both converters carry the documents; a template without any emits no key", () => {
+    expect(toPackageDefinition(withDocs).documents).toEqual(DOCS);
+    expect(toWorkspaceDefinition(withDocs).definition.documents).toEqual(DOCS);
+    expect(toPackageDefinition(withDocs).layoutConfig?.sidebarItems).toEqual([
+      { kind: "document", documentSlug: "space-home", label: "Home" },
+    ]);
+    expect("documents" in toPackageDefinition(base())).toBe(false);
+    expect("documents" in toWorkspaceDefinition(base()).definition).toBe(false);
+  });
+
+  it("(3a) a clean template with documents validates", () => {
+    const r = validateTemplate(withDocs, {});
+    expect(r, JSON.stringify(r.errors)).toEqual({ ok: true, errors: [] });
+  });
+
+  it("(3b) each document rule fires", () => {
+    expect(rules(base({ documents: [{ ...DOCS[1], slug: "Not Kebab" }] }))).toContain(
+      "document-slug-invalid"
+    );
+    expect(rules(base({ documents: [DOCS[1], { ...DOCS[1], title: "Again" }] }))).toContain(
+      "document-slug-duplicate"
+    );
+    expect(rules(base({ documents: [{ ...DOCS[1], title: " " }] }))).toContain(
+      "document-title-required"
+    );
+    expect(
+      rules(base({ documents: [{ ...DOCS[1], scope: "project" as never }] }))
+    ).toContain("document-scope-unknown");
+    expect(
+      rules(
+        base({
+          documents: DOCS,
+          layout: { sidebarItems: [{ kind: "document", documentSlug: "missing" }] },
+        })
+      )
+    ).toContain("sidebar-document-unknown");
+    expect(
+      rules(base({ layout: { sidebarItems: [{ kind: "document" }] } }))
+    ).toContain("sidebar-document-unknown");
+  });
+
+  it("(3c) an overlay may name a document of a base it composes onto, not of one it requires", () => {
+    const baseTpl = base({ documents: DOCS });
+    const overlay = (relation: "compose" | "require") =>
+      base({
+        meta: { ...base().meta, slug: "docs-overlay" },
+        dependencies: [{ slug: "docs-demo", relation }],
+        layout: { sidebarItems: [{ kind: "document", documentSlug: "notes" }] },
+      });
+    const resolveDep = (slug: string) => (slug === "docs-demo" ? baseTpl : undefined);
+    expect(rules(overlay("compose"), { resolveDep })).not.toContain(
+      "sidebar-document-unknown"
+    );
+    expect(rules(overlay("require"), { resolveDep })).toContain(
+      "sidebar-document-unknown"
+    );
+  });
+
+  it("(4) no shipped template declares documents while the CP publish door cannot carry them", () => {
+    const yamls = readYamlTemplates() as Array<{ file: string; data: WorkspaceYaml }>;
+    expect(yamls.length).toBeGreaterThanOrEqual(25);
+    const declaring = yamls
+      .filter(
+        ({ data }) =>
+          (data.documents?.length ?? 0) > 0 ||
+          (data.layout?.sidebarItems ?? []).some((i) => i.kind === "document")
+      )
+      .map(({ file }) => file);
+    if (declaring.length === 0) return;
+    // A template uses them: the CP's packageDefinitionSchema must slot both.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const cpPackages = join(here, "../../../../synap-control-plane-api/src/routes/packages.ts");
+    expect(existsSync(cpPackages), `${declaring.join(", ")} declare documents; ${cpPackages} is needed to check the CP carries them`).toBe(true);
+    const src = readFileSync(cpPackages, "utf8");
+    const start = src.indexOf("export const packageDefinitionSchema = z.object(");
+    expect(start).toBeGreaterThan(-1);
+    const body = src.slice(start, src.indexOf("\n});", start));
+    expect(body, `${declaring.join(", ")} declare documents, which the CP publish door strips`).toMatch(/\n  documents:/);
+    // The sidebar ITEM's kind enum is the one listing "profile" (the nested
+    // `surface` enum already lists "document"; it is not the item's kind).
+    const itemKinds = [...body.matchAll(/kind: z\.enum\(\[([^\]]*)\]\)/g)]
+      .map((m) => m[1]!)
+      .filter((list) => list.includes('"profile"'));
+    expect(itemKinds.length, "the CP sidebar item kind enum was not found").toBeGreaterThan(0);
+    for (const list of itemKinds)
+      expect(list, `${declaring.join(", ")} name a document sidebar item, which the CP publish door refuses`).toContain('"document"');
+  });
+});

package/src/templates.ts

@@ -11071,6 +11071,31 @@ const DATA = {
         "executor": "is-agent",
         "status": "active"
       },
+      {
+        "name": "Write the caption",
+        "description": "Draft the caption of one post from its brief and its script, as a draft in its script document that the person edits and saves.",
+        "goalTemplate": "Draft the caption of this post ({post}). Read the post: its hook (post-hook), its call to action (post-cta), its pillar, its journey stage, its platform (post-platform) and its format. Read its script, the post's own document: its slides (the S1, S2 lines or the slide table) and any caption already written under \"## Caption\". Write ONE caption in the brand voice (the pod's brand kit) that says what the slides leave out: a first line that stands on its own before the platform cuts it (Instagram shows about 125 characters before \"more\", LinkedIn about 210 before \"see more\"), then two or three short lines, and the call to action last. No hashtag wall, no emoji run, no claim the script does not make, and no line that starts with \"##\". Put it in the script document as its \"## Caption draft\" section: replace that section if it is there, else add it at the end, and change no other line (synap_update_document with the revision you read). Never write or change the \"## Caption\" section on your own: it is the person's. Then ask the person to approve your draft: ONE confirm ask on this session (owner the person), its prompt the caption itself, \"Use this caption\" recommended. On yes, put the draft in the \"## Caption\" section (replace its words, or add it) and remove the \"## Caption draft\" section, nothing else. On no, leave the draft where it is (they may edit it and save it on the post's page in Content Studio, which also makes it the caption). Never move the post's status. Close this session once the person answered.",
+        "subjectProfile": {
+          "profileSlug": "post"
+        },
+        "expectedOutputs": [
+          {
+            "kind": "document",
+            "label": "Caption draft",
+            "relationToSubject": "none"
+          }
+        ],
+        "params": [
+          {
+            "name": "post",
+            "type": "entity",
+            "label": "Post",
+            "required": true
+          }
+        ],
+        "executor": "is-agent",
+        "status": "active"
+      },
       {
         "name": "Repurpose",
         "description": "Turn a published post into new posts for other formats and platforms, each linked to the original.",
@@ -13525,7 +13550,7 @@ const DATA = {
       {
         "name": "Draft a first message",
         "description": "Draft one personal first message for a lead, citing its buying signal or a past exchange, in the person's language, as a proposed message in their channel for a person to approve; the agent never sends.",
-        "goalTemplate": "Draft the first message to the lead {lead} on {channel}. READ: the lead's score fields (icpScore, buyingSignal, buyingSignalSource, qualificationNotes) as they are, never rescoring them; its channels, past messages and notes in the pod; and the outreach campaign given ({campaign}), if any: its value proposition and call to action are the angle. WHO: a person lead is written to directly; for a company lead, write to the person who decides there (from the pod, else its public decider), and when no decider is known ask the person who to write to. DRAFT: one first message on channel {channel}, in the campaign's angle when one is given. DRAFT RULES: each draft is one proposed message in the channel of the person it is written to, filed through the pod's send door: run messaging.send with to = that person's entity id (for a company lead, its decider: when that person is not in the pod, create them through the entity door with only their own fields, such as name, role and LinkedIn URL, never the company's website, domain or email), text = the message, and provider linkedin or email. Read their channel first (synap_get_channel, mode person) for what was already said. The pod files it for a person to review in that channel; it goes out only once they approve it. Never call a tool's own send verb (Unipile, Gmail), never create an outreach touch, a note or a task holding the message, and never use synap_capture for it. Never send. Its message is personal: it cites the buying signal and what it showed, or a past exchange, never a generic template; short; in the person's language, French by default, and in French it says vous. It offers one useful next step, never pressure. Draft one message only: a person reviews it in the channel, edits it if needed and approves it. NEXT ACTION: set the lead's nextAction to \"Send the first message to <name> on LinkedIn\" (\"Send the first message to <name> by email\" on email), naming the person written to, and its nextActionAt to today. Never move the lead's stage while drafting. SENT: once the message is sent, follow the cadence, so \"Follow up on leads in outreach\" drafts the next one. CADENCE: when a message is sent (a person approved its proposed message, so it is an outbound message in the channel), set its lead's lastContactedAt to the sent day, count the messages sent to the lead (the outbound messages in its channels, read with synap_get_channel mode person: for a company lead, the channels of the person written to there), and set the lead's next action: after the first message, nextAction \"Follow up with <name> if no reply\" and nextActionAt the sent day + 3 days; after the first follow-up, nextAction \"Follow up with <name> a last time if no reply\" and nextActionAt the sent day + 7 days; after the second follow-up, nextAction \"No reply after two follow-ups: nurture or drop <name>\" and nextActionAt the sent day + 7 days, and when that date passes with no reply, \"Follow up on leads in outreach\" proposes nurturing. Never a third follow-up. Propose moving a lead at new or researching to outreach through the status door, with its expected status. A reply stops the cadence: a reply is an inbound message after our last outbound one in the channel, and \"Follow up on leads in outreach\" reads it and proposes the next step.",
+        "goalTemplate": "Draft the first message to the lead {lead} on {channel}. READ: the lead's score fields (icpScore, buyingSignal, buyingSignalSource, qualificationNotes) as they are, never rescoring them; its channels, past messages and notes in the pod; and the outreach campaign given ({campaign}), if any: its value proposition and call to action are the angle. WHO: a person lead is written to directly; for a company lead, write to the person who decides there (from the pod, else its public decider), and when no decider is known ask the person who to write to. DRAFT: one first message on channel {channel}, in the campaign's angle when one is given. DRAFT RULES: each draft is one proposed message in the channel of the person it is written to, filed through the pod's send door: run messaging.send with to = that person's entity id (for a company lead, its decider: when that person is not in the pod, create them through the entity door with only their own fields, such as name, role and LinkedIn URL, never the company's website, domain or email), text = the message, and provider linkedin or email. Read their channel first (synap_get_channel, mode person) for what was already said. The pod files it for a person to review in that channel; it goes out only once they approve it. Never call a tool's own send verb (Unipile, Gmail), never create an outreach touch, a note or a task holding the message, and never use synap_capture for it. Never send. A LinkedIn message is drafted whatever their reach: the pod holds a draft to someone who is not a connection yet, shows it with the next step and lets it go out once they connect, so never hold a draft back for want of a connection. Draft it, then, in this order: (1) a person with no linkedinUrl: find their profile with linkedin_find_profile (their full name and company); on a match, propose its linkedinUrl and linkedinProviderId on the person for a person to approve; on none or several, ask the person to choose among its candidates (the process \"Find their LinkedIn\" does this for one lead). (2) Read their linkedinConnection, which only the pod writes (never set it or linkedinInvitedAt): connected, nothing more; none or not set, ask to connect with linkedin_send_invite (it refuses someone already connected or already invited: then nothing more); pending, the draft waits for them; ignored, draft by email instead when they have an email address. While the draft waits for them to connect, set the lead's nextAction to \"Wait for <name> to accept the LinkedIn request\" and its nextActionAt 7 days later. An email message needs none of this. Its message is personal: it cites the buying signal and what it showed, or a past exchange, never a generic template; short; in the person's language, French by default, and in French it says vous. It offers one useful next step, never pressure. Draft one message only: a person reviews it in the channel, edits it if needed and approves it. NEXT ACTION: set the lead's nextAction to \"Send the first message to <name> on LinkedIn\" (\"Send the first message to <name> by email\" on email), naming the person written to, and its nextActionAt to today. Never move the lead's stage while drafting. SENT: once the message is sent, follow the cadence, so \"Follow up on leads in outreach\" drafts the next one. CADENCE: when a message is sent (a person approved its proposed message, so it is an outbound message in the channel), set its lead's lastContactedAt to the sent day, count the messages sent to the lead (the outbound messages in its channels, read with synap_get_channel mode person: for a company lead, the channels of the person written to there), and set the lead's next action: after the first message, nextAction \"Follow up with <name> if no reply\" and nextActionAt the sent day + 3 days; after the first follow-up, nextAction \"Follow up with <name> a last time if no reply\" and nextActionAt the sent day + 7 days; after the second follow-up, nextAction \"No reply after two follow-ups: nurture or drop <name>\" and nextActionAt the sent day + 7 days, and when that date passes with no reply, \"Follow up on leads in outreach\" proposes nurturing. Never a third follow-up. Propose moving a lead at new or researching to outreach through the status door, with its expected status. A reply stops the cadence: a reply is an inbound message after our last outbound one in the channel, and \"Follow up on leads in outreach\" reads it and proposes the next step.",
         "subjectProfile": {
           "profileSlug": "lead"
         },
@@ -13579,7 +13604,7 @@ const DATA = {
             "criteria": [
               {
                 "key": "first-message-one-draft",
-                "statement": "One proposed message, filed through messaging.send to the person written to (for a company, its decider), waits for review in that person's channel, holds the message text, and follows the campaign's angle when one was given.",
+                "statement": "One proposed message, filed through messaging.send to the person written to (for a company, its decider), waits for review in that person's channel, holds the message text, and follows the campaign's angle when one was given, whatever the person's LinkedIn reach; on LinkedIn to someone not yet a connection, the pod holds it, and their profile is found and the connection asked for or awaited, in the DRAFT RULES order.",
                 "check": {
                   "kind": "judge"
                 }
@@ -13628,10 +13653,73 @@ const DATA = {
           }
         ]
       },
+      {
+        "name": "Find their LinkedIn",
+        "description": "Find one lead's LinkedIn profile by their full name and company and propose its URL and member id on the person for a person to approve, or offer up to 3 candidates to choose from; nothing is sent.",
+        "goalTemplate": "Find the LinkedIn profile of the lead {lead}. WHO: a person lead is looked up themselves; for a company lead, the person who decides there, from the pod; when no decider is known, ask the person who it is. When that person already has a linkedinUrl, say so and stop. FIND: run linkedin_find_profile with their full name, their company and the LinkedIn account unipile_list_accounts lists (when several are connected, ask the person which one reads). On a match, propose its linkedinUrl and linkedinProviderId on the person through the entity door, for a person to approve; never write them directly, and never set linkedinConnection or linkedinInvitedAt, which only the pod writes. On none, several or more results than it read, ask the person to choose among its candidates (at most 3, each with its name, headline and profile URL) or to give the URL themselves, then propose the one chosen the same way. Never send a message or a connection request, never draft one, and never move the lead's stage.",
+        "subjectProfile": {
+          "profileSlug": "lead"
+        },
+        "activators": [
+          {
+            "on": "manual",
+            "mode": "propose"
+          }
+        ],
+        "params": [
+          {
+            "name": "lead",
+            "type": "entity",
+            "label": "Lead",
+            "required": true
+          }
+        ],
+        "executor": "is-agent",
+        "status": "active",
+        "requiredIntents": [
+          "enrich_entity"
+        ],
+        "stages": [
+          {
+            "key": "find",
+            "name": "Find the profile",
+            "category": "started",
+            "goal": "Run linkedin_find_profile for the lead (a company lead's decider) with their full name and company; on a match propose linkedinUrl and linkedinProviderId on the person, otherwise ask the person to choose among up to 3 candidates or give the URL.",
+            "criteria": [
+              {
+                "key": "find-linkedin-proposed",
+                "statement": "The person's linkedinUrl and linkedinProviderId are proposed on them for a person to approve (a strict match, or the candidate the person chose), or the person was asked to choose among at most 3 candidates; nothing was written directly.",
+                "check": {
+                  "kind": "judge"
+                }
+              },
+              {
+                "key": "find-linkedin-reader-only",
+                "statement": "No message or connection request was sent or drafted, linkedinConnection and linkedinInvitedAt were not set, and the lead's stage was not moved.",
+                "check": {
+                  "kind": "judge"
+                }
+              }
+            ]
+          },
+          {
+            "key": "confirm",
+            "name": "Person confirms",
+            "category": "completed",
+            "goal": "The person approves the proposed profile, or picks a candidate or gives the URL, and the pod stores linkedinUrl and linkedinProviderId on the person; the lead's next step is then to ask to connect.",
+            "gate": {
+              "kind": "human"
+            },
+            "onFail": {
+              "toStage": "find"
+            }
+          }
+        ]
+      },
       {
         "name": "Follow up on leads in outreach",
         "description": "Each weekday, read the channels of the leads in outreach; summarise a reply and propose the next step, or, when the follow-up is due with no reply, draft the next message in the angle of its outreach campaign as a proposed message for a person to approve; the agent never sends.",
-        "goalTemplate": "Follow up on the leads in outreach. For each, read its channels (synap_get_channel, mode person: for a company lead, the channels of the person who decides there) and its notes. A REPLY is an inbound message after our last outbound one in a channel. With a reply, draft nothing: summarise it for a person; when they show interest, propose the next step (prepare the free estimate, \"Prepare a pre-sale estimate\", or book a meeting) and propose moving the lead to engaged; when they decline, propose nurturing or disqualified with their reason (in disqualificationReason). Unless you propose dropping them, write the next step on the lead as nextAction, one imperative line, and nextActionAt, the date they named or today. Never open a deal and never answer the reply yourself; a person does. With no reply, and only when the lead's next action date is today or past and no proposed message to it is still waiting, draft the next message, to the lead (for a company, the person who decides there) and in the angle of the lead's outreach campaign: follow its value proposition and call to action, short and in the lead's language, offering the next useful step, never pressure. For a lead with no campaign, ask the person which one. Draft at most two follow-ups per lead: a lead already sent two follow-ups gets no draft, never a third follow-up; when its last date passes in silence, propose moving it to nurturing through the status door, with its expected status. DRAFT RULES: each draft is one proposed message in the channel of the person it is written to, filed through the pod's send door: run messaging.send with to = that person's entity id (for a company lead, its decider: when that person is not in the pod, create them through the entity door with only their own fields, such as name, role and LinkedIn URL, never the company's website, domain or email), text = the message, and provider linkedin or email. Read their channel first (synap_get_channel, mode person) for what was already said. The pod files it for a person to review in that channel; it goes out only once they approve it. Never call a tool's own send verb (Unipile, Gmail), never create an outreach touch, a note or a task holding the message, and never use synap_capture for it. Never send. For each draft, set the lead's `nextAction` to send it (e.g. \"Send the drafted message to Ana on LinkedIn\") and `nextActionAt` to today. The person reviews each proposed message in its channel, edits it if needed and approves it; the agent never sends. CADENCE: when a message is sent (a person approved its proposed message, so it is an outbound message in the channel), set its lead's lastContactedAt to the sent day, count the messages sent to the lead (the outbound messages in its channels, read with synap_get_channel mode person: for a company lead, the channels of the person written to there), and set the lead's next action: after the first message, nextAction \"Follow up with <name> if no reply\" and nextActionAt the sent day + 3 days; after the first follow-up, nextAction \"Follow up with <name> a last time if no reply\" and nextActionAt the sent day + 7 days; after the second follow-up, nextAction \"No reply after two follow-ups: nurture or drop <name>\" and nextActionAt the sent day + 7 days, and when that date passes with no reply, \"Follow up on leads in outreach\" proposes nurturing. Never a third follow-up. Propose moving a lead at new or researching to outreach through the status door, with its expected status. A reply stops the cadence: a reply is an inbound message after our last outbound one in the channel, and \"Follow up on leads in outreach\" reads it and proposes the next step.",
+        "goalTemplate": "Follow up on the leads in outreach. For each, read its channels (synap_get_channel, mode person: for a company lead, the channels of the person who decides there) and its notes. A REPLY is an inbound message after our last outbound one in a channel. With a reply, draft nothing: summarise it for a person; when they show interest, propose the next step (prepare the free estimate, \"Prepare a pre-sale estimate\", or book a meeting) and propose moving the lead to engaged; when they decline, propose nurturing or disqualified with their reason (in disqualificationReason). Unless you propose dropping them, write the next step on the lead as nextAction, one imperative line, and nextActionAt, the date they named or today. Never open a deal and never answer the reply yourself; a person does. With no reply, and only when the lead's next action date is today or past and no proposed message to it is still waiting, draft the next message, to the lead (for a company, the person who decides there) and in the angle of the lead's outreach campaign: follow its value proposition and call to action, short and in the lead's language, offering the next useful step, never pressure. For a lead with no campaign, ask the person which one. Draft at most two follow-ups per lead: a lead already sent two follow-ups gets no draft, never a third follow-up; when its last date passes in silence, propose moving it to nurturing through the status door, with its expected status. DRAFT RULES: each draft is one proposed message in the channel of the person it is written to, filed through the pod's send door: run messaging.send with to = that person's entity id (for a company lead, its decider: when that person is not in the pod, create them through the entity door with only their own fields, such as name, role and LinkedIn URL, never the company's website, domain or email), text = the message, and provider linkedin or email. Read their channel first (synap_get_channel, mode person) for what was already said. The pod files it for a person to review in that channel; it goes out only once they approve it. Never call a tool's own send verb (Unipile, Gmail), never create an outreach touch, a note or a task holding the message, and never use synap_capture for it. Never send. A LinkedIn message is drafted whatever their reach: the pod holds a draft to someone who is not a connection yet, shows it with the next step and lets it go out once they connect, so never hold a draft back for want of a connection. Draft it, then, in this order: (1) a person with no linkedinUrl: find their profile with linkedin_find_profile (their full name and company); on a match, propose its linkedinUrl and linkedinProviderId on the person for a person to approve; on none or several, ask the person to choose among its candidates (the process \"Find their LinkedIn\" does this for one lead). (2) Read their linkedinConnection, which only the pod writes (never set it or linkedinInvitedAt): connected, nothing more; none or not set, ask to connect with linkedin_send_invite (it refuses someone already connected or already invited: then nothing more); pending, the draft waits for them; ignored, draft by email instead when they have an email address. While the draft waits for them to connect, set the lead's nextAction to \"Wait for <name> to accept the LinkedIn request\" and its nextActionAt 7 days later. An email message needs none of this. For each draft, set the lead's `nextAction` to send it (e.g. \"Send the drafted message to Ana on LinkedIn\") and `nextActionAt` to today. The person reviews each proposed message in its channel, edits it if needed and approves it; the agent never sends. CADENCE: when a message is sent (a person approved its proposed message, so it is an outbound message in the channel), set its lead's lastContactedAt to the sent day, count the messages sent to the lead (the outbound messages in its channels, read with synap_get_channel mode person: for a company lead, the channels of the person written to there), and set the lead's next action: after the first message, nextAction \"Follow up with <name> if no reply\" and nextActionAt the sent day + 3 days; after the first follow-up, nextAction \"Follow up with <name> a last time if no reply\" and nextActionAt the sent day + 7 days; after the second follow-up, nextAction \"No reply after two follow-ups: nurture or drop <name>\" and nextActionAt the sent day + 7 days, and when that date passes with no reply, \"Follow up on leads in outreach\" proposes nurturing. Never a third follow-up. Propose moving a lead at new or researching to outreach through the status door, with its expected status. A reply stops the cadence: a reply is an inbound message after our last outbound one in the channel, and \"Follow up on leads in outreach\" reads it and proposes the next step.",
         "subjectProfile": {
           "profileSlug": "lead",
           "statusProperty": "leadStage"
@@ -13718,7 +13806,7 @@ const DATA = {
       {
         "name": "Personalized Outreach",
         "description": "Run one outreach campaign — write the angle and its offer, pick the people, draft one personal first message each as a proposed message in their channel; a person approves the list, then approves each message, which the pod sends.",
-        "goalTemplate": "Run this outreach campaign ({campaign}) on {channel}; each stage moves its status. If its type is not outreach, stop and say so. PREPARE: write the target audience, the value proposition and the call to action. Pick the people to reach from the pod (and public sources when the pod has too few), resolving each one before creating anything, link each as a member of the campaign with the lead role (lead source cold-outreach when it has none), and for each draft one first message to that person in this campaign's angle, specific to them — their company, role and any past message — never a generic template. DRAFT RULES: each draft is one proposed message in the channel of the person it is written to, filed through the pod's send door: run messaging.send with to = that person's entity id (for a company lead, its decider: when that person is not in the pod, create them through the entity door with only their own fields, such as name, role and LinkedIn URL, never the company's website, domain or email), text = the message, and provider linkedin or email. Read their channel first (synap_get_channel, mode person) for what was already said. The pod files it for a person to review in that channel; it goes out only once they approve it. Never call a tool's own send verb (Unipile, Gmail), never create an outreach touch, a note or a task holding the message, and never use synap_capture for it. Never send. START: a person approves the audience, the offer and the list, then reviews each proposed message in its channel and approves it; nothing goes out before they approve it, and the agent never sends. Once a message is sent, follow the cadence, so \"Follow up on leads in outreach\" drafts the next one. CADENCE: when a message is sent (a person approved its proposed message, so it is an outbound message in the channel), set its lead's lastContactedAt to the sent day, count the messages sent to the lead (the outbound messages in its channels, read with synap_get_channel mode person: for a company lead, the channels of the person written to there), and set the lead's next action: after the first message, nextAction \"Follow up with <name> if no reply\" and nextActionAt the sent day + 3 days; after the first follow-up, nextAction \"Follow up with <name> a last time if no reply\" and nextActionAt the sent day + 7 days; after the second follow-up, nextAction \"No reply after two follow-ups: nurture or drop <name>\" and nextActionAt the sent day + 7 days, and when that date passes with no reply, \"Follow up on leads in outreach\" proposes nurturing. Never a third follow-up. Propose moving a lead at new or researching to outreach through the status door, with its expected status. A reply stops the cadence: a reply is an inbound message after our last outbound one in the channel, and \"Follow up on leads in outreach\" reads it and proposes the next step. FINISH: when every person written to has replied or their follow-ups ended in silence, record in the campaign notes how many messages were sent (the outbound messages in their channels), how many got a reply and how many led to a booked meeting. Pausing or cancelling is a person's call.",
+        "goalTemplate": "Run this outreach campaign ({campaign}) on {channel}; each stage moves its status. If its type is not outreach, stop and say so. PREPARE: write the target audience, the value proposition and the call to action. Pick the people to reach from the pod (and public sources when the pod has too few), resolving each one before creating anything, link each as a member of the campaign with the lead role (lead source cold-outreach when it has none), and for each draft one first message to that person in this campaign's angle, specific to them — their company, role and any past message — never a generic template. DRAFT RULES: each draft is one proposed message in the channel of the person it is written to, filed through the pod's send door: run messaging.send with to = that person's entity id (for a company lead, its decider: when that person is not in the pod, create them through the entity door with only their own fields, such as name, role and LinkedIn URL, never the company's website, domain or email), text = the message, and provider linkedin or email. Read their channel first (synap_get_channel, mode person) for what was already said. The pod files it for a person to review in that channel; it goes out only once they approve it. Never call a tool's own send verb (Unipile, Gmail), never create an outreach touch, a note or a task holding the message, and never use synap_capture for it. Never send. A LinkedIn message is drafted whatever their reach: the pod holds a draft to someone who is not a connection yet, shows it with the next step and lets it go out once they connect, so never hold a draft back for want of a connection. Draft it, then, in this order: (1) a person with no linkedinUrl: find their profile with linkedin_find_profile (their full name and company); on a match, propose its linkedinUrl and linkedinProviderId on the person for a person to approve; on none or several, ask the person to choose among its candidates (the process \"Find their LinkedIn\" does this for one lead). (2) Read their linkedinConnection, which only the pod writes (never set it or linkedinInvitedAt): connected, nothing more; none or not set, ask to connect with linkedin_send_invite (it refuses someone already connected or already invited: then nothing more); pending, the draft waits for them; ignored, draft by email instead when they have an email address. While the draft waits for them to connect, set the lead's nextAction to \"Wait for <name> to accept the LinkedIn request\" and its nextActionAt 7 days later. An email message needs none of this. START: a person approves the audience, the offer and the list, then reviews each proposed message in its channel and approves it; nothing goes out before they approve it, and the agent never sends. Once a message is sent, follow the cadence, so \"Follow up on leads in outreach\" drafts the next one. CADENCE: when a message is sent (a person approved its proposed message, so it is an outbound message in the channel), set its lead's lastContactedAt to the sent day, count the messages sent to the lead (the outbound messages in its channels, read with synap_get_channel mode person: for a company lead, the channels of the person written to there), and set the lead's next action: after the first message, nextAction \"Follow up with <name> if no reply\" and nextActionAt the sent day + 3 days; after the first follow-up, nextAction \"Follow up with <name> a last time if no reply\" and nextActionAt the sent day + 7 days; after the second follow-up, nextAction \"No reply after two follow-ups: nurture or drop <name>\" and nextActionAt the sent day + 7 days, and when that date passes with no reply, \"Follow up on leads in outreach\" proposes nurturing. Never a third follow-up. Propose moving a lead at new or researching to outreach through the status door, with its expected status. A reply stops the cadence: a reply is an inbound message after our last outbound one in the channel, and \"Follow up on leads in outreach\" reads it and proposes the next step. FINISH: when every person written to has replied or their follow-ups ended in silence, record in the campaign notes how many messages were sent (the outbound messages in their channels), how many got a reply and how many led to a booked meeting. Pausing or cancelling is a person's call.",
         "subjectProfile": {
           "profileSlug": "campaign",
           "statusProperty": "campaign-status"

package/src/types.ts

@@ -266,6 +266,26 @@ export interface TemplateView {
   groupBy?: string;
 }
 
+/**
+ * A document a template carries. Mirrors `WorkspaceDocumentInput`
+ * (synap-backend `@synap-core/types/workspaces/definition`) VERBATIM; the pod
+ * installs it through `utils/template-documents.ts` (the one create door,
+ * system-authored, owned by the installer, identified in the space by `slug`).
+ */
+export interface TemplateDocument {
+  /** Stable id inside the template, kebab-case. Never rename it: the space knows the document by it. */
+  slug: string;
+  /** The document's name (its one title). */
+  title: string;
+  /** Markdown body; may carry `synap-cell` / `synap-section` embeds. */
+  content: string;
+  /**
+   * What its embeds read (a living document's scope): `space` = the space it
+   * is installed in, `pod` = the whole pod. Absent = no scope.
+   */
+  scope?: "space" | "pod";
+}
+
 export interface TemplateEntityLink {
   sourceProfileSlug: string;
   targetProfileSlug: string;
@@ -358,10 +378,12 @@ export interface TemplateSidebarSurface {
 }
 
 export interface TemplateSidebarItem {
-  kind: "app" | "view" | "profile" | "external" | "cell";
+  kind: "app" | "view" | "profile" | "external" | "cell" | "document";
   appId?: string;
   viewName?: string;
   viewId?: string;
+  /** kind "document": the `documents[].slug` it opens (the pod stores its id beside it). */
+  documentSlug?: string;
   profileSlug?: string;
   url?: string;
   cellKey?: string;
@@ -1075,6 +1097,15 @@ export interface WorkspaceYaml {
   /** Curated views — only the ones that add value */
   views?: TemplateView[];
 
+  /**
+   * Documents the space carries (plan 9ad4b2fc §5 lane 12, P4: a pinned set of
+   * documents hosts a space package). Installed by the pod with the views:
+   * created once per `slug` in the space, never rewritten by an update. A
+   * sidebar item `{kind: "document", documentSlug}` opens one. See
+   * {@link TemplateDocument}.
+   */
+  documents?: TemplateDocument[];
+
   /** Schema-level links between entity types */
   entityLinks?: TemplateEntityLink[];