@synap-core/workspace-templates 0.6.3 → 0.7.0

package/src/catalog.test.ts

@@ -7,7 +7,7 @@
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mergeCatalog, type RemoteEntry } from "./catalog.js";
+import { mergeCatalog, computeTemplateUpdates, type RemoteEntry } from "./catalog.js";
 import type { WorkspaceYaml } from "./types.js";
 
 const BUNDLE_VERSION = "0.6.0";
@@ -154,3 +154,101 @@ test("maps a bundled template's meta fields onto the entry", () => {
   assert.equal(e.category, "workspace");
   assert.equal(e.isPrivate, true, "isPublic:false ⇒ isPrivate");
 });
+
+// ── computeTemplateUpdates ───────────────────────────────────────────────────
+
+test("computeTemplateUpdates: no update when installed equals catalog latest (semver)", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("crm", { version: "0.7.0" })],
+    bundleVersion: BUNDLE_VERSION, // remote strictly newer → remote wins, carries "0.7.0"
+  });
+  const [check] = computeTemplateUpdates([{ slug: "crm", version: "0.7.0" }], entries);
+  assert.equal(check.latestVersion, "0.7.0");
+  assert.equal(check.updateAvailable, false);
+});
+
+test("computeTemplateUpdates: update available when installed is older (semver)", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("crm", { version: "0.7.0" })],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const [check] = computeTemplateUpdates([{ slug: "crm", version: "0.5.0" }], entries);
+  assert.equal(check.latestVersion, "0.7.0");
+  assert.equal(check.updateAvailable, true);
+});
+
+// NOTE: uses a non-colliding slug so the remote row is kept as a DISTINCT entry
+// regardless of version — a hash string never parses as semver, so on a slug
+// COLLISION `remoteIsStrictlyNewer` would (correctly, per mergeCatalog's existing
+// squatting-defense semantics) keep the bundle winning and never surface the hash.
+test("computeTemplateUpdates: hash-vs-semver — any mismatch with a hash version signals an update", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("hash-template", { version: "h-abc123" })],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const [staleSemver] = computeTemplateUpdates(
+    [{ slug: "hash-template", version: "0.5.0" }],
+    entries,
+  );
+  assert.equal(staleSemver.latestVersion, "h-abc123");
+  assert.equal(staleSemver.updateAvailable, true, "semver installed vs hash latest ⇒ differ ⇒ update");
+
+  const [sameHash] = computeTemplateUpdates(
+    [{ slug: "hash-template", version: "h-abc123" }],
+    entries,
+  );
+  assert.equal(sameHash.updateAvailable, false, "identical hash ⇒ no update");
+
+  const [differentHash] = computeTemplateUpdates(
+    [{ slug: "hash-template", version: "h-old999" }],
+    entries,
+  );
+  assert.equal(differentHash.updateAvailable, true, "different hash ⇒ update");
+});
+
+test("computeTemplateUpdates: slug missing from catalog ⇒ no update, latestVersion undefined", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const [check] = computeTemplateUpdates([{ slug: "ghost-template", version: "1.0.0" }], entries);
+  assert.equal(check.latestVersion, undefined);
+  assert.equal(check.updateAvailable, false);
+});
+
+test("computeTemplateUpdates: bundled winner compares against bundleVersion when passed", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const stale = computeTemplateUpdates(
+    [{ slug: "crm", version: "0.1.0" }],
+    entries,
+    BUNDLE_VERSION,
+  );
+  assert.equal(stale[0].latestVersion, BUNDLE_VERSION);
+  assert.equal(stale[0].updateAvailable, true);
+
+  const noBundleVersion = computeTemplateUpdates([{ slug: "crm", version: "0.1.0" }], entries);
+  assert.equal(noBundleVersion[0].latestVersion, undefined, "no bundleVersion ⇒ nothing to compare");
+  assert.equal(noBundleVersion[0].updateAvailable, false);
+});
+
+test("computeTemplateUpdates: passes isPrivate through from the winning entry", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("private-pack", { isPrivate: true, version: "1.0.0" })],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const [check] = computeTemplateUpdates(
+    [{ slug: "private-pack", version: "0.9.0" }],
+    entries,
+  );
+  assert.equal(check.isPrivate, true);
+  assert.equal(check.updateAvailable, true);
+});

