fullstackgtm 0.37.0 → 0.38.0

package/dist/enrich.js

@@ -2,13 +2,14 @@ import { mkdirSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.js";
 import { HUBSPOT_DEFAULT_FIELD_MAPPINGS } from "./mappings.js";
+import { parseAssignmentPolicy, resolveAssignment } from "./assign.js";
 export const ENRICH_CONFIG_FILE_NAME = "enrich.config.json";
 export const DEFAULT_STALE_DAYS = 90;
 const OBJECT_TYPES = ["company", "contact"];
 /** Match keys the matcher knows how to read off canonical snapshot records. */
 const MATCH_KEYS = {
     company: ["domain", "name"],
-    contact: ["email", "name"],
+    contact: ["email", "name", "linkedin"],
 };
 /** API source ids the MVP can pull from. */
 export const SUPPORTED_API_SOURCES = ["apollo", "explorium", "pipe0"];
@@ -178,6 +179,16 @@ export function parseEnrichConfig(raw) {
     if (!anyField && !hasAcquireCreate) {
         fail('"fields" maps nothing — add at least one field entry (or an "acquire.create" mapping)');
     }
+    // Normalize + validate the assignment policy (fails loud on shape errors so a
+    // misconfigured rule never silently mis-routes a created lead).
+    if (config.acquire?.assign !== undefined) {
+        try {
+            config.acquire.assign = parseAssignmentPolicy(config.acquire.assign);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
     return config;
 }
 /**
@@ -212,6 +223,35 @@ export function builtinEnrichPreset(source) {
  */
 export function builtinAcquirePreset(source) {
     const provider = source ?? "pipe0";
+    if (provider === "linkedin" || provider === "heyreach") {
+        // LinkedIn discovery reads our OWN HeyReach lead list, so it costs $0/record
+        // (no spend budget) and keys on the LinkedIn URL — leads are sparse on email,
+        // so email-keying would drop most of them. listId is supplied via --list.
+        return {
+            sources: { linkedin: { kind: "api" } },
+            match: { contact: { keys: ["linkedin", "email"], onAmbiguous: "skip" } },
+            fields: {},
+            policy: { overwrite: "never" },
+            acquire: {
+                budget: { records: { perDay: 50, perMonth: 500 } },
+                costPerRecord: { linkedin: 0 },
+                discovery: { linkedin: { provider: "linkedin", size: 25 } },
+                create: {
+                    contact: {
+                        matchKey: "linkedin",
+                        properties: {
+                            hs_linkedin_url: "linkedin",
+                            firstname: "firstName",
+                            lastname: "lastName",
+                            jobtitle: "jobTitle",
+                            company: "companyName",
+                            email: "email",
+                        },
+                    },
+                },
+            },
+        };
+    }
     if (provider !== "pipe0" && provider !== "explorium")
         return undefined;
     return {
@@ -387,6 +427,10 @@ function normalizeKeyValue(key, value) {
             .replace(/^www\./, "")
             .replace(/\/.*$/, "");
     }
+    if (key === "linkedin") {
+        // Match crmContactKeys' `li:` normalization (lowercased, trailing slash stripped).
+        return text.trim().replace(/\/+$/, "");
+    }
     return text.replace(/\s+/g, " ");
 }
 function crmKeyValue(objectType, record, key) {
@@ -399,6 +443,8 @@ function crmKeyValue(objectType, record, key) {
     }
     if (key === "email")
         return normalizeKeyValue("email", record.email);
+    if (key === "linkedin")
+        return normalizeKeyValue("linkedin", record.linkedin);
     if (key === "name") {
         return normalizeKeyValue("name", `${record.firstName ?? ""} ${record.lastName ?? ""}`.trim());
     }
@@ -652,6 +698,45 @@ export function buildEnrichPlan(options) {
     };
     return { plan, counts, stamps, ambiguities, unmatchedSourceIds };
 }
+/** First non-empty value among several candidate paths in a source payload. */
+function firstSourceValue(payload, paths) {
+    for (const path of paths) {
+        const value = sourceValueAt(payload, path);
+        if (!isEmptyValue(value))
+            return String(value).trim();
+    }
+    return undefined;
+}
+/**
+ * Lift a prospect/source payload into the routing attributes a territory rule
+ * reads. Tolerant of provider spellings (explorium vs pipe0); absent attributes
+ * stay undefined, so a rule that routes on them simply won't match (falling to
+ * the policy fallback) instead of mis-routing.
+ */
+export function acquireAssignmentContext(payload, companyName, accountOwnerByName) {
+    const ctx = {};
+    const title = firstSourceValue(payload, ["jobTitle", "job_title", "title"]);
+    if (title)
+        ctx.title = title.toLowerCase();
+    const geo = firstSourceValue(payload, ["geo", "country", "company_country_code", "companyCountry"]);
+    if (geo)
+        ctx.geo = geo.toLowerCase();
+    const industry = firstSourceValue(payload, ["industry", "company_industry", "companyIndustry"]);
+    if (industry)
+        ctx.industry = industry.toLowerCase();
+    const employeeBand = firstSourceValue(payload, ["employeeBand", "company_size", "companySize"]);
+    if (employeeBand)
+        ctx.employeeBand = employeeBand;
+    const department = firstSourceValue(payload, ["department", "job_department", "jobDepartment"]);
+    if (department)
+        ctx.department = department.toLowerCase();
+    if (companyName) {
+        const owner = accountOwnerByName.get(companyName.trim().toLowerCase());
+        if (owner)
+            ctx.accountOwnerId = owner;
+    }
+    return ctx;
+}
 /**
  * Match each sourced record against the snapshot and route it: matched =
  * already in the CRM (skip), ambiguous = a possible duplicate exists (skip —
@@ -680,8 +765,31 @@ export function buildAcquirePlan(options) {
         unmatched: 0,
         created: 0,
         withheldByMeter: 0,
+        assigned: 0,
+        unassigned: 0,
     };
     let estCostUsd = 0;
+    // Assignment context (built once): the set of owner ids the CRM will accept
+    // (active users), and a company-name → account-owner lookup for the
+    // "account-owner" inherit strategy. Empty when no assign policy is set.
+    const assignPolicy = acquire.assign;
+    const knownOwnerIds = new Set();
+    const accountOwnerByName = new Map();
+    if (assignPolicy) {
+        for (const user of snapshot.users ?? []) {
+            if (user.active === false)
+                continue;
+            if (user.crmId)
+                knownOwnerIds.add(user.crmId);
+            if (user.id)
+                knownOwnerIds.add(user.id);
+        }
+        for (const account of snapshot.accounts ?? []) {
+            if (account.name && account.ownerId) {
+                accountOwnerByName.set(account.name.trim().toLowerCase(), account.ownerId);
+            }
+        }
+    }
     for (const record of records) {
         const createMap = acquire.create[record.objectType];
         const match = config.match[record.objectType];
@@ -725,6 +833,19 @@ export function buildAcquirePlan(options) {
         }
         const recordEvidence = evidenceFor(source, sourceConfig.kind, sourceConfig.format, record, undefined, nowIso);
         evidence.push(recordEvidence);
+        // Resolve ownership BEFORE the meter-charged create lands, so the lead is
+        // never born ownerless. `counts.created` is the within-run index, giving
+        // round-robin deterministic, even distribution with no persisted cursor.
+        let ownerId;
+        let assignedBy;
+        if (assignPolicy) {
+            const ctx = acquireAssignmentContext(record.payload, associateCompanyName, accountOwnerByName);
+            const resolved = resolveAssignment(assignPolicy, ctx, counts.created, knownOwnerIds);
+            if (resolved.ownerId) {
+                ownerId = resolved.ownerId;
+                assignedBy = resolved.rule;
+            }
+        }
         const payload = {
             properties,
             matchKey: createMap.matchKey,
@@ -732,6 +853,7 @@ export function buildAcquirePlan(options) {
             source,
             estCostUsd: costPerRecord,
             associateCompanyName,
+            ...(ownerId ? { ownerId, assignedBy } : {}),
         };
         operations.push({
             id: `op_acq_${fnv1a(`${source}:${record.objectType}:${matchValue}`)}`,
@@ -748,6 +870,10 @@ export function buildAcquirePlan(options) {
             rollback: "Archive the created record (it was net-new).",
             evidenceIds: [recordEvidence.id],
         });
+        if (ownerId)
+            counts.assigned += 1;
+        else
+            counts.unassigned += 1;
         counts.created += 1;
         estCostUsd += costPerRecord;
     }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { auditSnapshot, defaultPolicy } from "./audit.ts";
+export { matchesTerritory, parseAssignmentPolicy, resolveAssignment, type AssignmentContext, type AssignmentPolicy, type AssignmentResult, type AssignmentStrategy, type TerritoryRule, } from "./assign.ts";
 export { buildBulkUpdatePlan, isFilterableField, parseWhere, type BulkUpdateOptions } from "./bulkUpdate.ts";
 export { buildDedupePlan, dedupeKey, type DedupeOptions } from "./dedupe.ts";
 export { buildReassignPlans, type ReassignObjectType, type ReassignOptions } from "./reassign.ts";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { auditSnapshot, defaultPolicy } from "./audit.js";
+export { matchesTerritory, parseAssignmentPolicy, resolveAssignment, } from "./assign.js";
 export { buildBulkUpdatePlan, isFilterableField, parseWhere } from "./bulkUpdate.js";
 export { buildDedupePlan, dedupeKey } from "./dedupe.js";
 export { buildReassignPlans } from "./reassign.js";

package/dist/reassign.d.ts

@@ -1,10 +1,19 @@
 import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
 export type ReassignObjectType = "account" | "contact" | "deal";
 export type ReassignOptions = {
-    /** the owner whose records are being handed off */
-    fromOwnerId: string;
+    /**
+     * the owner whose records are being handed off. Ignored (and not required)
+     * when `assignUnowned` is set — that mode targets ownerless records instead.
+     */
+    fromOwnerId?: string;
     /** the receiving owner — must be a known user in the snapshot */
     toOwnerId: string;
+    /**
+     * Backfill mode: instead of moving records from one owner to another, claim
+     * every OWNERLESS record (ownerId:empty) for `toOwnerId`. Shares the create-
+     * time assignment intent with `enrich acquire`, applied to existing debt.
+     */
+    assignUnowned?: boolean;
     /** which object types to compile plans for (default all three) */
     objects?: ReassignObjectType[];
     /** extra --where scoping, AND-ed into every plan (account fields lifted) */

package/dist/reassign.js

@@ -40,11 +40,16 @@ function scopeWhere(objectType, raw) {
     return raw;
 }
 export function buildReassignPlans(snapshot, options) {
-    if (!options.fromOwnerId || !options.toOwnerId) {
-        throw new Error("reassign requires both --from <ownerId> and --to <ownerId>.");
+    if (!options.toOwnerId) {
+        throw new Error("reassign requires --to <ownerId>.");
     }
-    if (options.fromOwnerId === options.toOwnerId) {
-        throw new Error("reassign --from and --to are the same owner — nothing to hand off.");
+    if (!options.assignUnowned) {
+        if (!options.fromOwnerId) {
+            throw new Error("reassign requires --from <ownerId> (or --assign-unowned to claim ownerless records).");
+        }
+        if (options.fromOwnerId === options.toOwnerId) {
+            throw new Error("reassign --from and --to are the same owner — nothing to hand off.");
+        }
     }
     // The receiving owner must exist: a typo'd --to would otherwise write an
     // invalid owner onto every matched record.
@@ -60,7 +65,7 @@ export function buildReassignPlans(snapshot, options) {
         }
     }
     return objects.map((objectType) => {
-        const where = [`ownerId=${options.fromOwnerId}`];
+        const where = [options.assignUnowned ? "ownerId:empty" : `ownerId=${options.fromOwnerId}`];
         if (objectType === "deal" && !options.includeClosedDeals) {
             where.push("isClosed=false"); // closed deals keep their historical owner
         }
@@ -80,7 +85,9 @@ export function buildReassignPlans(snapshot, options) {
             where,
             set: { ownerId: options.toOwnerId },
             reason: options.reason ??
-                `reassign: hand off ${objectType}s from owner ${options.fromOwnerId} to ${options.toOwnerId}`,
+                (options.assignUnowned
+                    ? `reassign: claim ownerless ${objectType}s for owner ${options.toOwnerId}`
+                    : `reassign: hand off ${objectType}s from owner ${options.fromOwnerId} to ${options.toOwnerId}`),
             maxOperations: options.maxOperations,
         });
     });

package/dist/runReport.d.ts

@@ -0,0 +1,9 @@
+/** A command annotates its headline metrics (merged). */
+export declare function reportCounts(values: Record<string, unknown>): void;
+/** A command annotates a structured event (plan saved, meter charged, …). */
+export declare function reportEvent(type: string, detail?: string): void;
+/**
+ * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
+ * swallows every error. Call once per process from the entry point.
+ */
+export declare function flushRunReport(args: string[], status: "success" | "partial" | "error", startedAt: number, error?: string): Promise<void>;

package/dist/runReport.js

@@ -0,0 +1,66 @@
+/**
+ * Opt-in CLI → hosted-app observability. When the user has paired the CLI
+ * (`login --via <url>` → broker token), each command fire-and-forgets a run
+ * record to the hosted app's `/api/cli/run`, authenticated by the broker token.
+ *
+ * Invariants: the CLI never requires web login; this does nothing when unpaired;
+ * it never throws and never changes the CLI's exit code or output. Reporting is
+ * pure added value for users who granted it.
+ */
+import { getCredential } from "./credentials.js";
+let counts;
+const events = [];
+/** A command annotates its headline metrics (merged). */
+export function reportCounts(values) {
+    counts = { ...(counts ?? {}), ...values };
+}
+/** A command annotates a structured event (plan saved, meter charged, …). */
+export function reportEvent(type, detail) {
+    events.push({ ts: Date.now(), type, detail });
+}
+// Setup/inspection verbs aren't interesting as "runs" — skip the noise.
+const SKIP_COMMANDS = new Set([
+    "login",
+    "logout",
+    "doctor",
+    "help",
+    "profiles",
+    "--help",
+    "-h",
+    "--version",
+    "-v",
+]);
+/**
+ * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
+ * swallows every error. Call once per process from the entry point.
+ */
+export async function flushRunReport(args, status, startedAt, error) {
+    const command = args[0];
+    if (!command || SKIP_COMMANDS.has(command))
+        return;
+    const broker = getCredential("broker");
+    if (!broker?.baseUrl || !broker.accessToken)
+        return; // opt-in: only when paired
+    const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
+    const finishedAt = Date.now();
+    try {
+        await fetch(`${broker.baseUrl.replace(/\/+$/, "")}/api/cli/run`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
+            body: JSON.stringify({
+                command: `${command}${sub}`,
+                status,
+                startedAt,
+                finishedAt,
+                durationMs: finishedAt - startedAt,
+                counts,
+                events: events.length ? events : undefined,
+                error,
+            }),
+            signal: AbortSignal.timeout(4000),
+        });
+    }
+    catch {
+        // Observability is best-effort; never affect the CLI outcome.
+    }
+}

package/dist/types.d.ts

@@ -24,6 +24,14 @@ export type CreateRecordPayload = {
     source: string;
     estCostUsd?: number;
     associateCompanyName?: string;
+    /**
+     * Owner to stamp on the new record (canonical owner id). The connector maps
+     * it to the CRM's owner property (HubSpot `hubspot_owner_id`) at create time
+     * so a lead is never born ownerless. Absent = leave unassigned.
+     */
+    ownerId?: string;
+    /** Audit label for how the owner was chosen (e.g. "fixed", "territory:0"). */
+    assignedBy?: string;
 };
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 /**

package/docs/api.md

@@ -102,7 +102,10 @@ emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
   duplicate groups by normalized identity key, one `merge_records` per group,
   deterministic survivor selection (`richest` / `oldest`).
 - `buildReassignPlans(snapshot, options: ReassignOptions)` — one plan per
-  `ReassignObjectType`, account-lifted scoping, stage exclusions.
+  `ReassignObjectType`, account-lifted scoping, stage exclusions. With
+  `assignUnowned` (CLI `--assign-unowned`) it targets ownerless records
+  (`ownerId:empty`) and claims them for `--to` — the backfill twin of
+  `enrich acquire`'s create-time assignment, for clearing existing ownerless debt.
 
 `fix` is CLI-only composition of existing surfaces (audit → suggest →
 approve → apply for one rule).
@@ -138,11 +141,31 @@ zero-config `EnrichConfig.acquire` (budget, provider, create-mapping) so
   waterfall, chunked, surfaces upstream errors), `fetchPipe0CrustdataProspects`
   (people search). `prospectIdentityKeys` / `crmContactKeys` /
   `partitionFreshProspects` power the pre-email dedup.
+- **LinkedIn source** (`connectors/linkedin.ts`, `acquireLinkedIn.ts`): the
+  injectable `LinkedInProvider` interface with a default HeyReach adapter
+  (`createHeyReachProvider`, `HEYREACH_BASE`, `X-API-KEY`, `normalizeHeyReachLead`)
+  and `createFakeLinkedInProvider` for keyless/offline tests; `createLinkedInProvider`
+  selects the adapter (`heyreach` only; rejects unknown). `discoverLinkedInProspects`
+  pulls a HeyReach lead list and `linkedInProspectToProspect` maps each lead to the
+  canonical `Prospect` (match key = LinkedIn URL), so ICP scoring / dedup / meter /
+  apply are reused unchanged. Phase 1 is discovery-only — read-only, never sends.
 - **Meter** (`acquireMeter.ts`): `AcquireBudget`, `loadMeter` / `remaining` /
   `recordConsumption` — per-profile windowed record+spend budget, charged only
   for landed creates.
 - **Seen cache** (`acquireSeen.ts`): `loadSeen` / `recordSeen` — cross-run
   memory so a re-run never re-pays to enrich a known prospect.
+- **Assignment** (`assign.ts`): `AssignmentPolicy` (`fixed` / `round-robin` /
+  `territory` / `account-owner`), `parseAssignmentPolicy`, pure
+  `resolveAssignment(policy, ctx, index, knownOwnerIds)`. Set
+  `EnrichConfig.acquire.assign` and `buildAcquirePlan` stamps `ownerId` into each
+  `create_record` payload so a **lead is never born ownerless** — the connector
+  maps it to HubSpot `hubspot_owner_id` at create time. Round-robin distributes
+  by the within-run index (deterministic, no persisted cursor); every result is
+  gated by the snapshot's active owners (an unknown/inactive owner collapses to
+  unassigned, never a bad write). The CLI defaults to the portal's sole active
+  owner when no policy is set (or `--assign-owner <id>`); with multiple owners
+  and no policy it warns and leaves leads unassigned rather than guess. The same
+  policy backfills existing debt via `reassign --assign-unowned`.
 
 `CanonicalContact.linkedin` (mapped from HubSpot `hs_linkedin_url`) is the
 strong dedup key across all of the above.

package/docs/architecture.md

@@ -78,6 +78,9 @@ provider  ──fetchSnapshot()──►  CanonicalGtmSnapshot
   translation, prospect fit scoring, and the agent-driven interview spec.
 - `acquireMeter.ts` — per-profile windowed budget (records + spend) for acquire.
 - `acquireSeen.ts` — cross-run "seen" cache so re-runs don't re-pay for dupes.
+- `assign.ts` — `AssignmentPolicy` (fixed / round-robin / territory /
+  account-owner): the pure owner-routing rule `buildAcquirePlan` stamps onto new
+  leads (never born ownerless) and `reassign --assign-unowned` reuses to backfill.
 - `connectors/prospectSources.ts` — API prospect sources (Explorium discovery,
   pipe0 work-email waterfall, pipe0/Crustdata search) + the pre-email dedup keys.
 

package/docs/linkedin-connector-spec.md

@@ -0,0 +1,87 @@
+# `linkedin` connector — spec (Phase 1)
+
+Status: scoped 2026-06-20. Decisions locked: **first slice = Phase 1 discovery,
+dry-run; default provider = HeyReach.** Rationale + the full white-label
+investigation that motivated owning this: see the LinkedIn connector research.
+
+## Why this shape
+
+The research verdict (≈85%): Gojiberry runs its **own** LinkedIn session-automation
+stack — it is **not** white-labeling HeyReach/Unipile, so there is no upstream to
+go "direct" to. But Gojiberry proves a small team can build the architecture, and
+the *execution* layer is rentable. So FSGTM's play is: **rent execution
+(HeyReach), own the targeting + scoring + plan/apply governance** — "governed
+LinkedIn outbound," which nobody else has.
+
+This does **not** rebuild anything. The in-flight `enrich acquire` pipeline
+already is the spine:
+
+```
+Icp → discovery source (Explorium/pipe0/Clay) → scoreProspectAgainstIcp
+   → partitionFreshProspects (dedup vs CRM + acquireSeen) → create_record op
+   → acquireMeter budget cap → approve → apply
+```
+
+LinkedIn is just a **new discovery source** on that spine.
+
+## Phase 1 deliverable: `enrich acquire --source linkedin` (dry-run)
+
+ICP → LinkedIn people-search via HeyReach → `Prospect[]` → ICP-scored → deduped →
+**dry-run `create_record` plan** (no `--save` ⇒ nothing written, zero send/ToS
+exposure). Net-new code is small; scoring/dedup/metering/apply are reused.
+
+### Components
+- **`src/connectors/linkedin.ts`** (mirrors `prospectSources.ts`):
+  - `icpToLinkedInFilters(icp)` — `Icp` → LinkedIn/Sales-Nav search params (mirror
+    of `icpToExploriumFilters` / `icpToCrustdataFilters` in `icp.ts`).
+  - `discoverProspects(provider, filters, max)` — search mode for Phase 1; returns
+    the existing `Prospect` type so everything downstream is free.
+- **`LinkedInProvider` interface** (injectable, like `CrontabIo`): default
+  **HeyReach** adapter (`searchLeads` / lead-list pull), plus a **`FakeLinkedInProvider`**
+  for tests so the whole pipeline runs with no key and no network.
+- **`builtinAcquirePreset('linkedin')`** — zero-config source preset (match-key
+  email/linkedinUrl; cost-per-record for the meter).
+- **Wiring**: register `linkedin` in the `enrich acquire` source switch; add to
+  the source allowlist + help; `login heyreach` (or `HEYREACH_API_KEY`) for the key.
+
+### Reused as-is (no change)
+`scoreProspectAgainstIcp`, `partitionFreshProspects`, `acquireSeen`,
+`acquireMeter` (records/day+month, cost/record), the `create_record` op + apply
+path, the dry-run→approve→apply gate.
+
+## Out of scope for Phase 1 (explicit)
+- **No sending.** `linkedin_connect` / `linkedin_message` operations, the
+  per-sender safety meter, and HeyReach webhook ingestion are **Phase 2**.
+- Engagement-signal capture (Gojiberry-style intent from who-engaged-our-posts)
+  is a Phase 1.5 add to `discoverProspects` once search mode is trusted.
+- Not our own automation engine; not the official LinkedIn API; not multi-channel.
+
+## Provider: HeyReach
+Behind `LinkedInProvider` so we are not locked in (Unipile = documented
+alternative: cheaper raw search/profile, multi-channel). HeyReach chosen for the
+full Campaign API + webhooks + sender rotation + built-in per-account caps (the
+Phase 2 ban-safety primitives we will want). ToS/ban risk sits on the connected
+LinkedIn account — same posture as Gojiberry today.
+
+## Build sequencing (IMPORTANT)
+The acquire spine (`icp.ts`, `prospectSources.ts`, `acquireMeter.ts`,
+`acquireSeen.ts`) is **uncommitted, actively-edited working-tree code** (not on
+main). Building the acquire-source wiring on top of it is expansion on an
+unstable base. Therefore:
+
+1. **Buildable now (self-contained, no dep on the uncommitted acquire internals):**
+   `LinkedInProvider` interface + HeyReach adapter (coded to HeyReach's documented
+   API) + `FakeLinkedInProvider` + `icpToLinkedInFilters` + unit tests against the
+   fake.
+2. **After the acquire workstream commits/lands:** wire `enrich acquire --source
+   linkedin` end-to-end and add the dry-run integration test.
+3. **Live validation** needs a HeyReach trial API key (Ryan provides) — the fake
+   covers everything up to the real network call.
+
+## Phase 2 (future, recorded for continuity)
+Governed outbound: `linkedin_connect`/`linkedin_message` as `PatchOperation`s
+(objectId = contact, afterValue = body, approvalRequired, `groupId` = sequence
+all-or-nothing, `preconditions` = not-already-connected); `applyOperation`
+dispatches `linkedin_*` to the provider; per-sender-account daily caps via the
+`acquireMeter` pattern (ban-safety encoded as governance); HeyReach webhooks →
+CRM activity + intent signal. This is the differentiated surface.

package/llms.txt

@@ -76,7 +76,10 @@ identity key — merge with `dedupe` instead. `dedupe <object> --key
 deterministic survivor (`--keep richest|oldest`); merges are irreversible and
 stay low-confidence-capped at approval. `reassign --from <owner> --to
 <owner>` = ownership handoff plans per object type; `--except-deal-stage`
-also excludes records whose account has an open deal in that stage. `fix
+also excludes records whose account has an open deal in that stage;
+`reassign --assign-unowned --to <id>` instead claims every ownerless record
+(`ownerId:empty`) for an owner — the backfill twin of acquire's create-time
+assignment. `fix
 --rule <id>` = audit one rule → suggest → approve at the confidence bar →
 apply only with `--yes`. All four produce plans; none writes outside
 approve → apply.
@@ -95,6 +98,24 @@ where the source value changed (beforeValue = current CRM value → apply-time
 CAS). Conflict policy MVP is `never`; `system-only`/`always` are phase 2 and
 refused explicitly. Run store (checkpoint + staleness ledger + `status`) is
 profile-scoped under `<home>/enrich/runs`. No cron — scheduling is horizontal.
+`acquire` is the one enrich verb that creates net-new records instead of
+filling blanks: it discovers ICP-targeted people, resolves work email, and
+proposes governed `create_record` ops through the same dry-run → approve →
+apply gate — resolve-first dedupe re-checks the key at apply time so it never
+double-creates. A per-profile windowed meter (`acquireMeter.ts`) caps both
+record count and provider spend (per-day + per-month, whichever binds first);
+sources come from staged ingest lists. Acquired leads are never born ownerless:
+an `acquire.assign` policy (`fixed`/`round-robin`/`territory`/`account-owner`,
+or `--assign-owner <id>`) stamps an owner into every `create_record`, gated by
+the snapshot's active owners (unknown/inactive owner → unassigned, never a bad
+owner); with multiple owners and no policy it warns and leaves leads unassigned.
+Discovery sources are presets behind `--source`: `explorium`/`pipe0` (ICP-driven
+people search) and `linkedin` (Phase 1, discovery + dry-run) which reads a
+pre-built HeyReach lead list (`--list <id>` or `acquire.discovery.linkedin.listId`,
+match key = LinkedIn URL, $0/record, `login heyreach`/`HEYREACH_API_KEY`) via the
+injectable `LinkedInProvider` (default HeyReach; `FakeLinkedInProvider` for tests).
+LinkedIn is read-only — Phase 1 has no `linkedin_connect`/`linkedin_message` ops
+and no webhook ingestion (Phase 2). Never auto-writes.
 
 ## Key invariants (schedule)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",

package/skills/fullstackgtm/SKILL.md

@@ -58,10 +58,11 @@ credentials AND stored plans per client org.
 | `resolve <contact\|account\|deal>` | Create gate: exit 0 = safe to create, 2 = exists/ambiguous — never blind-create |
 | `dedupe <object> --key <domain\|email\|name>` | One merge op per duplicate group, deterministic survivor; merges are irreversible |
 | `bulk-update <object> --where … --set\|--archive\|--create-task` | Filtered dry-run plan; filter re-verified per record at apply time |
-| `reassign --from <owner> --to <owner>` | Ownership handoff plans per object type |
+| `reassign --from <owner> --to <owner>` | Ownership handoff plans per object type; `--assign-unowned --to <id>` backfills every ownerless record |
 | `fix --rule <id>` | audit one rule → suggest → approve at the confidence bar → apply only with `--yes` |
 | `call parse\|score\|link\|plan` | Transcripts → evidence-quoted insights, rubric scorecards, deal linking, governed next-step writes |
 | `enrich append\|refresh\|ingest\|status` | Governed enrichment (Apollo pull / Clay ingest), fill-blanks-only plans |
+| `enrich acquire [--source explorium\|pipe0\|linkedin]` | Net-new ICP-targeted lead gen: resolve-first deduped `create_record` plans, capped by a per-profile windowed meter (records + spend); owner-stamped via `acquire.assign`/`--assign-owner` (never born ownerless); `--source linkedin --list <id>` reads a HeyReach lead list (Phase 1 discovery, read-only — never sends); never auto-writes |
 | `market init\|capture\|classify\|worksheet\|observe\|fronts\|axes\|overlay\|scale\|report\|refresh` | Competitive category map; evidence quotes verified verbatim against stored captures |
 | `schedule add\|list\|remove\|enable\|disable\|run\|install\|uninstall\|status` | Horizontal cron; read/plan-side allowlist only — scheduling NEVER auto-approves |
 | `report` | Client-ready audit deliverable (markdown or self-contained HTML) |
@@ -85,6 +86,6 @@ Tools over stdio: `fullstackgtm_audit` (read-only), `fullstackgtm_rules`,
 
 ## Going deeper
 
-- [llms.txt](https://github.com/fullstackgtm/core/blob/main/llms.txt) — the full invariant map per layer (calls, market, write verbs, enrich, schedule)
+- [llms.txt](https://github.com/fullstackgtm/core/blob/main/llms.txt) — the full invariant map per layer (calls, market, write verbs, enrich, schedule, engagement/health)
 - [INSTALL_FOR_AGENTS.md](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md) — deterministic install-and-verify with expected outputs
 - [docs/api.md](https://github.com/fullstackgtm/core/blob/main/docs/api.md) — semver-covered surfaces: canonical model, rule interface, plan/apply contract, connectors, config, CLI, MCP