@synap-core/workspace-templates 0.12.0 → 0.24.0

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

@@ -0,0 +1,183 @@
+/**
+ * Unipile — finding ONE known person's LinkedIn profile, and paging the people
+ * search (CRM wave 2, S4b, build map 6f6c197f).
+ *
+ *  - `linkedin_find_profile` answers a profile only on a STRICT match: the
+ *    result's name equals the full name (case- and accent-insensitive), the
+ *    company is in its headline as whole words, and exactly one result is
+ *    both. Otherwise no match, with up to 3 candidates for a person to choose
+ *    from. It writes nothing: the match's fields are the caller's proposal
+ *    (founder decision 7).
+ *  - `linkedin_search_people` and `linkedin_capture_profiles` page by
+ *    `cursor`, the reply's `next_cursor` (Unipile v2 performClassicPeopleSearch
+ *    takes a `cursor` query param and no offset or limit).
+ *
+ * SEAM: each verb's REAL `code` body, run the way the pod's executor wraps it
+ * (`async (args, context) => { <code> }` with `callProvider` and `propose` in
+ * scope), against a recorded `callProvider` that answers page by page.
+ *
+ * NOT covered: what a live LinkedIn search returns (ranking, how the
+ * `advanced_keywords.company` filter matches, headline wording), and the pod's
+ * governance of the read (finding 4c31855b: a read once came back proposed;
+ * the verb then returns `proposed`, tested below with a stubbed answer).
+ */
+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<Record<string, any>> } };
+const skill = (name: string) => capability.spec.skills.find((s) => s.name === name)!;
+
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as new (
+  ...args: string[]
+) => (...a: unknown[]) => Promise<any>;
+
+type Call = { tool: string; method: string; path: string; body: Record<string, unknown> };
+type Page = { data: Array<Record<string, unknown>>; next_cursor?: string | null };
+
+/** Runs `name`'s code; `pages` answers the provider calls in order (the last one repeats). */
+async function run(name: string, args: Record<string, unknown>, pages: Array<Page | Record<string, unknown>>) {
+  const calls: Call[] = [];
+  const proposals: Array<Record<string, unknown>> = [];
+  const callProvider = async (tool: string, method: string, path: string, body: Record<string, unknown>) => {
+    calls.push({ tool, method, path, body });
+    const reply = pages[Math.min(calls.length - 1, pages.length - 1)];
+    return "proposed" in reply ? reply : { status: 200, body: reply };
+  };
+  const propose = { entity: async (input: Record<string, unknown>) => (proposals.push(input), { status: "proposed" }) };
+  const body = new AsyncFunction("args", "context", "callProvider", "propose", skill(name).code);
+  const result = await body(args, {}, callProvider, propose);
+  return { result, calls, proposals };
+}
+
+const row = (id: string, display_name: string, headline: string) => ({
+  object: "PeopleSearchResult",
+  id,
+  display_name,
+  headline,
+  public_identifier: `${id}-slug`,
+  profile_url: `https://www.linkedin.com/in/${id}-slug`,
+  network_distance: "SECOND_DEGREE",
+});
+const ADA = row("u-ada", "Adèle Lovelace", "CEO at Analytical Engines · Paris");
+const ARGS = { accountId: "acc_1", fullName: "adele  LOVELACE", company: "Analytical Engines" };
+
+describe("linkedin_find_profile — a strict match or none", () => {
+  const verb = skill("linkedin_find_profile");
+
+  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" });
+    expect(verb.parameters).toEqual({ fullName: "string", company: "string", accountId: "string" });
+    expect(verb.requires).toEqual(["unipile_linkedin"]);
+    expect(verb.code).not.toMatch(/\{\{\w+\}\}/);
+    // It writes nothing: the match is the caller's proposal (decision 7).
+    expect(verb.code).not.toMatch(/propose\.entity|callProvider\([^)]*'(PATCH|PUT|DELETE)'/);
+  });
+
+  it("one result with the same name (case and accents aside) and the company in its headline: the match", async () => {
+    const other = row("u-2", "Ada Byron", "Engineer at Analytical Engines");
+    const { result, calls, proposals } = await run("linkedin_find_profile", ARGS, [{ data: [other, ADA], next_cursor: null }]);
+    expect(result.matched).toBe(true);
+    expect(result.profile).toMatchObject({ name: "Adèle Lovelace", providerId: "u-ada", publicIdentifier: "u-ada-slug" });
+    expect(result.properties).toEqual({ linkedinUrl: "https://www.linkedin.com/in/u-ada-slug", linkedinProviderId: "u-ada" });
+    expect(result.candidates).toEqual([]);
+    expect(proposals).toEqual([]);
+    expect(calls).toEqual([
+      {
+        tool: "unipile_linkedin",
+        method: "POST",
+        path: "/acc_1/linkedin/search/people",
+        body: { keywords: "adele  LOVELACE", advanced_keywords: { company: "Analytical Engines" } },
+      },
+    ]);
+  });
+
+  it("two results that both match: no match, both offered as candidates", async () => {
+    const twin = row("u-twin", "Adele Lovelace", "Analytical Engines, board member");
+    const { result } = await run("linkedin_find_profile", ARGS, [{ data: [ADA, twin] }]);
+    expect(result).toMatchObject({ matched: false, reason: "several" });
+    expect(result.candidates.map((c: any) => c.providerId)).toEqual(["u-ada", "u-twin"]);
+    expect(result.properties).toBeUndefined();
+  });
+
+  it("the name matches but the company is not in the headline, or only inside another word: no match", async () => {
+    const elsewhere = row("u-3", "Adèle Lovelace", "Founder at Difference Engines");
+    const inside = row("u-4", "Adèle Lovelace", "CTO at AnalyticalEnginesCo");
+    const { result } = await run("linkedin_find_profile", ARGS, [{ data: [elsewhere, inside] }]);
+    expect(result).toMatchObject({ matched: false, reason: "none" });
+    expect(result.candidates.map((c: any) => [c.providerId, c.nameMatches, c.companyInHeadline])).toEqual([
+      ["u-3", true, false],
+      ["u-4", true, false],
+    ]);
+  });
+
+  it("a different name with the right company is never a match, and at most 3 candidates come back, closest first", async () => {
+    const rows = [
+      row("a", "Ada Lovelace", "CEO at Analytical Engines"),
+      row("b", "Bob Smith", "Sales"),
+      row("c", "Adèle Lovelace", "Poet"),
+      row("d", "Carol King", "Analytical Engines"),
+    ];
+    const { result } = await run("linkedin_find_profile", ARGS, [{ data: rows }]);
+    expect(result).toMatchObject({ matched: false, reason: "none" });
+    expect(result.candidates.map((c: any) => c.providerId)).toEqual(["c", "a", "d"]);
+  });
+
+  it("pages by cursor: a match on page 2 with no page after it is the match", async () => {
+    const { result, calls } = await run("linkedin_find_profile", ARGS, [
+      { data: [row("x", "Someone Else", "Analytical Engines")], next_cursor: "c2" },
+      { data: [ADA], next_cursor: null },
+    ]);
+    expect(result.matched).toBe(true);
+    expect(calls.map((c) => c.path)).toEqual(["/acc_1/linkedin/search/people", "/acc_1/linkedin/search/people?cursor=c2"]);
+  });
+
+  it("a third page left unread could hold another match: no match (more_results), and it stops after 2 pages", async () => {
+    const { result, calls } = await run("linkedin_find_profile", ARGS, [
+      { data: [ADA], next_cursor: "c2" },
+      { data: [row("y", "Other", "x")], next_cursor: "c3" },
+    ]);
+    expect(result).toMatchObject({ matched: false, reason: "more_results" });
+    expect(result.searched).toMatchObject({ pages: 2, moreUnread: true });
+    expect(calls).toHaveLength(2);
+  });
+
+  it("a search the pod held for review is no match and says so", async () => {
+    const { result } = await run("linkedin_find_profile", ARGS, [{ proposed: true, proposalId: "p-1" }]);
+    expect(result).toEqual({ matched: false, reason: "proposed", proposed: true, proposalId: "p-1", candidates: [] });
+  });
+
+  it("a failed search throws; a missing company or name is refused before any call", async () => {
+    await expect(run("linkedin_find_profile", ARGS, [{ proposed: false, status: 429 } as any])).rejects.toThrow(/status 429/);
+    await expect(run("linkedin_find_profile", { ...ARGS, company: " " }, [{ data: [] }])).rejects.toThrow(/company is required/);
+    await expect(run("linkedin_find_profile", { ...ARGS, fullName: "" }, [{ data: [] }])).rejects.toThrow(/fullName/);
+  });
+});
+
+describe("the people search pages by cursor", () => {
+  it.each(["linkedin_search_people", "linkedin_capture_profiles"])("%s takes a cursor and returns the next one", async (name) => {
+    expect(skill(name).parameters.cursor).toBe("string?");
+    const first = await run(name, { accountId: "acc_1", keywords: "founders lyon" }, [{ data: [ADA], next_cursor: "n2" }]);
+    expect(first.calls[0].path).toBe("/acc_1/linkedin/search/people");
+    expect(first.calls[0].body).toEqual({ keywords: "founders lyon" });
+    expect(first.result.cursor).toBe("n2");
+
+    const second = await run(name, { accountId: "acc_1", keywords: "founders lyon", cursor: "n2" }, [{ data: [ADA], next_cursor: null }]);
+    expect(second.calls[0].path).toBe("/acc_1/linkedin/search/people?cursor=n2");
+    expect(second.result.cursor).toBeNull();
+    // v2 takes no offset or limit: page 2 is reached by the cursor alone (the
+    // exact paths above carry no other query param).
+  });
+
+  it("capture still proposes each row of the page, and search still returns them", async () => {
+    const capture = await run("linkedin_capture_profiles", { accountId: "acc_1", keywords: "k", cursor: "n2" }, [{ data: [ADA] }]);
+    expect(capture.proposals).toHaveLength(1);
+    expect(capture.proposals[0]).toMatchObject({ profileSlug: "person", title: "Adèle Lovelace" });
+    const search = await run("linkedin_search_people", { accountId: "acc_1", keywords: "k", limit: 1 }, [{ data: [ADA, ADA] }]);
+    expect(search.result.count).toBe(1);
+  });
+});