package/src/catalog.ts

@@ -371,3 +371,96 @@ export function assembleCatalog(input: AssembleCatalogInput): MergeCatalogResult
     remoteStatus: input.remoteStatus,
   });
 }
+
+// ============================================================================
+// Installed-vs-catalog update check
+// ============================================================================
+
+/** A template a pod has installed — the door reads `settings.packageVersion` off the workspace row. */
+export interface InstalledTemplate {
+  slug: string;
+  version: string;
+}
+
+/** Per-slug verdict: is a newer catalog version available than what's installed? */
+export interface TemplateUpdateCheck {
+  slug: string;
+  installedVersion: string;
+  /** `undefined` when the slug has no matching catalog entry, or a bundled winner and no `bundleVersion` was passed. */
+  latestVersion: string | undefined;
+  updateAvailable: boolean;
+  /** Passed through from the winning catalog entry, so callers can route private updates through the authed path. */
+  isPrivate?: boolean;
+}
+
+/**
+ * `true` when `version` is a CP content-hash stamp (`"h-<hash>"`) rather than semver.
+ * Content-hash versions are NOT semver-comparable — see `computeTemplateUpdates`.
+ */
+export function isHashVersion(version: string | undefined): boolean {
+  return typeof version === "string" && version.startsWith("h-");
+}
+
+/**
+ * Compare an installed version against a catalog's latest — reusing
+ * `remoteIsStrictlyNewer` for the semver path. Either side being a content-hash
+ * (`"h-..."`) makes the pair NOT semver-comparable, so an update is signalled
+ * whenever the two raw strings simply differ (equal ⇒ no update, by construction
+ * the CP only reissues a new hash when the template content actually changed).
+ */
+function isNewerVersion(installedVersion: string, latestVersion: string | undefined): boolean {
+  if (latestVersion === undefined) return false;
+  if (isHashVersion(installedVersion) || isHashVersion(latestVersion)) {
+    return installedVersion !== latestVersion;
+  }
+  return remoteIsStrictlyNewer(latestVersion, installedVersion);
+}
+
+/**
+ * Compute, per installed template, whether the CATALOG (bundled + remote,
+ * already merged by `mergeCatalog`/`assembleCatalog`) carries a newer version
+ * than what the pod installed — the shared "update available" check all three
+ * doors (browser, synap-app, CLI) reuse instead of re-deriving it.
+ *
+ * `installed` and `catalog` are BOTH already-fetched/computed by the caller —
+ * this stays PURE, same as the rest of this module (no fetch, no auth).
+ *
+ * The catalog's winning entry carries the latest version signal two ways:
+ *   • `source: "remote"` → `remote.definition?.sourcePackage?.version` (semver
+ *     OR, going forward, a CP content-hash `"h-<hash>"` stamp).
+ *   • `source: "bundled"` → bundled entries carry no version field at all
+ *     (`TemplateMeta` has none); pass `bundleVersion` (this client's compiled
+ *     package version, the same value fed to `mergeCatalog`) to compare against
+ *     it. Omit `bundleVersion` and bundled-backed slugs report `latestVersion:
+ *     undefined, updateAvailable: false` (nothing comparable).
+ *
+ * A slug with no matching catalog entry ⇒ `updateAvailable: false`,
+ * `latestVersion: undefined` — there is nothing to update TO.
+ */
+export function computeTemplateUpdates(
+  installed: InstalledTemplate[],
+  catalog: CatalogEntry[],
+  bundleVersion?: string,
+): TemplateUpdateCheck[] {
+  const bySlug = new Map(catalog.map((entry) => [entry.slug, entry]));
+
+  return installed.map(({ slug, version: installedVersion }) => {
+    const entry = bySlug.get(slug);
+    if (!entry) {
+      return { slug, installedVersion, latestVersion: undefined, updateAvailable: false };
+    }
+
+    const latestVersion =
+      entry.source === "remote"
+        ? entry.remote.definition?.sourcePackage?.version
+        : bundleVersion;
+
+    return {
+      slug,
+      installedVersion,
+      latestVersion,
+      updateAvailable: isNewerVersion(installedVersion, latestVersion),
+      isPrivate: entry.isPrivate,
+    };
+  });
+}

