feat(crm-starter-export): Phase 1-2 export scripts land — orgs.csv + people.csv from the canonical layer

Executes the plan's export half: one row per org (identity, flattened
links by kind, streams as long-text, tags/bucket/relations, the Master
Pipeline Tracker's human columns joined exact-first via
corpus_funder_slug then name/alias fuzzy — flagged, never trusted), and
one row per PERSON (relevance-ranked primary org attach, extras in
additional_orgs, orphans kept with blank org). External ids (slug /
person_uuid) on every row. No corpora, per the plan invariant.

First run (reach-edu): 364 orgs (64 pipeline-matched: 28 exact, 36
fuzzy; 32 unmatched pipeline rows to the sidecar), 417 people (354
attached, 63 orphans, 18 multi-affiliation). The sidecar's three
"second row also matches" warnings are the same org with multiple
pipeline deals — evidence for the opportunities-not-company-fields call
at dry-run sign-off.

Per context-v/plans/CRM-Starter-Export-Orgs-Then-People.md (Phase 3 —
the Twenty importer — awaits the fresh API key + operator review of
these files).

Files changed:
- scripts/export-crm-orgs-csv.mjs (new)
- scripts/export-crm-people-csv.mjs (new)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RW28dw3kQAKXr2ZNefCukE

Author: mpstaton