package/src/unipile-publish-post.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Unipile — what a pod app may ask it to publish (intent actions, decision
+ * ef0e917c, 2026-10-28; the Postiz precedent is postiz-contract.test.ts).
+ *
+ * A pod app asks the person's tools for `publish_post` with ONE input
+ * `{ text, media?, link?, when? }`. Unipile reaches several accounts through one
+ * key, so `unipile_publish_post` names an account source and the pod offers one
+ * action per account: the shared `unipile_list_accounts`, every provider, so
+ * LinkedIn and Instagram each get their own action (founder, 28 Oct, on
+ * decision 34103d1b). The post's images and videos come as `file[]:bytes`
+ * (phase 2c of plan e7c3c98e): the code holds one handle per pod file and the
+ * pod streams the bytes into a multipart part, so Instagram can post.
+ *
+ * SEAM: the verb's REAL `code` body, run the way the pod's executor wraps it
+ * (`async (args, context) => { <code> }` with `callProvider` in scope), against
+ * a recorded `callProvider`.
+ *
+ * NOT covered: the pod's own checks of the map and of `file[]:bytes`
+ * (backend `intent-input.ts`, `file-parameters.ts`), the handles turning into
+ * bytes (backend `pod-file-body.ts`), and whether Unipile accepts the request
+ * (not exercised against a live Unipile).
+ */
+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<Record<string, any>>; provides?: string[] } };
+
+const skill = (name: string) => capability.spec.skills.find((s) => s.name === name)!;
+const verb = skill("unipile_publish_post");
+
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as new (
+  ...args: string[]
+) => (...a: unknown[]) => Promise<unknown>;
+
+type Call = { tool: string; method: string; path: string; body: Record<string, unknown>; opts?: Record<string, unknown> };
+async function run(args: Record<string, unknown>, reply: Record<string, unknown> = { status: 201, body: { id: "p1", share_url: "https://x/p1" } }) {
+  const calls: Call[] = [];
+  const callProvider = async (tool: string, method: string, path: string, body: Record<string, unknown>, opts?: Record<string, unknown>) => {
+    calls.push({ tool, method, path, body, opts });
+    return reply;
+  };
+  const body = new AsyncFunction("args", "context", "callProvider", "propose", verb.code);
+  const result = await body(args, {}, callProvider, {});
+  return { result, calls };
+}
+
+describe("Unipile — what a pod app may ask it to publish", () => {
+  it("unipile_publish_post maps the text, the media and the account picked from unipile_list_accounts", () => {
+    expect(verb.intent).toBe("publish_post");
+    expect(verb.metadata).toEqual({ verbType: "write" });
+    expect(verb.inputMap).toEqual({
+      params: { text: "$.text", accountId: "$account.id", provider: "$account.provider", media: "$.media" },
+      accounts: { verb: "unipile_list_accounts", id: "id", label: "name", provider: "provider" },
+    });
+    expect(capability.spec.provides).toContain("publish_post");
+  });
+
+  it("Unipile has no scheduling and links stay out: the map never reads when or link", () => {
+    const read = Object.values(verb.inputMap.params).filter((s) => !String(s).startsWith("$account."));
+    expect(read.sort()).toEqual(["$.media", "$.text"]);
+  });
+
+  it("the media are pod files sent as bytes, so the verb is code run in the pod, toward its own tool", () => {
+    expect(verb.kind).toBe("code");
+    expect(verb.executionMode).not.toBe("box");
+    expect(verb.parameters).toEqual({
+      accountId: "string",
+      text: "string",
+      provider: "string?",
+      media: "file[]:bytes?",
+      postAs: "string?",
+      quotedPostId: "string?",
+    });
+    expect(verb.requires).toEqual(["unipile_linkedin"]);
+    // An install-time value in the code would stop the pod updating Unipile.
+    expect(verb.code).not.toMatch(/\{\{\w+\}\}/);
+  });
+
+  it("text alone is a JSON post of exactly { text } to /{accountId}/posts", async () => {
+    const { result, calls } = await run({ accountId: "acc_1", text: "Hello", provider: "linkedin" });
+    expect(calls).toEqual([{ tool: "unipile_linkedin", method: "POST", path: "/acc_1/posts", body: { text: "Hello" }, opts: undefined }]);
+    expect(result).toEqual({ postId: "p1", shareUrl: "https://x/p1", attachments: 0 });
+  });
+
+  it("with media, a multipart form: the text field and one attachments[i] part per pod file", async () => {
+    const { result, calls } = await run({ accountId: "acc_2", text: "Caption", provider: "instagram", media: ["podfile:a", "podfile:b"] });
+    expect(calls).toEqual([
+      {
+        tool: "unipile_linkedin",
+        method: "POST",
+        path: "/acc_2/posts",
+        body: { text: "Caption", "attachments[0]": "podfile:a", "attachments[1]": "podfile:b" },
+        opts: { multipart: true },
+      },
+    ]);
+    expect(result).toMatchObject({ postId: "p1", attachments: 2 });
+  });
+
+  it("refuses before any call: Instagram with no media, an account with no posts, no text", async () => {
+    await expect(run({ accountId: "acc_2", text: "Caption", provider: "instagram" })).rejects.toThrow(/Instagram needs at least one image or video/);
+    await expect(run({ accountId: "acc_3", text: "Hi", provider: "whatsapp" })).rejects.toThrow(/whatsapp account has no posts/);
+    await expect(run({ accountId: "acc_1", text: " ", provider: "linkedin" })).rejects.toThrow(/text is required/);
+  });
+
+  it("as a LinkedIn company page: post_as beside the text, as JSON and in the multipart form", async () => {
+    const { calls } = await run({ accountId: "acc_1", text: "Hello", provider: "linkedin", postAs: "12345" });
+    expect(calls[0]).toMatchObject({ path: "/acc_1/posts", body: { text: "Hello", post_as: "12345" }, opts: undefined });
+    const multi = await run({ accountId: "acc_1", text: "Hi", provider: "linkedin", postAs: "12345", media: ["podfile:a"] });
+    expect(multi.calls[0]).toMatchObject({ body: { text: "Hi", post_as: "12345", "attachments[0]": "podfile:a" }, opts: { multipart: true } });
+  });
+
+  it("a repost: quoted_post_id, with empty text a plain repost, with text a quote", async () => {
+    const plain = await run({ accountId: "acc_1", text: "", provider: "linkedin", quotedPostId: "WzEy" });
+    expect(plain.calls[0].body).toEqual({ text: "", quoted_post_id: "WzEy" });
+    const quote = await run({ accountId: "acc_1", text: "Worth a read", quotedPostId: "WzEy", postAs: "12345" });
+    expect(quote.calls[0].body).toEqual({ text: "Worth a read", post_as: "12345", quoted_post_id: "WzEy" });
+  });
+
+  it("an empty company page or original is left out, and Instagram refuses both before any call", async () => {
+    const { calls } = await run({ accountId: "acc_1", text: "Hello", provider: "linkedin", postAs: " ", quotedPostId: "" });
+    expect(calls[0].body).toEqual({ text: "Hello" });
+    await expect(run({ accountId: "acc_2", text: "C", provider: "instagram", media: ["podfile:a"], quotedPostId: "WzEy" })).rejects.toThrow(/Instagram has no company page post or repost/);
+    await expect(run({ accountId: "acc_2", text: "C", provider: "instagram", media: ["podfile:a"], postAs: "1" })).rejects.toThrow(/Instagram has no company page post or repost/);
+  });
+
+  it("linkedin_list_company_pages: a read of the same tool, listing each page's id and name", () => {
+    const pages = skill("linkedin_list_company_pages");
+    expect(pages).toMatchObject({ intent: "list_records", kind: "declarative", metadata: { readOnly: true }, parameters: { accountId: "string" } });
+    expect(pages.requires).toEqual(verb.requires);
+    expect(pages.providerSpec).toMatchObject({
+      tool: "unipile_linkedin",
+      method: "GET",
+      pathTemplate: "/{{accountId}}/linkedin/company/pages",
+      responseShape: { collectionPath: "data", item: { id: "id", name: "name" } },
+    });
+    // A read never maps into an app's intent: nothing publishes through it.
+    expect(pages.inputMap).toBeUndefined();
+  });
+
+  it("a refused post throws, and a proposed call is never reported as published", async () => {
+    await expect(run({ accountId: "acc_1", text: "Hello" }, { status: 422, body: {} })).rejects.toThrow(/status 422/);
+    const { result } = await run({ accountId: "acc_1", text: "Hello" }, { proposed: true, proposalId: "pr1" });
+    expect(result).toEqual({ success: false, proposed: true, proposalId: "pr1" });
+  });
+
+  it("the account source is a read of the same tool that lists every account with the fields it names", () => {
+    const list = skill("unipile_list_accounts");
+    expect(list.metadata).toEqual({ readOnly: true });
+    expect(list.requires).toEqual(verb.requires);
+    expect(list.providerSpec).toMatchObject({ method: "GET", pathTemplate: "/accounts/" });
+    expect(list.providerSpec.query).toBeUndefined();
+    expect(Object.keys(list.providerSpec.responseShape.item)).toEqual(expect.arrayContaining(["id", "name", "provider"]));
+  });
+
+  it("one Unipile verb publishes for apps", () => {
+    const mapped = capability.spec.skills.filter((s) => s.inputMap && s.intent === "publish_post").map((s) => s.name);
+    expect(mapped).toEqual(["unipile_publish_post"]);
+  });
+});

