@synap-core/workspace-templates 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/workspace-templates",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "type": "module",
   "description": "Canonical workspace definitions — YAML source + typed exports for browser, backend, CLI, and marketplace",
   "repository": {
@@ -21,6 +21,7 @@
     "./skills/*": "./skills/*",
     "./automations/*": "./automations/*",
     "./views/*": "./views/*",
+    "./agents/*": "./agents/*",
     "./package.json": "./package.json"
   },
   "files": [
@@ -30,6 +31,7 @@
     "skills",
     "automations",
     "views",
+    "agents",
     "retired.yaml"
   ],
   "dependencies": {

package/src/catalog-safety.test.ts

@@ -172,7 +172,7 @@ describe("(b) every skill reference resolves", () => {
 
 // ── (c) the content directories ship, the build reads none of them ─────────
 
-const CONTENT_DIRS = ["capabilities", "skills", "automations", "views"];
+const CONTENT_DIRS = ["capabilities", "skills", "automations", "views", "agents"];
 
 describe("(c) catalog content ships in the npm bundle; the build reads only src/*.yaml", () => {
   const pkg = JSON.parse(readFileSync(join(PKG, "package.json"), "utf8"));

package/src/crm-absorbs-outreach.template.test.ts

@@ -70,7 +70,12 @@ describe("CRM absorbs Outreach & Comms", () => {
       ["replied", "done", false],
       ["bounced", "lost", false],
       ["no_response", "lost", false],
+      ["replaced", "lost", true],
     ]);
+    // `replaced` closes a draft moved into the person's channel; an agent proposes it.
+    expect(touch?.lifecycle?.options.find((o) => o.key === "replaced")?.label).toBe("Replaced");
+    const status = touch?.properties?.find((p) => p.slug === "status");
+    expect(status?.enumValues).toContain("replaced");
     expect(crm.meta.intent?.produces?.map((p) => p.profile)).toContain("outreach-touch");
   });
 

package/src/crm-find-contact.template.test.ts

@@ -0,0 +1,121 @@
+/**
+ * "Find the right contact" (plan 87088d2d W3b, founder 2026-11-06), pinned
+ * against the REAL YAML corpus and the real validator. The CRM app (site-crm
+ * W2) codes against these names, agreed between the two lanes:
+ *
+ *   - the playbook is "Find the right contact" (slug find-the-right-contact);
+ *   - its params are `company` (entity, required) and `audience` (entity,
+ *     optional); a batch is one session whose targets are the companies;
+ *   - the company kind carries its LinkedIn page as `linkedinUrl`.
+ *
+ * Its subject, `company`, declares no lifecycle: no stage moves anything and no
+ * gate stops it (every write goes through the pod's governance instead), and
+ * the company stays the lead.
+ *
+ * Does NOT cover what an agent does at run time (the goal is prose).
+ */
+
+import { describe, expect, it } from "vitest";
+import { readYamlTemplates } from "./generate.mjs";
+import type { WorkspaceYaml } from "./types.js";
+import { validateTemplate } from "./validate.js";
+
+const NAME = "Find the right contact";
+
+const corpus = readYamlTemplates().map((t) => t.data as WorkspaceYaml);
+const crm = corpus.find((x) => x.meta.slug === "crm")!;
+const profileOf = (slug: string) => crm.profiles.find((p) => p.slug === slug);
+const pb = () => {
+  const found = crm.playbooks?.find((p) => p.name === NAME);
+  if (!found) throw new Error(`playbook "${NAME}" not in crm`);
+  return found;
+};
+
+describe("CRM — Find the right contact", () => {
+  it("crm validates against the corpus", () => {
+    expect(validateTemplate(crm, { corpus }).errors).toEqual([]);
+  });
+
+  it("the company kind carries its LinkedIn page as linkedinUrl, the identity signal person uses", () => {
+    const company = profileOf("company")?.properties.find((p) => p.slug === "linkedinUrl");
+    expect(company).toMatchObject({ valueType: "string", inputType: "url" });
+    // The same global property as the person's, never a second spelling.
+    expect(profileOf("person")?.properties.find((p) => p.slug === "linkedinUrl")).toMatchObject({ valueType: "string" });
+    const spellings = (profileOf("company")?.properties ?? []).map((p) => p.slug).filter((s) => /linkedin/i.test(s));
+    expect(spellings).toEqual(["linkedinUrl"]);
+  });
+
+  it("is one CRM playbook, named for the slug the app uses", () => {
+    const named = corpus.flatMap((t) => (t.playbooks ?? []).filter((p) => p.name === NAME).map(() => t.meta.slug));
+    expect(named).toEqual(["crm"]);
+    expect(NAME.toLowerCase().replace(/\s+/g, "-")).toBe("find-the-right-contact");
+  });
+
+  it("takes company (required) and audience (optional), and runs by hand", () => {
+    expect((pb().params ?? []).map((p) => [p.name, p.type, p.required ?? false])).toEqual([
+      ["company", "entity", true],
+      ["audience", "entity", false],
+    ]);
+    expect(pb().goalTemplate).toMatch(/\{company\}/);
+    expect(pb().goalTemplate).toMatch(/\{audience\}/);
+    expect(pb().activators).toEqual([{ on: "manual", mode: "propose" }]);
+    expect(pb().executor).toBe("is-agent");
+    expect(pb().status).toBe("active");
+    expect(pb().grants).toEqual(["entity.create"]);
+    expect(pb().requiredIntents).toEqual(["find_people", "enrich_entity"]);
+  });
+
+  it("works a company, which has no lifecycle: no stage moves it and no gate stops it", () => {
+    expect(pb().subjectProfile).toEqual({ profileSlug: "company" });
+    expect(profileOf("company")).not.toHaveProperty("lifecycle");
+    const stages = pb().stages ?? [];
+    expect(stages.map((s) => [s.key, s.category])).toEqual([
+      ["read", "planned"],
+      ["find", "started"],
+      ["file", "completed"],
+    ]);
+    expect(stages.filter((s) => s.subjectStatus || s.gate || s.onFail)).toEqual([]);
+  });
+
+  it("yields the person picked, linked works_at the company, and may yield nobody", () => {
+    expect((pb().stages ?? []).flatMap((s) => s.expectedOutputs ?? [])).toEqual([
+      { kind: "person", label: "Contact picked", relationToSubject: "works_at", optional: true },
+    ]);
+  });
+
+  it("checks its rules with criteria, within the pod's cap", () => {
+    const keys = (pb().stages ?? []).flatMap((s) => (s.criteria ?? []).map((c) => c.key));
+    expect(keys).toEqual([
+      "contact-roles-from-audience",
+      "contact-page-clear-match",
+      "contact-lookups-capped",
+      "contact-current-role",
+      "contact-identity-first",
+      "contact-linked-homed",
+      "contact-company-stays-lead",
+      "contact-report",
+    ]);
+  });
+
+  it("its goal holds the agreed process: roles, at most 5 profiles, identity first, home, reach, the company stays the lead, batch", () => {
+    const goal = pb().goalTemplate;
+    for (const part of [
+      /founder,\s+co-founder, CEO and CTO/,
+      /Never invent a role/,
+      /linkedin_search_people with keywords "<role> <company name>"/,
+      /linkedin_get_profile on at most 5 candidates/,
+      /two at most/,
+      /current role at THIS company/,
+      /resolve identity\s+first by their LinkedIn URL/,
+      /only their own fields/,
+      /never the company's website, domain or\s+email/,
+      /homeWorkspaceId/,
+      /POST \/channels\/linkedin-reach\/<personId>/,
+      /never set linkedinConnection or\s+linkedinInvitedAt/,
+      /never give the person the lead\s+role, never move the company's lead stage/,
+      /only on a clear match/,
+      /has targets/,
+    ])
+      expect(goal).toMatch(part);
+  });
+});

package/src/crm.yaml

@@ -215,6 +215,15 @@ profiles:
         label: Domain
         valueType: string
         inputType: text
+      # The company's LinkedIn page (linkedin.com/company/...), written by
+      # "Find the right contact" on a clear match only. The pod's global
+      # `linkedinUrl` property, the one `person` uses (and an identity signal),
+      # so no new definition: the system company kind declares none (plan
+      # 87088d2d W3b, 2026-11-06).
+      - slug: linkedinUrl
+        label: LinkedIn page
+        valueType: string
+        inputType: url
       - slug: industry
         label: Industry
         valueType: string
@@ -657,6 +666,11 @@ profiles:
         - { key: replied, category: done }
         - { key: bounced, category: lost }
         - { key: no_response, category: lost }
+        # A draft whose message now lives in the person's channel as a
+        # messaging.send proposal (the one send door, d5): closed, never sent
+        # from here (6 Nov 2026). A person's call like every closed touch no
+        # process owns: an agent that moves a draft PROPOSES the move.
+        - { key: replaced, label: Replaced, category: lost, humanOnly: true }
     properties:
       - slug: channel
         label: Channel
@@ -674,7 +688,7 @@ profiles:
         label: Status
         valueType: string
         inputType: select
-        enumValues: [drafted, sent, opened, replied, bounced, no_response]
+        enumValues: [drafted, sent, opened, replied, bounced, no_response, replaced]
         constraints: { defaultValue: drafted }
       - slug: sentDate
         label: Sent date
@@ -1545,6 +1559,128 @@ playbooks:
         gate: { kind: human }
         onFail: { toStage: find }
 
+  # ── Find the right contact — the decider at a company with none ──────────
+  # Plan 87088d2d W3b (founder, 6 Nov 2026): from a company lead with no contact,
+  # find the right person, link them and home them in the CRM, so "Draft a first
+  # message" has someone to write to. Contract with the CRM app (site-crm W2),
+  # fixed: params `company` (entity, required) and `audience` (entity, optional);
+  # a batch is one session whose targets are the companies.
+  # Subject `company`, which declares no lifecycle (the shape of "Score a list"
+  # on an audience): no stage moves anything, and the company stays the lead
+  # (the person gets no lead role, its leadStage never moves). The LinkedIn
+  # lookups are reads that run on their own (unipile-linkedin readOnly verbs);
+  # every write (the person, works_at, the company's linkedinUrl, the home
+  # space) goes through the pod's doors and its governance, never through a
+  # gate here: the founder is never asked how a write lands. The reach is the
+  # pod's own read (POST /channels/linkedin-reach/<personId>, backend#786), and
+  # the home space is the entity door's governed homeWorkspaceId (backend#871).
+  - name: Find the right contact
+    description: Find the person to contact at a company with no contact; read the roles from its audience, look them up on LinkedIn, pick the best one or two with a reason, and file them linked to the company and homed in the CRM; one company or a batch.
+    goalTemplate: >-
+      Find the right person to contact at the company {company}, for the
+      audience {audience} when one is given. BATCH: when this session also
+      has targets (the companies it works as a batch), do all that follows
+      for each target company, one after the other, and report each one.
+      READ: the company (its name, website, domain and linkedinUrl) and the
+      people the pod already links to it with works_at; when one of them
+      already holds a role the audience names, pick them and search nothing.
+      COMPANY PAGE: when the company has no linkedinUrl, read its website
+      (web.read) and take the LinkedIn company page (linkedin.com/company/...)
+      it links to. Store it as the company's linkedinUrl through the entity
+      door only on a clear match: the company's own website links to it, or
+      its name and its website or domain agree with the company's. Otherwise
+      store nothing and report the page you found. ROLES: read the decision
+      roles the audience names (its persona, segment and traits): the
+      audience given, else the one the company targets (its targets link).
+      When there is no audience or it names no role, look for founder,
+      co-founder, CEO and CTO, in that order. Never invent a role. SEARCH:
+      find the LinkedIn account with unipile_list_accounts (when several are
+      connected, ask the person which one reads). For each role, run
+      linkedin_search_people with keywords "<role> <company name>", then
+      linkedin_get_profile on at most 5 candidates in all, the most likely
+      first. These lookups only read. PICK: the best person for the
+      audience, two at most: a current role at THIS company (in their
+      current position, not a past one or a namesake), the most senior of
+      the roles, the best fit with the audience, and a one-line reason for
+      each. When no candidate passes, pick nobody and say what was searched.
+      FILE, through the pod's doors and its governance: resolve identity
+      first by their LinkedIn URL (synap_resolve_identity with that URL); a
+      strong match is that person, reused, and nothing is created. Otherwise
+      create the person with only their own fields: their name as title,
+      jobTitle (their current title), linkedinUrl, and linkedinProviderId
+      when the profile gives it; never the company's website, domain or
+      email. File a new person and their works_at link to the company as ONE
+      write (synap_capture with the person, the company by existingEntityId
+      and the works_at relation); for a person already in the pod, add the
+      works_at link when it is missing. Home the person in this CRM space:
+      set their homeWorkspaceId to this space with synap_update_entity (on a
+      pod whose entity door has no homeWorkspaceId, file them with this
+      space's workspaceId instead). Then measure their LinkedIn reach through
+      the pod's reach door (POST /channels/linkedin-reach/<personId>), which
+      records it on the person; never set linkedinConnection or
+      linkedinInvitedAt yourself. A write the pod files for review is
+      success: keep going, never retry it, and report it as waiting for
+      review. The company stays the lead: never give the person the lead
+      role, never move the company's lead stage, and never draft or send a
+      message or a connection request. REPORT, for each company: who was
+      picked and why, their reach, whether the company's LinkedIn page was
+      stored, only found or not found, and the next step ("Draft a first
+      message" to the person picked or, when nobody fits, what the person
+      could do instead).
+    subjectProfile:
+      profileSlug: company
+    activators:
+      - { on: manual, mode: propose }
+    params:
+      - { name: company, type: entity, label: Company, required: true }
+      - { name: audience, type: entity, label: Audience (ICP) the company came from }
+    executor: is-agent
+    status: active
+    requiredIntents: [find_people, enrich_entity]
+    grants: [entity.create]
+    stages:
+      - key: read
+        name: Read the company and the roles
+        category: planned
+        goal: Read the company, the people already linked to it and its LinkedIn page, find its page on its website when it has none, and list the roles to look for from the audience (founder, co-founder, CEO and CTO when it names none).
+        criteria:
+          - key: contact-roles-from-audience
+            statement: The roles looked for are the ones the audience names, or founder, co-founder, CEO and CTO when there is no audience or it names none; no role was invented.
+            check: { kind: judge }
+          - key: contact-page-clear-match
+            statement: The company's linkedinUrl was stored only on a clear match (its own website links to the page, or the name and the website or domain agree); otherwise nothing was stored and the page found was reported.
+            check: { kind: judge }
+      - key: find
+        name: Look the people up
+        category: started
+        goal: Search LinkedIn for each role at the company, read at most 5 profiles, and pick the best person (two at most) with a one-line reason each.
+        criteria:
+          - key: contact-lookups-capped
+            statement: linkedin_get_profile ran on at most 5 candidates per company, and only lookup verbs were called on LinkedIn.
+            check: { kind: judge }
+          - key: contact-current-role
+            statement: Each person picked (two at most) holds a current role at this company and has a one-line reason, or nobody was picked and what was searched is said.
+            check: { kind: judge }
+      - key: file
+        name: File the contact
+        category: completed
+        goal: Resolve each person picked by their LinkedIn URL, create them only if new with their own fields, link them works_at the company, home them in this CRM space, measure their reach, and report who, why, their reach and the next step.
+        expectedOutputs:
+          - { kind: person, label: Contact picked, relationToSubject: works_at, optional: true }
+        criteria:
+          - key: contact-identity-first
+            statement: Each person picked was resolved by their LinkedIn URL first; an existing person was reused, and a new one carries only their own fields (never the company's website, domain or email).
+            check: { kind: judge }
+          - key: contact-linked-homed
+            statement: Each person picked works_at the company, is homed in this CRM space and had their LinkedIn reach measured through the pod's reach door, or the write is reported as waiting for review.
+            check: { kind: judge }
+          - key: contact-company-stays-lead
+            statement: The person got no lead role, the company's lead stage did not move, and no message or connection request was drafted or sent.
+            check: { kind: judge }
+          - key: contact-report
+            statement: The report gives, for each company, who was picked and why, their reach, whether its LinkedIn page was stored, only found or not found, and the next step.
+            check: { kind: judge }
+
   # ── Follow up on leads in outreach — THE one follow-up process ───────────
   # CRM build plan A6 (founder Q4). A batch worker: each weekday it reads the
   # channels of the leads in outreach. Due with no reply, it drafts one message
@@ -1869,7 +2005,10 @@ playbooks:
     subjectProfile:
       profileSlug: outreach-touch
       statusProperty: status
-    humanOnlyStatuses: [drafted, sent, opened]
+    # No stage of this process owns these: drafted and sent come before it
+    # starts, opened is a person's record, replaced closes a draft moved into
+    # the person's channel.
+    humanOnlyStatuses: [drafted, sent, opened, replaced]
     activators:
       - { on: enters_status, status: sent, mode: run }
     params:

package/src/lead-outreach-send-door.test.ts

@@ -0,0 +1,37 @@
+/**
+ * "Lead Outreach" (the Discord Bot and Agency Skills packs) drafts through the
+ * pod's send door, like every CRM drafter (plan 87088d2d W3a, 6 Nov 2026).
+ *
+ * Its goal said "PROPOSE sending it (connect + message)" and named no door, so
+ * an agent proposed a tool's own send verb or wrote the message into a record:
+ * neither shows in CRM Messages, which lists `messaging.send` proposals. The
+ * CRM's own drafters are pinned in crm-one-send-door.template.test.ts; these
+ * two live in capability packs, which that test does not read.
+ *
+ * Does NOT cover what an agent does at run time (the goal is prose).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+type Playbook = { name: string; goalTemplate: string; description: string };
+const playbook = (pack: string) => {
+  const cap = JSON.parse(
+    readFileSync(join(import.meta.dirname, "..", "capabilities", `${pack}.capability.json`), "utf8"),
+  ) as { spec: { playbooks?: Playbook[] } };
+  return (cap.spec.playbooks ?? []).find((p) => p.name === "Lead Outreach")!;
+};
+
+describe("Lead Outreach drafts through messaging.send", () => {
+  it.each(["discord-bot", "agency-skills"])("%s: the first message is filed through messaging.send to the person, never a tool's own send verb", (pack) => {
+    const p = playbook(pack);
+    expect(p, pack).toBeDefined();
+    expect(p.goalTemplate).toMatch(/messaging\.send[^.]*to = the person's entity id/);
+    expect(p.goalTemplate).toMatch(/never a tool's own send verb|Never call a tool's own send verb/);
+    expect(p.goalTemplate).not.toMatch(/PROPOSE sending it/);
+  });
+
+  it("discord-bot: no outreach touch, note or task holds the message", () => {
+    expect(playbook("discord-bot").goalTemplate).toMatch(/never create an outreach touch, a note or a task holding the message/);
+  });
+});

package/src/templates.ts

@@ -13272,6 +13272,12 @@ const DATA = {
             "valueType": "string",
             "inputType": "text"
           },
+          {
+            "slug": "linkedinUrl",
+            "label": "LinkedIn page",
+            "valueType": "string",
+            "inputType": "url"
+          },
           {
             "slug": "industry",
             "label": "Industry",
@@ -13857,6 +13863,12 @@ const DATA = {
             {
               "key": "no_response",
               "category": "lost"
+            },
+            {
+              "key": "replaced",
+              "label": "Replaced",
+              "category": "lost",
+              "humanOnly": true
             }
           ]
         },
@@ -13895,7 +13907,8 @@ const DATA = {
               "opened",
               "replied",
               "bounced",
-              "no_response"
+              "no_response",
+              "replaced"
             ],
             "constraints": {
               "defaultValue": "drafted"
@@ -14880,6 +14893,132 @@ const DATA = {
           }
         ]
       },
+      {
+        "name": "Find the right contact",
+        "description": "Find the person to contact at a company with no contact; read the roles from its audience, look them up on LinkedIn, pick the best one or two with a reason, and file them linked to the company and homed in the CRM; one company or a batch.",
+        "goalTemplate": "Find the right person to contact at the company {company}, for the audience {audience} when one is given. BATCH: when this session also has targets (the companies it works as a batch), do all that follows for each target company, one after the other, and report each one. READ: the company (its name, website, domain and linkedinUrl) and the people the pod already links to it with works_at; when one of them already holds a role the audience names, pick them and search nothing. COMPANY PAGE: when the company has no linkedinUrl, read its website (web.read) and take the LinkedIn company page (linkedin.com/company/...) it links to. Store it as the company's linkedinUrl through the entity door only on a clear match: the company's own website links to it, or its name and its website or domain agree with the company's. Otherwise store nothing and report the page you found. ROLES: read the decision roles the audience names (its persona, segment and traits): the audience given, else the one the company targets (its targets link). When there is no audience or it names no role, look for founder, co-founder, CEO and CTO, in that order. Never invent a role. SEARCH: find the LinkedIn account with unipile_list_accounts (when several are connected, ask the person which one reads). For each role, run linkedin_search_people with keywords \"<role> <company name>\", then linkedin_get_profile on at most 5 candidates in all, the most likely first. These lookups only read. PICK: the best person for the audience, two at most: a current role at THIS company (in their current position, not a past one or a namesake), the most senior of the roles, the best fit with the audience, and a one-line reason for each. When no candidate passes, pick nobody and say what was searched. FILE, through the pod's doors and its governance: resolve identity first by their LinkedIn URL (synap_resolve_identity with that URL); a strong match is that person, reused, and nothing is created. Otherwise create the person with only their own fields: their name as title, jobTitle (their current title), linkedinUrl, and linkedinProviderId when the profile gives it; never the company's website, domain or email. File a new person and their works_at link to the company as ONE write (synap_capture with the person, the company by existingEntityId and the works_at relation); for a person already in the pod, add the works_at link when it is missing. Home the person in this CRM space: set their homeWorkspaceId to this space with synap_update_entity (on a pod whose entity door has no homeWorkspaceId, file them with this space's workspaceId instead). Then measure their LinkedIn reach through the pod's reach door (POST /channels/linkedin-reach/<personId>), which records it on the person; never set linkedinConnection or linkedinInvitedAt yourself. A write the pod files for review is success: keep going, never retry it, and report it as waiting for review. The company stays the lead: never give the person the lead role, never move the company's lead stage, and never draft or send a message or a connection request. REPORT, for each company: who was picked and why, their reach, whether the company's LinkedIn page was stored, only found or not found, and the next step (\"Draft a first message\" to the person picked or, when nobody fits, what the person could do instead).",
+        "subjectProfile": {
+          "profileSlug": "company"
+        },
+        "activators": [
+          {
+            "on": "manual",
+            "mode": "propose"
+          }
+        ],
+        "params": [
+          {
+            "name": "company",
+            "type": "entity",
+            "label": "Company",
+            "required": true
+          },
+          {
+            "name": "audience",
+            "type": "entity",
+            "label": "Audience (ICP) the company came from"
+          }
+        ],
+        "executor": "is-agent",
+        "status": "active",
+        "requiredIntents": [
+          "find_people",
+          "enrich_entity"
+        ],
+        "grants": [
+          "entity.create"
+        ],
+        "stages": [
+          {
+            "key": "read",
+            "name": "Read the company and the roles",
+            "category": "planned",
+            "goal": "Read the company, the people already linked to it and its LinkedIn page, find its page on its website when it has none, and list the roles to look for from the audience (founder, co-founder, CEO and CTO when it names none).",
+            "criteria": [
+              {
+                "key": "contact-roles-from-audience",
+                "statement": "The roles looked for are the ones the audience names, or founder, co-founder, CEO and CTO when there is no audience or it names none; no role was invented.",
+                "check": {
+                  "kind": "judge"
+                }
+              },
+              {
+                "key": "contact-page-clear-match",
+                "statement": "The company's linkedinUrl was stored only on a clear match (its own website links to the page, or the name and the website or domain agree); otherwise nothing was stored and the page found was reported.",
+                "check": {
+                  "kind": "judge"
+                }
+              }
+            ]
+          },
+          {
+            "key": "find",
+            "name": "Look the people up",
+            "category": "started",
+            "goal": "Search LinkedIn for each role at the company, read at most 5 profiles, and pick the best person (two at most) with a one-line reason each.",
+            "criteria": [
+              {
+                "key": "contact-lookups-capped",
+                "statement": "linkedin_get_profile ran on at most 5 candidates per company, and only lookup verbs were called on LinkedIn.",
+                "check": {
+                  "kind": "judge"
+                }
+              },
+              {
+                "key": "contact-current-role",
+                "statement": "Each person picked (two at most) holds a current role at this company and has a one-line reason, or nobody was picked and what was searched is said.",
+                "check": {
+                  "kind": "judge"
+                }
+              }
+            ]
+          },
+          {
+            "key": "file",
+            "name": "File the contact",
+            "category": "completed",
+            "goal": "Resolve each person picked by their LinkedIn URL, create them only if new with their own fields, link them works_at the company, home them in this CRM space, measure their reach, and report who, why, their reach and the next step.",
+            "expectedOutputs": [
+              {
+                "kind": "person",
+                "label": "Contact picked",
+                "relationToSubject": "works_at",
+                "optional": true
+              }
+            ],
+            "criteria": [
+              {
+                "key": "contact-identity-first",
+                "statement": "Each person picked was resolved by their LinkedIn URL first; an existing person was reused, and a new one carries only their own fields (never the company's website, domain or email).",
+                "check": {
+                  "kind": "judge"
+                }
+              },
+              {
+                "key": "contact-linked-homed",
+                "statement": "Each person picked works_at the company, is homed in this CRM space and had their LinkedIn reach measured through the pod's reach door, or the write is reported as waiting for review.",
+                "check": {
+                  "kind": "judge"
+                }
+              },
+              {
+                "key": "contact-company-stays-lead",
+                "statement": "The person got no lead role, the company's lead stage did not move, and no message or connection request was drafted or sent.",
+                "check": {
+                  "kind": "judge"
+                }
+              },
+              {
+                "key": "contact-report",
+                "statement": "The report gives, for each company, who was picked and why, their reach, whether its LinkedIn page was stored, only found or not found, and the next step.",
+                "check": {
+                  "kind": "judge"
+                }
+              }
+            ]
+          }
+        ]
+      },
       {
         "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.",
@@ -15086,7 +15225,8 @@ const DATA = {
         "humanOnlyStatuses": [
           "drafted",
           "sent",
-          "opened"
+          "opened",
+          "replaced"
         ],
         "activators": [
           {

package/src/unipile-linkedin-find-profile.test.ts

@@ -70,7 +70,8 @@ describe("linkedin_find_profile — a strict match or none", () => {
   it("is a read the pod runs at once, routed by enrich_entity, and carries no install-time value", () => {
     expect(verb.kind).toBe("code");
     expect(verb.intent).toBe("enrich_entity");
-    expect(verb.metadata).toEqual({ verbType: "read" });
+    // Declared read-only: the pod runs it with no review (plan 87088d2d W3c).
+    expect(verb.metadata).toEqual({ verbType: "read", readOnly: true });
     expect(verb.parameters).toEqual({ fullName: "string", company: "string", accountId: "string" });
     expect(verb.requires).toEqual(["unipile_linkedin"]);
     expect(verb.code).not.toMatch(/\{\{\w+\}\}/);

package/src/unipile-lookups-read-only.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Unipile — a lookup runs on its own, a write waits for review (plan 87088d2d
+ * W3c, 6 Nov 2026).
+ *
+ * Every Unipile lookup used to wait for a review: the applier seeds each verb
+ * at `propose`, and only a verb whose definition DECLARES
+ * `metadata.readOnly: true` is run by the pod's gate with no review
+ * (backend `verbDeclaresReadOnly`, `execute-capability.ts`). A lookup reads
+ * LinkedIn or a conversation and writes nothing, in the pod or outside it, so
+ * it declares itself read-only. A verb that sends, invites, posts, opens a
+ * chat, makes a hosted-auth link or captures people into the pod writes, so it
+ * never does.
+ *
+ * Widening `readOnly` on an approved skill makes the pod ask for its approval
+ * again (backend `SKILL_METADATA_READ_ONLY`): the person approves each lookup
+ * once, then it runs on its own.
+ *
+ * NOT covered: the pod's gate itself (backend tests), and the catalog
+ * validator's refusal of a declarative write that says read-only
+ * (`scripts/catalog-lib.test.ts`).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const capability = JSON.parse(
+  readFileSync(join(import.meta.dirname, "..", "capabilities", "unipile-linkedin.capability.json"), "utf8"),
+) as { spec: { skills: Array<{ name: string; metadata?: { readOnly?: unknown } }> } };
+
+const LOOKUPS = [
+  "unipile_list_accounts",
+  "unipile_get_account",
+  "unipile_list_conversations",
+  "unipile_list_messages",
+  "linkedin_search_people",
+  "linkedin_get_profile",
+  "linkedin_find_profile",
+  "linkedin_list_relations",
+  "linkedin_list_invitations",
+  "linkedin_list_company_pages",
+];
+const WRITES = [
+  "unipile_create_hosted_auth",
+  "unipile_send_message",
+  "unipile_start_chat",
+  "linkedin_capture_profiles",
+  "linkedin_send_invite",
+  "linkedin_send_first_message",
+  "unipile_publish_post",
+];
+
+describe("Unipile — a lookup runs on its own, a write waits for review", () => {
+  const names = capability.spec.skills.map((s) => s.name);
+
+  it("every verb of the pack is either a lookup or a write", () => {
+    expect([...names].sort()).toEqual([...LOOKUPS, ...WRITES].sort());
+  });
+
+  it.each(LOOKUPS)("%s declares metadata.readOnly: true", (name) => {
+    expect(capability.spec.skills.find((s) => s.name === name)?.metadata?.readOnly).toBe(true);
+  });
+
+  it.each(WRITES)("%s does not declare itself read-only", (name) => {
+    expect(capability.spec.skills.find((s) => s.name === name)?.metadata?.readOnly).not.toBe(true);
+  });
+});