package/src/crm.yaml

@@ -1,8 +1,8 @@
 # CRM workspace template
 # The CRM owns pre-sale work only. A won deal is handed to the operating
 # workspace; this template deliberately does not provision client delivery,
-# campaigns, tasks, documents, or automations. It DOES seed funnel playbooks
-# (the action layer) so the pipeline is operable via sessions — see `playbooks:`.
+# campaigns, tasks, documents, automations, or sales-specific playbooks. A
+# use-case overlay (for example `business-developer`) may add those workflows.
 
 meta:
   slug: crm
@@ -17,6 +17,20 @@ meta:
     - contacts
   isPublic: true
 
+# SSOT ordering guarantee — this template REFERENCES foundation's pod-wide
+# shared `client`/`partner`/`lead`/`churned` roles below. The apply engine seeds
+# a shared profile's pod-wide BASE property body from whichever template
+# creates it FIRST, and adds a REUSING template's extra props as workspace
+# OVERLAYS. Requiring foundation makes the resolver install it first
+# (deps-first), so the base is always foundation's SSOT body and never this
+# template's. `require`, not `compose`: foundation is a real workspace, not an
+# overlay.
+dependencies:
+  - slug: foundation
+    kind: workspace
+    relation: require
+    reason: "Provides the pod-wide client/partner/lead/churned role vocabulary this workspace reuses."
+
 workspace:
   name: CRM
   description: A focused pre-sale workspace for contacts, companies, and deals.
@@ -407,67 +421,33 @@ entityLinks:
     targetProfileSlug: deal
     type: linked_to_deal
 
-# Playbooks — session templates seeded with the workspace. The CRM's action layer.
-# `subjectProfile` binds each playbook to a funnel subject so the Capture → Session
-# matcher (`playbooks.matchForEntity`, filtering `subject_profile->>'profileSlug'`)
-# can offer it when that subject is captured — a captured lead surfaces "Enrich this
-# lead" / "Qualify this lead"; a deal surfaces "Work this deal". The subject entity
-# is passed as the matching entity param and substituted into the goalTemplate.
-#
-# Two subjects are used: `lead` (a shared ROLE facet on a person/company — the same
-# facet-role subject pattern ecosystem.yaml uses for `competitor`) and `deal` (a
-# primary CRM kind). The matcher keys purely on the profileSlug string, so a role
-# facet and a kind are matched identically.
-#
-# No `grants:` on "Enrich this lead": enrichment tools (Apify/Unipile-LinkedIn) are
-# workspace-conditional and may not be granted, so the goalTemplate context-injects
-# the intent and the session agent uses whatever enrichment capability the workspace
-# actually has — mirroring how "Produce Content" (content-os) grants nothing and
-# leans on the workspace's tools, rather than hardcoding a tool that might be absent.
+# Playbook — enriches a lead/prospect from public sources (company site,
+# LinkedIn, firmographic signal) so ICP scoring and qualification start from
+# real data instead of a blank record. Bound to `lead` so a newly captured
+# lead can offer this as a session.
 playbooks:
-  - name: Enrich this lead
-    description: Take a thin, freshly-captured lead and fill it out — company, title, LinkedIn, and the relationships around it.
+  - name: Enrich Lead/Company
+    description: Enrich a lead or company from public sources — firmographics, company size, and recent signal — to sharpen ICP scoring and qualification.
     goalTemplate: >-
-      Enrich this lead ({lead}). Starting from whatever is known, fill out the
-      missing detail — company, job title, LinkedIn URL, location, and the people
-      and companies around them — and record it on the lead. Draw on whatever
-      enrichment capability this workspace has connected (e.g. an Apify or
-      Unipile/LinkedIn tool); if none is available, enrich from the public web and
-      what is already in the pod. Link the lead to its company and any related
-      contacts, and note where information is still missing.
+      Enrich {target} using public sources. Scrape their website and LinkedIn
+      presence (via Apify) for firmographics: company size, industry, location,
+      and any recent signal (funding, hiring, product launches). Fill in the
+      missing profile fields (industry, companySize, location, icpScore) with
+      what you find, and note anything that changes qualification. Do not
+      fabricate — leave a field blank rather than guess.
     subjectProfile:
       profileSlug: lead
     params:
-      - { name: lead, type: entity, label: Lead, required: true }
+      - { name: target, type: entity, label: Lead or company, required: true }
     executor: is-agent
+    grants:
+      - apify_run_actor
+      - entity.create
     status: active
 
-  - name: Qualify this lead
-    description: Assess a lead against the ICP, score the fit, and decide the next step — advance, nurture, or disqualify.
-    goalTemplate: >-
-      Qualify this lead ({lead}). Assess how well they fit our ideal customer
-      profile — company, role, industry, size, and the signals of intent or need —
-      and set an ICP score. Decide the next step: advance them toward a deal,
-      keep nurturing, or disqualify. Write the reasoning and the decision back onto
-      the lead (its stage, score, and next step) so the call is auditable.
-    subjectProfile:
-      profileSlug: lead
-    params:
-      - { name: lead, type: entity, label: Lead, required: true }
-    executor: is-agent
-    status: active
-
-  - name: Work this deal
-    description: Move a deal toward Won — read the current stage, find the blocker, and propose the next step and owner.
-    goalTemplate: >-
-      Work this deal ({deal}) toward Won. Assess where it stands — its current
-      stage, value, and close date — and identify the single thing blocking it from
-      advancing. Propose the concrete next step, who owns it, and by when, and
-      update the deal's next step accordingly. If the stage should change, say so
-      and why.
-    subjectProfile:
-      profileSlug: deal
-    params:
-      - { name: deal, type: entity, label: Deal, required: true }
-    executor: is-agent
-    status: active
+# Apify powers the enrichment playbook (scrape public sources for a lead's
+# firmographics). Composed pod-wide at provisioning via the existing
+# integrations door; the user supplies the Apify API key once on install — a
+# missing key fails gracefully per-skill, not the whole workspace.
+integrations:
+  - templateKey: apify

package/src/define.flow-automations.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { toWorkspaceDefinition } from "./define.js";
+import type { WorkspaceYaml } from "./types.js";
+
+const workflowTemplate: WorkspaceYaml = {
+  meta: {
+    slug: "workflow-contract-test",
+    name: "Workflow contract test",
+    description: "Test template",
+    icon: "workflow",
+    color: "blue",
+  },
+  workspace: { name: "Workflow contract test", description: "Test" },
+  profiles: [],
+  automations: [
+    {
+      name: "A manual workflow",
+      triggerType: "manual",
+      flow: {
+        nodes: [{ id: "trigger", type: "trigger" }],
+        edges: [],
+        precondition: "trigger.payload.ready === true",
+      },
+    },
+  ],
+  actionPlacements: [
+    {
+      profileSlug: "person",
+      surface: "entity-detail",
+      kind: "automation",
+      ref: "A manual workflow",
+      label: "Run workflow",
+      when: {
+        requiredFacetSlugs: ["lead"],
+        propertyEquals: { stage: "ready" },
+      },
+      confirmation: { title: "Continue?", confirmLabel: "Run" },
+    },
+  ],
+};
+
+describe("toWorkspaceDefinition flow automations", () => {
+  it("keeps graph workflows distinct from legacy loop automations", () => {
+    const { definition } = toWorkspaceDefinition(workflowTemplate);
+
+    expect(definition.flowAutomations).toEqual([
+      expect.objectContaining({
+        name: "A manual workflow",
+        triggerType: "manual",
+        flowDefinition: expect.objectContaining({
+          precondition: "trigger.payload.ready === true",
+        }),
+      }),
+    ]);
+    expect("automations" in definition).toBe(false);
+  });
+
+  it("preserves action applicability and confirmation policy", () => {
+    const { definition } = toWorkspaceDefinition(workflowTemplate);
+    expect(definition.actionPlacements?.[0]).toMatchObject({
+      when: { requiredFacetSlugs: ["lead"], propertyEquals: { stage: "ready" } },
+      confirmation: { title: "Continue?", confirmLabel: "Run" },
+    });
+  });
+});

package/src/define.ts

@@ -10,9 +10,39 @@
  * shape never drifts per call-site.
  */
 