scripts/export-crm-orgs-csv.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+// ============================================================================
+// export-crm-orgs-csv.mjs
+//
+// Phase 1 of context-v/plans/CRM-Starter-Export-Orgs-Then-People.md:
+// one row per canonical organization visible to the client, carrying
+//   - identity (slug as external_id, names, aliases, domains, bucket, tags)
+//   - identity links flattened by kind (website/linkedin/x/… + other_links)
+//   - pulse streams (one long-text column — multi-valued by nature)
+//   - org↔org relations summary
+//   - the Master Pipeline Tracker's human columns, joined exact-first via
+//     the pipeline row's corpus_funder_slug, then by name/alias matching
+//   - NO corpora (plan invariant 2)
+//
+// Unmatched pipeline rows are reported to a sidecar CSV, never dropped —
+// they may name orgs never captured (themselves a to-capture list).
+//
+// Reads: SurrealDB direct (orgs/tags/relations — SURREAL_* env) + NATS
+// row-store (the pipeline record set). Writes CSVs; touches nothing.
+//
+// Usage:
+//   set -a; source ./.env; set +a
+//   node scripts/export-crm-orgs-csv.mjs \
+//     [--client reach-edu] \
+//     [--record-set-name-match Master-Pipeline-Tracker] \
+//     [--out-dir clients/<client>/outputs/<YYYY-MM-DD>_crm-starter/]
+// ============================================================================
+
+import { createRequire } from 'node:module';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+const requireScripts = createRequire(new URL('./package.json', import.meta.url));
+const requireServices = createRequire(new URL('../services/social-search/package.json', import.meta.url));
+const { Surreal } = requireScripts('surrealdb');
+const { connect } = requireServices('@nats-io/transport-node');
+
+// ---- args -------------------------------------------------------------------
+const args = { client: 'reach-edu', match: 'Master-Pipeline-Tracker' };
+for (let i = 2; i < process.argv.length; i += 1) {
+  const k = process.argv[i];
+  if (k === '--client') args.client = process.argv[++i];
+  else if (k === '--record-set-name-match') args.match = process.argv[++i];
+  else if (k === '--out-dir') args.outDir = process.argv[++i];
+}
+const today = new Date().toISOString().slice(0, 10);
+const OUT_DIR = resolve(args.outDir ?? `clients/${args.client}/outputs/${today}_crm-starter`);
+
+// ---- csv helpers --------------------------------------------------------------
+const csvEscape = (s) => {
+  const v = String(s ?? '');
+  return /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+};
+const writeCsv = async (path, headers, rows) => {
+  const lines = [headers.join(',')];
+  for (const r of rows) lines.push(headers.map((h) => csvEscape(r[h])).join(','));
+  await writeFile(path, lines.join('\n') + '\n', 'utf8');
+};
+
+// ---- link-kind flattening map --------------------------------------------------
+// First URL of each promoted kind gets its own column; the rest spill into
+// other_links. Kinds observed live 2026-07-27 (19 in use).
+const PROMOTED_KINDS = {
+  website: 'website',
+  linkedin_company: 'linkedin',
+  x_profile: 'x',
+  facebook_profile: 'facebook',
+  instagram_profile: 'instagram',
+  youtube: 'youtube',
+  wikipedia: 'wikipedia',
+  bluesky_profile: 'bluesky',
+  substack: 'substack',
+  team_page: 'team_page',
+};
+
+// ---- pipeline columns replicated (the plan's enumerated human set) -------------
+const PIPELINE_COLS = [
+  'Type', 'Owner', 'Stage', 'Total Commitment ($)', 'FY26 Revenue ($)',
+  'FY27 Revenue ($)', 'Probability (auto)', 'Weighted FY26 (auto)',
+  'Weighted FY27 (auto)', 'Last Contact/Update', 'Notes/Context', 'Next Step',
+  'Next Step Due', 'Next Step Owner', 'Next Step Status', 'Upcoming Event',
+  'RSVP Status',
+];
+
+// ---- name normalization for the fuzzy join --------------------------------------
+const normName = (s) =>
+  String(s ?? '')
+    .replace(/\(.*?\)/g, ' ') // strip parentheticals: "Accelerate the Future (ACH, GW Match)"
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+
+// ---- main -----------------------------------------------------------------------
+const db = new Surreal();
+await db.connect(process.env.SURREAL_URL);
+await db.signin({ username: process.env.SURREAL_USER, password: process.env.SURREAL_PASS });
+await db.use({ namespace: process.env.SURREAL_NS, database: process.env.SURREAL_DB });
+
+// 1. Canonical orgs.
+const orgs = (await db.query(
+  `SELECT id, slug, complete_name, conventional_name, aliases, domains,
+          org_links, media_streams
+     FROM organizations WHERE client_access CONTAINS $client;`,
+  { client: args.client },
+))?.[0] ?? [];
+console.log(`orgs: ${orgs.length}`);
+
+// 2. Org tags (per-client has_tag observations), grouped by subject id.
+const tagRows = (await db.query(
+  `SELECT subject, object FROM observations
+     WHERE predicate = 'has_tag' AND client = $client
+       AND record::tb(subject) = 'organizations';`,
+  { client: args.client },
+))?.[0] ?? [];
+const tagsByOrg = new Map();
+for (const t of tagRows) {
+  const k = String(t.subject);
+  tagsByOrg.set(k, [...(tagsByOrg.get(k) ?? []), String(t.object)]);
+}
+
+// 3. Org↔org relations, projected per org (same semantics as
+//    organization.relations: inbound child_of = child, outbound = parent).
+const relRows = (await db.query(
+  `SELECT rel, kind, in.slug AS in_slug, out.slug AS out_slug FROM affiliations
+     WHERE edge_type = 'org_org' AND client_access CONTAINS $client;`,
+  { client: args.client },
+))?.[0] ?? [];
+const relsByOrg = new Map();
+const addRel = (slug, line) => relsByOrg.set(slug, [...(relsByOrg.get(slug) ?? []), line]);
+for (const r of relRows) {
+  const kind = r.kind ? ` (${r.kind})` : '';
+  if (r.rel === 'peer') {
+    addRel(r.in_slug, `peer: ${r.out_slug}${kind}`);
+    addRel(r.out_slug, `peer: ${r.in_slug}${kind}`);
+  } else {
+    addRel(r.in_slug, `parent: ${r.out_slug}${kind}`);
+    addRel(r.out_slug, `child: ${r.in_slug}${kind}`);
+  }
+}
+
+// 4. Bucket derivation from the client corpus's disk folders.
+const BUCKETS = ['funders', 'gov-entities', 'think-tanks', 'associations-networks', 'academic-institutions', 'data-services'];
+const CORPUS_ROOT = resolve(`clients/${args.client}/corpus`);
+const bucketOf = (slug) => BUCKETS.find((b) => existsSync(join(CORPUS_ROOT, b, slug))) ?? '';
+
+// 5. Pipeline record set over NATS — newest record set whose name matches.
+const nc = await connect({ servers: process.env.NATS_URL ?? 'nats://localhost:4222' });
+const req = async (s, b, t = 30_000) =>
+  JSON.parse(new TextDecoder().decode((await nc.request(s, JSON.stringify(b), { timeout: t })).data));
+const list = await req('record_set.list.requested', {});
+const candidates = (list.record_sets ?? []).filter((s) => (s.name ?? '').includes(args.match));
+candidates.sort((a, b) => String(b.name).localeCompare(String(a.name)));
+const chosen = candidates[0];
+if (!chosen) throw new Error(`no record set matching "${args.match}"`);
+console.log(`pipeline record set: ${chosen.name}`);
+const got = await req('record_set.get.requested', { record_set_id: chosen.record_set_id ?? chosen.id });
+const pipelineRows = (got.rows ?? []).map((r) => r.fields ?? r);
+await nc.drain();
+console.log(`pipeline rows: ${pipelineRows.length}`);
+
+// 6. Join pipeline → orgs: exact by corpus_funder_slug, then name/alias.
+const orgBySlug = new Map(orgs.map((o) => [o.slug, o]));
+const byNorm = new Map(); // normalized name/alias → slug (first wins; collisions logged)
+for (const o of orgs) {
+  for (const cand of [o.complete_name, o.conventional_name, o.slug.replace(/-/g, ' '), ...(o.aliases ?? [])]) {
+    const n = normName(cand);
+    if (n && !byNorm.has(n)) byNorm.set(n, o.slug);
+  }
+}
+const pipelineByOrg = new Map(); // slug → { row, matched }
+const unmatched = [];
+for (const row of pipelineRows) {
+  const name = row['Prospect / Organization'] ?? '';
+  const exact = row.corpus_funder_slug && orgBySlug.has(row.corpus_funder_slug) ? row.corpus_funder_slug : null;
+  const fuzzy = exact ? null : byNorm.get(normName(name));
+  const slug = exact ?? fuzzy;
+  if (!slug) {
+    unmatched.push(row);
+    continue;
+  }
+  if (!pipelineByOrg.has(slug)) {
+    pipelineByOrg.set(slug, { row, matched: exact ? 'exact' : 'fuzzy' });
+  } else {
+    console.warn(`  ⚠ second pipeline row also matches ${slug}: "${name}" — kept the first, this one goes to the sidecar`);
+    unmatched.push(row);
+  }
+}
+console.log(`pipeline matched: ${pipelineByOrg.size} (exact+fuzzy) · unmatched: ${unmatched.length}`);
+
+// 7. Shape org rows.
+const exported_at = new Date().toISOString();
+const outRows = orgs.map((o) => {
+  const links = o.org_links ?? [];
+  const flat = {};
+  const other = [];
+  for (const l of links) {
+    const col = PROMOTED_KINDS[l.kind];
+    if (col && !flat[col]) flat[col] = l.url;
+    else other.push(`${l.kind ?? 'other'}: ${l.url}`);
+  }
+  const streams = (o.media_streams ?? []).map((s) => `${s.name ? s.name + ' — ' : ''}${s.url}${s.kind ? ` (${s.kind})` : ''}`);
+  const p = pipelineByOrg.get(o.slug);
+  const row = {
+    external_id: o.slug,
+    name: o.complete_name ?? o.conventional_name ?? o.slug,
+    conventional_name: o.conventional_name ?? '',
+    aliases: (o.aliases ?? []).join(' | '),
+    domains: (o.domains ?? []).map((d) => d.domain).filter(Boolean).join(' | '),
+    bucket: bucketOf(o.slug),
+    tags: (tagsByOrg.get(String(o.id)) ?? []).join(' | '),
+    ...Object.fromEntries(Object.values(PROMOTED_KINDS).map((c) => [c, flat[c] ?? ''])),
+    other_links: other.join('\n'),
+    streams: streams.join('\n'),
+    stream_count: streams.length,
+    related_orgs: (relsByOrg.get(o.slug) ?? []).join('\n'),
+    pipeline_org_name: p?.row['Prospect / Organization'] ?? '',
+    pipeline_matched: p?.matched ?? 'none',
+    ...Object.fromEntries(PIPELINE_COLS.map((c) => [c, p?.row[c] ?? ''])),
+    exported_at,
+  };
+  return row;
+});
+
+// Pipeline-matched rows first (they're the review priority), then by name.
+outRows.sort((a, b) =>
+  (a.pipeline_matched === 'none') - (b.pipeline_matched === 'none') || a.name.localeCompare(b.name));
+
+const HEADERS = [
+  'external_id', 'name', 'conventional_name', 'aliases', 'domains', 'bucket', 'tags',
+  ...Object.values(PROMOTED_KINDS), 'other_links', 'streams', 'stream_count', 'related_orgs',
+  'pipeline_org_name', 'pipeline_matched', ...PIPELINE_COLS, 'exported_at',
+];
+
+await mkdir(OUT_DIR, { recursive: true });
+await writeCsv(join(OUT_DIR, 'orgs.csv'), HEADERS, outRows);
+console.log(`wrote ${outRows.length} rows → ${join(OUT_DIR, 'orgs.csv')}`);
+
+if (unmatched.length > 0) {
+  const uHeaders = Object.keys(unmatched[0]);
+  await writeCsv(join(OUT_DIR, 'unmatched-pipeline-rows.csv'), uHeaders, unmatched);
+  console.log(`wrote ${unmatched.length} unmatched pipeline rows → ${join(OUT_DIR, 'unmatched-pipeline-rows.csv')}`);
+}
+
+const fuzzyCount = outRows.filter((r) => r.pipeline_matched === 'fuzzy').length;
+console.log(`review: ${fuzzyCount} fuzzy pipeline matches flagged in pipeline_matched`);
+await db.close();