package/src/validate-flow.drift.test.ts

@@ -22,6 +22,7 @@ import { describe, expect, it } from "vitest";
 import { readFileSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { stripComments } from "../../design-tokens/scripts/strip-comments.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const OWN_COPY = join(HERE, "validate-flow.ts");
@@ -40,11 +41,9 @@ const BACKEND_COPY = join(
  *     normalize whitespace.
  */
 function normalizeFlowValidatorSource(src: string): string {
-  return src
+  return stripComments(src, "ts")
     .replace(/import type \{[^}]*\} from ["']@synap\/database["'];/g, "")
     .replace(/type AssertExact<[\s\S]*?void _outputTypesInSync;/g, "")
-    .replace(/\/\*[\s\S]*?\*\//g, "") // block comments (incl. JSDoc)
-    .replace(/\/\/.*$/gm, "") // line + trailing comments
     .split("\n")
     .map((l) => l.replace(/\s+/g, " ").trim())
     .filter((l) => l.length > 0)

package/src/validate-flow.ts

@@ -35,6 +35,7 @@
  * Until then: keep the constant arrays below identical to `@synap/database`
  * `schema/automations.ts`.
  */
+import { PLAYBOOK_RUN_MODES } from "@synap-core/types/automations";
 
 // ── Contract constants (mirror schema/automations.ts — keep in sync) ──────────
 
@@ -65,9 +66,10 @@ export const FLOW_NODE_TYPES = [
   "playbook_run",
 ] as const;
 
-/** The 11 output types — `OutputNodeDef.data.outputType` (schema/automations.ts). */
+/** The 15 output types — `OutputNodeDef.data.outputType` (schema/automations.ts). */
 export const FLOW_OUTPUT_TYPES = [
   "notification",
+  "record_observation",
   "entity_create",
   "entity_update",
   "facet_attach",
@@ -77,6 +79,9 @@ export const FLOW_OUTPUT_TYPES = [
   "webhook",
   "channel_message",
   "session_update",
+  "complete_outcome",
+  "post_evidence",
+  "reevaluate_criterion",
   "set_state",
 ] as const;
 
@@ -380,6 +385,21 @@ export function validateFlowDefinition(
             }) that does not exist.`,
           });
         }
+        // An unknown `mode` would silently RUN (`readPlaybookRunMode` reads it
+        // as the default) — the opposite of what an author who typed
+        // "propose" wanted. Refused by name at the door instead.
+        if (
+          data.mode !== undefined &&
+          !(PLAYBOOK_RUN_MODES as readonly unknown[]).includes(data.mode)
+        ) {
+          errors.push({
+            nodeId,
+            code: "playbook_run_bad_mode",
+            message: `Playbook-run node "${nodeId}" has mode ${JSON.stringify(
+              data.mode
+            )}; expected one of ${PLAYBOOK_RUN_MODES.join(", ")}.`,
+          });
+        }
         break;
       }
 
@@ -671,7 +691,7 @@ function collectLoopBindingRefs(data: unknown): string[] {
       // never evaluates (`_filterNote` and friends explain what DOWNSTREAM
       // nodes do, and so legitimately quote `{{loop.item...}}` in prose).
       // Reading them as live references made a correct flow fail validation:
-      // `stellar-grant-client` was reported as "references {{loop.item}} but is
+      // a (since-removed) grant capability was reported as "references {{loop.item}} but is
       // not inside a loop body" purely because its note DESCRIBED the nodes
       // that do. Kept identical in all three copies of this walker.
       for (const [k, x] of Object.entries(v)) {

package/src/validate-onboarding.test.ts

@@ -85,4 +85,63 @@ describe("validateTemplate onboarding contract", () => {
       ])
     );
   });
+
+  it("a steady-state brief needs no interview: purpose + anchors + fetch is valid", () => {
+    const result = validateTemplate(
+      templateWithOnboarding({
+        purpose: "Where records live.",
+        anchors: [{ profileSlug: "record", role: "root", limit: 1 }],
+        fetch: [{ profileSlug: "record", note: "the live ones" }],
+      }),
+      {}
+    );
+    expect(result, JSON.stringify(result.errors)).toEqual({ ok: true, errors: [] });
+  });
+
+  it("an interview still requires its persona and collect targets", () => {
+    const result = validateTemplate(
+      templateWithOnboarding({ goal: "Set it up.", openingQuestions: ["Why?"] }),
+      {}
+    );
+    expect(result.errors.map((e) => e.rule)).toEqual(
+      expect.arrayContaining(["onboarding-framing-empty", "onboarding-collect-empty"])
+    );
+  });
+
+  it("rejects a brief that says nothing, bad anchors, bad fetch hints and bad minimums", () => {
+    const result = validateTemplate(
+      templateWithOnboarding({
+        anchors: [
+          { profileSlug: "record", role: "root", seedRef: "Nope" },
+          { profileSlug: "record", role: "root" },
+          { profileSlug: "ghost", role: "context" },
+        ],
+        fetch: [{ note: "no target" }],
+        collect: [{ profileSlug: "record", what: "x", min: 0 }],
+      }),
+      {}
+    );
+    expect(result.errors.map((e) => e.rule)).toEqual(
+      expect.arrayContaining([
+        "onboarding-brief-empty",
+        "onboarding-anchor-seedref-unknown",
+        "onboarding-anchor-invalid",
+        "onboarding-fetch-invalid",
+        "onboarding-collect-min-invalid",
+      ])
+    );
+  });
+
+  it("template rules need a unique kebab key and an intent", () => {
+    const tpl = templateWithOnboarding(undefined);
+    tpl.rules = [
+      { key: "use-approved", intent: "Use approved assets first." },
+      { key: "use-approved", intent: "Dup." },
+      { key: "Bad Key", intent: "" },
+    ];
+    const rules = validateTemplate(tpl, {}).errors.map((e) => e.rule);
+    expect(rules).toEqual(
+      expect.arrayContaining(["rule-key-duplicate", "rule-key-invalid", "rule-intent-empty"])
+    );
+  });
 });

package/src/validate.test.ts

@@ -15,7 +15,7 @@ import type { WorkspaceYaml } from "./types.js";
 describe("validateTemplate — fires on a bad template", () => {
   const bad = {
     // meta.slug MISSING — required field.
-    meta: { name: "Bad", description: "d", icon: "x", color: "#000000" },
+    meta: { name: "Bad", description: "d", icon: "x", color: "violet" },
     workspace: { name: "Bad", description: "d" },
     profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
     automations: [
@@ -65,7 +65,7 @@ describe("validateTemplate — clean template", () => {
         name: "Good",
         description: "d",
         icon: "x",
-        color: "#000000",
+        color: "violet",
       },
       workspace: { name: "Good", description: "d" },
       profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
@@ -88,7 +88,7 @@ describe("validateTemplate — system Knowledge contract", () => {
         name: "Knowledge consumer",
         description: "d",
         icon: "brain",
-        color: "#000000",
+        color: "violet",
       },
       workspace: { name: "Knowledge consumer", description: "d" },
       profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
@@ -178,7 +178,7 @@ describe("validateTemplate — automation flow node contract", () => {
         name: "Flowy",
         description: "d",
         icon: "x",
-        color: "#000000",
+        color: "violet",
       },
       workspace: { name: "Flowy", description: "d" },
       profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
@@ -286,3 +286,70 @@ describe("validateTemplate — automation flow node contract", () => {
     });
   });
 });
+
+describe("validateTemplate — a pack needs no profile shell (D8)", () => {
+  const pack = (tags: string[], deps: unknown[]) =>
+    ({
+      meta: {
+        slug: "acme-suite",
+        name: "Acme",
+        description: "d",
+        icon: "x",
+        color: "violet",
+        tags,
+      },
+      workspace: { name: "Acme", description: "d" },
+      profiles: [],
+      dependencies: deps,
+    }) as unknown as WorkspaceYaml;
+  const profileErrors = (t: WorkspaceYaml) =>
+    validateTemplate(t, {}).errors.filter((e) => e.rule === "profiles-required");
+
+  it("a suite that requires a workspace is valid without profiles", () => {
+    expect(
+      profileErrors(pack(["suite"], [{ slug: "crm", kind: "workspace", relation: "require" }]))
+    ).toEqual([]);
+  });
+
+  it("a suite requiring NO workspace still needs a profile", () => {
+    expect(profileErrors(pack(["suite"], []))).toHaveLength(1);
+  });
+
+  it("a non-suite template without profiles is still refused", () => {
+    expect(
+      profileErrors(pack([], [{ slug: "crm", kind: "workspace", relation: "require" }]))
+    ).toHaveLength(1);
+  });
+});
+
+describe("validateTemplate — entityLinks[].required", () => {
+  const withLinks = (entityLinks: unknown[]) =>
+    ({
+      meta: { slug: "links", name: "Links", description: "d", icon: "x", color: "violet" },
+      workspace: { name: "Links", description: "d" },
+      profiles: [
+        { slug: "gadget", displayName: "Gadget", properties: [] },
+        { slug: "widget", displayName: "Widget", properties: [] },
+      ],
+      entityLinks,
+    }) as unknown as WorkspaceYaml;
+  const link = { sourceProfileSlug: "gadget", targetProfileSlug: "widget", type: "relates_to" };
+  const requiredErrors = (t: WorkspaceYaml) =>
+    validateTemplate(t, {}).errors.filter((e) => e.rule === "entitylink-required-not-boolean");
+
+  it("accepts required: true, required: false and no required", () => {
+    const result = validateTemplate(
+      withLinks([{ ...link, required: true }, { ...link, type: "part_of", required: false }, { ...link, type: "mentions" }]),
+      {}
+    );
+    expect(result, JSON.stringify(result.errors)).toEqual({ ok: true, errors: [] });
+  });
+
+  it("refuses a required that is not a boolean, naming the link", () => {
+    for (const bad of ["yes", 1, "true", null]) {
+      const errors = requiredErrors(withLinks([{ ...link, required: bad }]));
+      expect(errors, String(bad)).toHaveLength(1);
+      expect(errors[0]!.message).toContain("gadget→widget (relates_to)");
+    }
+  });
+});