-import type { TemplateBentoBlock, WorkspaceYaml } from "./types.js";
+import type { TemplateAutomation, TemplateBentoBlock, WorkspaceYaml } from "./types.js";
 import { getWorkspaceTemplate } from "./templates.js";
 
+/**
+ * A `TemplateAutomation` as the apply door expects it: `flowDefinition`, not
+ * the authored `flow` (mirrors `PackagePostWorkspaceBody['automations'][number]`
+ * / the Hub `POST /packages/apply` `AutomationSchema`).
+ */
+export interface PackageAutomationWire {
+  /** Stable template identity; names may be edited without orphaning the flow. */
+  key?: string;
+  name: string;
+  description?: string;
+  triggerType: TemplateAutomation['triggerType'];
+  triggerConfig?: Record<string, unknown>;
+  flowDefinition?: { nodes: unknown[]; edges: unknown[]; precondition?: string };
+  status?: TemplateAutomation['status'];
+}
+
+function toAutomationWire(
+  automations: TemplateAutomation[] | undefined,
+): PackageAutomationWire[] | undefined {
+  return automations?.map((a) => ({
+    key: a.key,
+    name: a.name,
+    description: a.description,
+    triggerType: a.triggerType,
+    triggerConfig: a.triggerConfig,
+    flowDefinition: a.flow,
+    status: a.status,
+  }));
+}
+
 /** A widget block as the wire expects it: `bentoLayout[]`, keyed by `widgetType`. */
 export interface BentoWidgetBlockWire {
   widgetType: string;
@@ -147,6 +177,21 @@ export interface WorkspaceDefinitionInput {
    * tools/skills/automations silently dropped on that door.
    */
   capabilities?: WorkspaceYaml['integrations'];
+  /** Playbooks normalized to the workspace-create input contract. */
+  playbooks?: Array<Record<string, unknown>>;
+  /**
+   * Entity-detail action placements — forwarded verbatim to
+   * `applyPackagePostWorkspace`, which merges them into
+   * `settings.actionPlacements`. The tRPC door (`createFromDefinition`)
+   * declares `actionPlacements` in its zod input and carries them through the
+   * shared apply door. No shape transform: the authored form IS the wire form.
+   */
+  actionPlacements?: WorkspaceYaml['actionPlacements'];
+  /**
+   * Graph-based automations. Deliberately distinct from the legacy
+   * `automations` loop/playbook-trigger wire shape accepted by this door.
+   */
+  flowAutomations?: PackageAutomationWire[];
   // Workspace-level metadata (flattened from the `workspace` block)
   workspaceSubtype?: string;
   workspaceType?: NonNullable<WorkspaceYaml['workspace']>['workspaceType'];
@@ -177,6 +222,27 @@ export interface ToDefinitionResult {
   templateId: string;
 }
 
+/**
+ * The workspace-create door persists a compact primitive input contract. A
+ * template's entity/choice parameter is still represented precisely by its
+ * `subjectProfile` or runtime prompt, while the persisted input value is an ID
+ * or selected value string. Keep this conversion at the shared template seam
+ * so browser creation and package application cannot silently disagree.
+ */
+function toWorkspacePlaybooks(playbooks: WorkspaceYaml["playbooks"]): Array<Record<string, unknown>> | undefined {
+  return playbooks?.map((playbook) => ({
+    ...playbook,
+    params: playbook.params?.map((param) => ({
+      name: param.name,
+      type: param.type === "number" || param.type === "boolean" ? param.type : "string",
+      ...(param.defaultValue !== undefined ? { default: param.defaultValue } : {}),
+      ...(param.label
+        ? { description: param.label }
+        : {}),
+    })),
+  }));
+}
+
 /**
  * Resolve a template (by slug or YAML object) into the createFromDefinition
  * payload. Pass `nameOverride` to rename the workspace at creation time.
@@ -228,6 +294,13 @@ export function toWorkspaceDefinition(
     workspaceCapabilities: ws.capabilities,
     sourceRoles: ws.sourceRoles,
     defaultSources: ws.defaultSources,
+    // Workspace creation persists its own compact playbook parameter shape.
+    // Map authored entity/choice inputs here instead of dropping playbooks.
+    playbooks: toWorkspacePlaybooks(tpl.playbooks),
+    // Entity-detail action placements — forwarded verbatim; the apply door
+    // resolves playbook/automation refs and merges into settings.actionPlacements.
+    actionPlacements: tpl.actionPlacements,
+    flowAutomations: toAutomationWire(tpl.automations),
     onboarding: tpl.onboarding,
     // Template-composition dependencies — forwarded so the tRPC/UI door gets the
     // SAME deps-first ordering the CLI/Hub door gets via `toPackageDefinition`.
@@ -281,6 +354,9 @@ type WorkspaceDefinitionForwarded =
   | 'bento'         // → bentoViewName + bentoLayout (widgets) + bentoViewBlocks (views)
   | 'profileEntityBentoTemplates'
   | 'integrations'  // → capabilities (installed via shared applyPackagePostWorkspace door)
+  | 'playbooks'     // → normalized compact playbook contract
+  | 'actionPlacements' // → settings.actionPlacements via applyPackagePostWorkspace
+  | 'automations' // → flowAutomations → shared applyPackagePostWorkspace door
   | 'onboarding'
   | 'dependencies';
 
@@ -297,12 +373,7 @@ type WorkspaceDefinitionDropped =
   // The door DOES accept `extends`, but no template declares it today (0/21).
   // Forwarding is a no-op until one does — wire it then.
   | 'extends'
-  // REAL GAP (agent-fleet, project-management declare playbooks). The door
-  // accepts `playbooks`, but the shapes disagree: template param `type` allows
-  // 'text'|'entity'|'choice', the tRPC enum accepts only string|number|boolean
-  // (and defaultValue↔default, grants: string[]↔{kind,ref}[]). Raw forwarding =
-  // zod BAD_REQUEST. Needs a param mapper — separate wave, not a silent drop.
-  | 'playbooks';
+  ;
 
 type UnclassifiedWorkspaceDefinitionKey = Exclude<
   keyof WorkspaceYaml,
@@ -367,6 +438,19 @@ export interface PackageDefinitionOutput {
   layoutConfig?: WorkspaceYaml['layout'];
   capabilities?: WorkspaceYaml['integrations'];
   playbooks?: WorkspaceYaml['playbooks'];
+  /** Flow-based automations — mapped to the apply door's `flowDefinition` field. */
+  automations?: PackageAutomationWire[];
+  /**
+   * Entity-detail action placements — carried verbatim (authored form IS the
+   * wire form). NOTE: the Hub `PackageApplySchema` (synap-backend
+   * `hub-protocol/rest/packages.ts`) is a plain `z.object` and does not yet
+   * declare `actionPlacements`, so on the CLI/Hub install path this field is
+   * STRIPPED before `applyPackagePostWorkspace` sees it. The tRPC
+   * `createFromDefinition` door DOES carry it. Named follow-up: add an
+   * `ActionPlacementSchema` field to `PackageApplySchema` to close the Hub half
+   * (out of the T2 fence — flagged in the handoff).
+   */
+  actionPlacements?: WorkspaceYaml['actionPlacements'];
   onboarding?: WorkspaceYaml['onboarding'];
   /** Template-composition dependencies — resolved by the apply endpoint. */
   dependencies?: WorkspaceYaml['dependencies'];
@@ -421,6 +505,8 @@ export function toPackageDefinition(
     layoutConfig: tpl.layout,
     capabilities: tpl.integrations,
     playbooks: tpl.playbooks,
+    automations: toAutomationWire(tpl.automations),
+    actionPlacements: tpl.actionPlacements,
     onboarding: tpl.onboarding,
     dependencies: tpl.dependencies,
   };
@@ -448,6 +534,8 @@ type PackageDefinitionForwarded =
   | 'layout'        // → layoutConfig
   | 'integrations'  // → capabilities
   | 'playbooks'
+  | 'automations'   // → mapped to the apply door's flowDefinition wire shape
+  | 'actionPlacements' // → carried verbatim (Hub inbound schema decl is a follow-up)
   | 'onboarding'
   | 'dependencies';
 

package/src/ecosystem.yaml

@@ -381,9 +381,11 @@ playbooks:
     goalTemplate: >-
       Research this competitor ({competitor}) and compare them to us. Investigate
       their {focus}: positioning, strengths, weaknesses, pricing, and recent
-      moves. Use the provided company context where relevant: {companyContext}.
-      Produce: {outputTypes}. Update the competitor entity with what you find and
-      make clear where we win and where we are exposed.
+      moves. Use web search for news and public signal, and use the Apify scraper
+      for a deep scan of their site (pricing page, changelog, careers page) when
+      a URL is known. Use the provided company context where relevant:
+      {companyContext}. Produce: {outputTypes}. Update the competitor entity with
+      what you find and make clear where we win and where we are exposed.
     subjectProfile:
       profileSlug: competitor
     params:
@@ -398,8 +400,9 @@ playbooks:
     # starts paid AI runs — the user turns it on when they want the watch.
     schedule: { cron: "0 9 * * 1", enabled: false }
     grants:
-      - Web Search
-      - Entity Creator
+      - exa_search
+      - apify_run_actor
+      - entity.create
     status: active
 
   # A radar DISCOVERY run: the self-generating half. No subjectProfile → a single
@@ -409,28 +412,32 @@ playbooks:
   - name: Discover Competitors
     description: Scan the market for competitors we don't track yet and add them to the ecosystem — the self-generating half of the radar.
     goalTemplate: >-
-      Find companies that compete with us in {ourSpace}. Use neural web search
-      (the exa_search skill with category "company") to surface real, named
-      companies — direct competitors, adjacent tools that solve the same job a
-      different way, and emerging players. For each genuinely NEW one (not already
-      a competitor in our ecosystem), propose it as a `competitor` entity and
-      ALWAYS include its `website` (its canonical URL) so it de-duplicates against
-      what we already track — never create a company that already exists. Skip
-      anything already known. Report what you added and why each one matters.
+      Find companies that compete with us in {ourSpace}. Fan out neural web
+      searches with the exa_search skill using category "company" — cover direct
+      competitors, adjacent tools that solve the same job a different way, and
+      emerging players, not just the obvious incumbents. For each genuinely NEW
+      one (not already a competitor in our ecosystem), propose it as a
+      `competitor` entity and ALWAYS include its `website` (its canonical URL) as
+      the dedup key — never create a company whose website already matches one we
+      track. Skip anything already known. Report what you added, the search
+      angles you covered, and why each new one matters.
     schedule: { cron: "0 9 * * 1", enabled: false }
     params:
       - { name: ourSpace, type: text, label: Our market / category, required: true }
     executor: is-agent
     grants:
       - exa_search
-      - Entity Creator
+      - entity.create
     status: active
 
-# The Exa search capability powers the discovery radar (find companies we don't
-# track yet). Composed pod-wide at provisioning via the existing integrations
-# door; the user supplies the Exa API key once on install.
+# Exa powers the discovery radar (find companies we don't track yet); Apify
+# powers the deep-scan half of Research Competitor (scrape a known competitor's
+# site for pricing/changelog/careers signal). Composed pod-wide at provisioning
+# via the existing integrations door; the user supplies each API key once on
+# install — a missing key fails gracefully per-skill, not the whole workspace.
 integrations:
   - templateKey: exa
+  - templateKey: apify
 
 onboarding:
   goal: >

package/src/index.ts

@@ -44,6 +44,8 @@ export type {
   TemplateOnboardingCollectTarget,
   TemplatePlaybook,
   TemplatePlaybookParam,
+  TemplateAutomation,
+  TemplateActionPlacement,
 } from "./types.js";
 
 // The dependency-kind vocabulary as a VALUE — so consumers (marketplace,
@@ -61,7 +63,13 @@ export {
 
 export type { WorkspaceTemplateSlug } from "./templates.js";
 
-export { mergeCatalog, rowToRemoteEntry, assembleCatalog } from "./catalog.js";
+export {
+  mergeCatalog,
+  rowToRemoteEntry,
+  assembleCatalog,
+  computeTemplateUpdates,
+  isHashVersion,
+} from "./catalog.js";
 export type {
   MergeCatalogInput,
   MergeCatalogResult,
@@ -73,6 +81,8 @@ export type {
   RemoteCatalogEntry,
   CpPackageRow,
   AssembleCatalogInput,
+  InstalledTemplate,
+  TemplateUpdateCheck,
 } from "./catalog.js";
 
 export {