scripts/export-crm-people-csv.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// ============================================================================
+// export-crm-people-csv.mjs
+//
+// Phase 2 of context-v/plans/CRM-Starter-Export-Orgs-Then-People.md:
+// one row per PERSON (deliberately NOT per affiliation edge — a person with
+// two affiliations must not become two CRM contacts; the inversion of
+// export-affiliation-ratings-csv.mjs's shape, reasoned in the plan).
+//
+// The strongest affiliation (relevance-ranked) supplies the org attach
+// (org_external_id = the org slug, matching orgs.csv's external_id); the
+// remaining edges ride in additional_orgs. Persons with zero affiliations
+// still export with blank org columns — the CRM decides about orphans.
+//
+// Usage:
+//   set -a; source ./.env; set +a
+//   node scripts/export-crm-people-csv.mjs \
+//     [--client reach-edu] \
+//     [--out-dir clients/<client>/outputs/<YYYY-MM-DD>_crm-starter/]
+// ============================================================================
+
+import { createRequire } from 'node:module';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+
+const requireScripts = createRequire(new URL('./package.json', import.meta.url));
+const { Surreal } = requireScripts('surrealdb');
+
+const args = { client: 'reach-edu' };
+for (let i = 2; i < process.argv.length; i += 1) {
+  const k = process.argv[i];
+  if (k === '--client') args.client = process.argv[++i];
+  else if (k === '--out-dir') args.outDir = process.argv[++i];
+}
+const today = new Date().toISOString().slice(0, 10);
+const OUT_DIR = resolve(args.outDir ?? `clients/${args.client}/outputs/${today}_crm-starter`);
+
+const csvEscape = (s) => {
+  const v = String(s ?? '');
+  return /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+};
+
+// Relevance ranking — the operator's labels outrank unrated; skip/irrelevant
+// sink below unrated so a person's "best" org is never one they were rated
+// irrelevant for when an unrated alternative exists.
+const RELEVANCE_RANK = {
+  very_relevant: 5,
+  highly_relevant: 4,
+  relevant: 3,
+  '': 2,
+  skip: 1,
+  irrelevant: 0,
+};
+const rankOf = (r) => RELEVANCE_RANK[r ?? ''] ?? 2;
+
+const db = new Surreal();
+await db.connect(process.env.SURREAL_URL);
+await db.signin({ username: process.env.SURREAL_USER, password: process.env.SURREAL_PASS });
+await db.use({ namespace: process.env.SURREAL_NS, database: process.env.SURREAL_DB });
+
+// 1. Persons visible to the client.
+const persons = (await db.query(
+  `SELECT id, person_uuid, name, full_name, first_name, surname, email,
+          linkedin_profile_url, headline, personal_links
+     FROM persons WHERE client_access CONTAINS $client;`,
+  { client: args.client },
+))?.[0] ?? [];
+console.log(`persons: ${persons.length}`);
+
+// 2. Person→org edges in one pass (org_org edges excluded by shape: their
+//    `in` is an organizations row, so in.person_uuid is absent — the same
+//    guard the People Reveal relies on).
+const edges = (await db.query(
+  `SELECT in.person_uuid AS person_uuid, out.slug AS org_slug,
+          out.complete_name AS org_complete, out.conventional_name AS org_conventional,
+          kind, relevance
+     FROM affiliations WHERE in.person_uuid != NONE;`,
+))?.[0] ?? [];
+const edgesByPerson = new Map();
+for (const e of edges) {
+  const k = String(e.person_uuid);
+  edgesByPerson.set(k, [...(edgesByPerson.get(k) ?? []), e]);
+}
+console.log(`person→org edges: ${edges.length}`);
+
+// 3. Shape one row per person.
+const exported_at = new Date().toISOString();
+const rows = persons.map((p) => {
+  const my = (edgesByPerson.get(String(p.person_uuid)) ?? [])
+    .slice()
+    .sort((a, b) => rankOf(b.relevance) - rankOf(a.relevance));
+  const primary = my[0];
+  const extras = my.slice(1);
+  const links = p.personal_links ?? [];
+  const linkedin =
+    p.linkedin_profile_url ??
+    links.find((l) => /linkedin\.com\/in\//i.test(l.url ?? ''))?.url ??
+    '';
+  const other = links
+    .filter((l) => (l.url ?? '') !== linkedin)
+    .map((l) => `${l.kind ?? 'other'}: ${l.url}`);
+  return {
+    external_id: p.person_uuid,
+    name: p.name ?? p.full_name ?? '',
+    first_name: p.first_name ?? '',
+    surname: p.surname ?? '',
+    email: p.email ?? '',
+    linkedin,
+    headline: p.headline ?? '',
+    org_external_id: primary?.org_slug ?? '',
+    org_name: primary ? (primary.org_complete ?? primary.org_conventional ?? primary.org_slug) : '',
+    role: primary?.kind ?? '',
+    relevance: primary?.relevance ?? '',
+    additional_orgs: extras.map((e) => `${e.org_slug} — ${e.kind ?? '-'}${e.relevance ? ` (${e.relevance})` : ''}`).join('\n'),
+    other_links: other.join('\n'),
+    exported_at,
+  };
+});
+
+// Attached-and-rated first, then attached, then orphans; alphabetical within.
+rows.sort((a, b) =>
+  (a.org_external_id === '') - (b.org_external_id === '') ||
+  rankOf(b.relevance) - rankOf(a.relevance) ||
+  a.name.localeCompare(b.name));
+
+const HEADERS = [
+  'external_id', 'name', 'first_name', 'surname', 'email', 'linkedin', 'headline',
+  'org_external_id', 'org_name', 'role', 'relevance', 'additional_orgs',
+  'other_links', 'exported_at',
+];
+await mkdir(OUT_DIR, { recursive: true });
+const lines = [HEADERS.join(',')];
+for (const r of rows) lines.push(HEADERS.map((h) => csvEscape(r[h])).join(','));
+await writeFile(join(OUT_DIR, 'people.csv'), lines.join('\n') + '\n', 'utf8');
+
+const orphans = rows.filter((r) => !r.org_external_id).length;
+const multi = rows.filter((r) => r.additional_orgs).length;
+console.log(`wrote ${rows.length} rows → ${join(OUT_DIR, 'people.csv')}`);
+console.log(`attached: ${rows.length - orphans} · orphans (no affiliation): ${orphans} · multi-affiliation: ${multi}`);
+await db.close();