@localpulse/cli 0.0.3 → 0.0.5

package/README.md

@@ -10,15 +10,15 @@ CLI for [Local Pulse](https://localpulse.nl) — ingest event posters, search ev
 bunx @localpulse/cli --help
 ```
 
-**Standalone binary:**
-
-Download the latest binary for your platform from the [releases page](https://github.com/localpulse/local_pulse/releases), then:
+**Global install:**
 
 ```sh
-chmod +x localpulse
-./localpulse --help
+bun add -g @localpulse/cli
+localpulse --help
 ```
 
+See the package on [npm](https://www.npmjs.com/package/@localpulse/cli).
+
 ## Quick start
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localpulse/cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Local Pulse CLI — ingest event posters, search events, manage credentials",
   "type": "module",
   "license": "MIT",

package/src/index.test.ts

@@ -53,7 +53,7 @@ describe("localpulse", () => {
     expect(stdout).toContain("--dry-run");
     expect(stdout).toContain("--json");
     expect(stdout).toContain("Examples:");
-    expect(stdout).not.toContain("--performers");
+    expect(stdout).not.toContain("--featured");
     expect(stdout).not.toContain("--genre");
     expect(stdout).not.toContain("--socials");
     expect(stdout).not.toContain("--organizer");
@@ -127,7 +127,7 @@ describe("localpulse", () => {
     expect(exitCode).toBe(0);
     const skeleton = JSON.parse(stdout);
     expect(() => validateResearchPayload(skeleton)).not.toThrow();
-    expect(skeleton.performers).toBeDefined();
+    expect(skeleton.featured).toBeDefined();
     expect(skeleton.event).toBeDefined();
     expect(skeleton.venue).toBeDefined();
     expect(skeleton.organizer).toBeDefined();
@@ -136,8 +136,18 @@ describe("localpulse", () => {
   it("validates research payload from file with --dry-run", async () => {
     const researchFile = join(tmpdir(), `lp-test-${Date.now()}.json`);
     await writeFile(researchFile, JSON.stringify({
-      performers: [{ name: "DJ Nobu", genre: "techno" }],
-      event: { title: "Test Night" },
+      featured: [
+        { name: "DJ Nobu", type: "DJ", genre: "techno", socials: ["https://instagram.com/djnobu"], context: "Berlin-based" },
+      ],
+      organizer: { name: "Dekmantel", socials: ["https://instagram.com/dekmantel"] },
+      venue: { name: "Shelter", city: "Amsterdam", google_place_id: "ChIJ123" },
+      event: {
+        title: "Test Night",
+        date: "2026-03-14T22:00:00+01:00",
+        type: "club night",
+        urls: ["https://ra.co/events/123", "https://example.com/event"],
+        ticket_url: "https://tickets.example.com",
+      },
     }));
 
     const { exitCode, stdout } = runCli("ingest", "../../README.md", "--research", researchFile, "--dry-run");
@@ -145,6 +155,36 @@ describe("localpulse", () => {
     expect(stdout).toContain("Dry run passed");
   });
 
+  it("rejects thin research payload with audit findings", async () => {
+    const researchFile = join(tmpdir(), `lp-test-${Date.now()}.json`);
+    await writeFile(researchFile, JSON.stringify({
+      featured: [],
+      event: { title: "Test" },
+    }));
+
+    const { exitCode, stderr } = runCli("ingest", "../../README.md", "--research", researchFile, "--dry-run");
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("audit failed");
+    expect(stderr).toContain("featured");
+    expect(stderr).toContain("Fix these issues");
+  });
+
+  it("outputs structured audit findings with --json", async () => {
+    const researchFile = join(tmpdir(), `lp-test-${Date.now()}.json`);
+    await writeFile(researchFile, JSON.stringify({
+      event: { title: "Test" },
+    }));
+
+    const { exitCode, stdout } = runCli("ingest", "../../README.md", "--research", researchFile, "--json");
+    expect(exitCode).toBe(1);
+    const result = JSON.parse(stdout);
+    expect(result.audit_failed).toBe(true);
+    expect(result.findings).toBeArray();
+    expect(result.findings.length).toBeGreaterThan(0);
+    expect(result.findings[0].field).toBeDefined();
+    expect(result.findings[0].action).toBeDefined();
+  });
+
   it("rejects invalid research payload", async () => {
     const researchFile = join(tmpdir(), `lp-test-${Date.now()}.json`);
     await writeFile(researchFile, JSON.stringify({ performers: "not-an-array" }));

package/src/index.ts

@@ -17,6 +17,7 @@ import {
 } from "./lib/credentials";
 import { loginWithToken } from "./lib/login";
 import { exitCodeForError, printError } from "./lib/output";
+import { auditResearchPayload, formatAuditFindings } from "./lib/research-audit";
 import { readResearchPayload } from "./lib/research-reader";
 import {
   generateResearchSkeleton,
@@ -189,6 +190,19 @@ async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   }
 
   const payload = await readResearchPayload(researchPath);
+  const jsonOutput = hasOption(parsed, "json");
+
+  const audit = auditResearchPayload(payload);
+  if (!audit.pass) {
+    if (jsonOutput) {
+      stdout.write(`${JSON.stringify({ audit_failed: true, findings: audit.findings })}\n`);
+    } else {
+      process.stderr.write(formatAuditFindings(audit.findings));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
   const mapped = mapResearchToUploadFields(payload);
   const stitched = stitchResearchContext(payload);
   const explicitContext = readStringOption(parsed, "context");
@@ -197,7 +211,6 @@ async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   const apiUrl = await resolveApiUrl();
   const dryRun = hasOption(parsed, "dry-run");
   const force = hasOption(parsed, "force");
-  const jsonOutput = hasOption(parsed, "json");
   const token = dryRun ? "" : await requireToken();
 
   const uploadOptions = {
@@ -525,21 +538,46 @@ Research payload:
   The payload is JSON with five top-level sections. All are optional,
   but richer research produces much better event listings.
 
+  Research guidance:
+  The source URL is a starting point, not the finish line. After extracting
+  what the page provides, use Instagram graph traversal and web search to
+  fill gaps. Do NOT guess or fabricate profile URLs — verify every link.
+
+  Entity discovery (preferred order):
+  1. Find the venue or organizer's Instagram profile first.
+  2. Browse their recent posts or Reels for the event announcement.
+  3. Check who is tagged in that post — these are verified performer handles.
+  4. Also check the caption for @mentions, #hashtags, and links.
+  5. Visit each tagged profile: their bio contains verified links (website,
+     Spotify, Bandcamp, YouTube) and genre/context info for featured[].context.
+  6. Check the venue's Tagged tab for posts where others tag the venue —
+     artists promoting the event often tag the venue and each other.
+
+  Fallback research (when Instagram doesn't surface enough):
+  - Search "{name}" to find their website and background.
+  - Search Google Maps for "{venue} {city}" and extract the google_place_id.
+  - Search for the event on RA, Facebook, or the venue's own website.
+
+  Every person mentioned on the event page or tagged in the Instagram post
+  should appear in featured[] with a type that fits (chef, DJ, host…).
+
   Quality checklist (aim to fill as many as possible):
-  ✓ Performer socials: Instagram, Spotify, Bandcamp, SoundCloud, RA, website
+  ✓ Featured person socials: Instagram (verified via tags), website, Spotify, Bandcamp, RA
+  ✓ Featured person context: pull from Instagram bio — genre, notable work, links
   ✓ Organizer socials: Instagram, website, RA promoter page
   ✓ Venue google_place_id (search Google Maps → share → extract place ID)
   ✓ Multiple event.urls: venue page, RA, Facebook event, artist page
   ✓ Embed URLs in context: Spotify album/track links, YouTube videos
-  ✓ Performer context: recent releases, labels, residencies, tour info
-  ✓ All support acts as separate performer entries
-
-  performers[]            Who is performing or presenting
-    .name                 Full name (required per performer)
-    .type                 What they are: "DJ", "band", "speaker", "visual artist"
-    .genre                Style or genre: "techno", "jazz", "stand-up comedy"
+  ✓ All featured people as separate entries (support acts, guest chefs, co-hosts)
+  ✓ Discover unlisted performers via Instagram tags (support acts, guest hosts)
+
+  featured[]              Who is featured — performers, chefs, hosts, speakers
+    .name                 Full name (required per person)
+    .type                 Their role: "DJ", "chef", "band", "host", "speaker",
+                          "visual artist", "cook"
+    .genre                Style, genre, or cuisine: "techno", "jazz", "Kerala"
     .socials[]            Profile URLs: Instagram, RA, Bandcamp, personal site
-    .context              Anything else: bio, residencies, notable releases
+    .context              Anything else: bio, notable work, affiliations
 
   organizer               Who is putting on the event
     .name                 Collective, promoter, or brand name (required)
@@ -556,7 +594,8 @@ Research payload:
     .title                Event name
     .date                 ISO 8601 datetime (e.g. "2026-03-14T22:00:00+01:00")
     .type                 Kind of event: "club night", "festival", "exhibition",
-                          "workshop", "concert", "open air", "listening session"
+                          "workshop", "concert", "open air", "listening session",
+                          "pop-up dinner", "food event", "tasting", "market"
     .price                Ticket price info: "€15-25", "Free", "Sold out"
     .urls[]               Source pages: RA, venue site, Facebook event
     .ticket_url           Direct ticketing / purchase URL

package/src/lib/research-audit.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, it } from "bun:test";
+
+import { auditResearchPayload, formatAuditFindings } from "./research-audit";
+import { generateResearchSkeleton } from "./research-schema";
+
+describe("auditResearchPayload", () => {
+  it("passes a complete payload", () => {
+    const payload = {
+      ...generateResearchSkeleton(),
+      venue: {
+        name: "Shelter Amsterdam",
+        city: "Amsterdam",
+        google_place_id: "ChIJ123abc",
+        context: "Underground club beneath A'DAM Tower",
+      },
+      event: {
+        ...generateResearchSkeleton().event,
+        urls: [
+          "https://ra.co/events/1234567",
+          "https://www.dekmantel.com/events/shelter-nobu",
+        ],
+      },
+    };
+    const result = auditResearchPayload(payload);
+    expect(result.pass).toBe(true);
+    expect(result.findings).toHaveLength(0);
+  });
+
+  it("flags an empty payload with findings for every section", () => {
+    const result = auditResearchPayload({});
+    expect(result.pass).toBe(false);
+    const fields = result.findings.map((f) => f.field);
+    expect(fields).toContain("featured");
+    expect(fields).toContain("organizer");
+    expect(fields).toContain("venue");
+    expect(fields).toContain("event");
+  });
+
+  it("short-circuits: missing section emits one finding, not per-field", () => {
+    const result = auditResearchPayload({});
+    const venueFindings = result.findings.filter((f) => f.field.startsWith("venue"));
+    expect(venueFindings).toHaveLength(1);
+    expect(venueFindings[0].field).toBe("venue");
+  });
+
+  // --- featured ---
+
+  it("flags empty featured array", () => {
+    const result = auditResearchPayload({ featured: [] });
+    const f = result.findings.find((f) => f.field === "featured");
+    expect(f).toBeDefined();
+    expect(f!.action).toContain("featured[]");
+  });
+
+  it("flags featured person missing type, socials, and context", () => {
+    const result = auditResearchPayload({
+      featured: [{ name: "Sherin Kalam" }],
+    });
+    const fields = result.findings.map((f) => f.field);
+    expect(fields).toContain("featured[0].type");
+    expect(fields).toContain("featured[0].socials");
+    expect(fields).toContain("featured[0].context");
+  });
+
+  it("does not flag featured person with complete data", () => {
+    const result = auditResearchPayload({
+      featured: [
+        {
+          name: "DJ Nobu",
+          type: "DJ",
+          socials: ["https://instagram.com/djnobu"],
+          context: "Berlin-based Japanese DJ",
+        },
+      ],
+    });
+    const featuredFindings = result.findings.filter((f) => f.field.startsWith("featured"));
+    expect(featuredFindings).toHaveLength(0);
+  });
+
+  it("templates person name into action text", () => {
+    const result = auditResearchPayload({
+      featured: [{ name: "Sherin Kalam" }],
+    });
+    const socials = result.findings.find((f) => f.field === "featured[0].socials");
+    expect(socials!.action).toContain("Sherin Kalam");
+  });
+
+  // --- organizer ---
+
+  it("flags missing organizer", () => {
+    const result = auditResearchPayload({});
+    expect(result.findings.find((f) => f.field === "organizer")).toBeDefined();
+  });
+
+  it("flags organizer without socials", () => {
+    const result = auditResearchPayload({
+      organizer: { name: "Wanakam" },
+    });
+    const f = result.findings.find((f) => f.field === "organizer.socials");
+    expect(f).toBeDefined();
+    expect(f!.action).toContain("Wanakam");
+  });
+
+  it("does not flag organizer with socials", () => {
+    const result = auditResearchPayload({
+      organizer: {
+        name: "Wanakam",
+        socials: ["https://instagram.com/wanakam"],
+      },
+    });
+    const orgFindings = result.findings.filter((f) => f.field.startsWith("organizer"));
+    expect(orgFindings).toHaveLength(0);
+  });
+
+  // --- venue ---
+
+  it("flags venue without city", () => {
+    const result = auditResearchPayload({
+      venue: { name: "Shelter" },
+    });
+    expect(result.findings.find((f) => f.field === "venue.city")).toBeDefined();
+  });
+
+  it("flags venue without google_place_id", () => {
+    const result = auditResearchPayload({
+      venue: { name: "Shelter", city: "Amsterdam" },
+    });
+    const f = result.findings.find((f) => f.field === "venue.google_place_id");
+    expect(f).toBeDefined();
+    expect(f!.action).toContain("Shelter Amsterdam");
+  });
+
+  it("flags venue with empty-string google_place_id", () => {
+    const result = auditResearchPayload({
+      venue: { name: "Shelter", city: "Amsterdam", google_place_id: "" },
+    });
+    expect(result.findings.find((f) => f.field === "venue.google_place_id")).toBeDefined();
+  });
+
+  // --- event ---
+
+  it("flags event with no title", () => {
+    const result = auditResearchPayload({ event: {} });
+    expect(result.findings.find((f) => f.field === "event.title")).toBeDefined();
+  });
+
+  it("flags event with no date", () => {
+    const result = auditResearchPayload({ event: {} });
+    expect(result.findings.find((f) => f.field === "event.date")).toBeDefined();
+  });
+
+  it("flags event with no type", () => {
+    const result = auditResearchPayload({ event: {} });
+    expect(result.findings.find((f) => f.field === "event.type")).toBeDefined();
+  });
+
+  it("flags event with no urls", () => {
+    const result = auditResearchPayload({ event: {} });
+    expect(result.findings.find((f) => f.field === "event.urls")).toBeDefined();
+  });
+
+  it("flags event with only 1 url", () => {
+    const result = auditResearchPayload({
+      event: { urls: ["https://example.com"] },
+    });
+    const f = result.findings.find((f) => f.field === "event.urls");
+    expect(f).toBeDefined();
+    expect(f!.message).toContain("Only 1");
+  });
+
+  it("does not flag event with 2+ urls", () => {
+    const result = auditResearchPayload({
+      event: { urls: ["https://example.com", "https://ra.co/events/123"] },
+    });
+    expect(result.findings.find((f) => f.field === "event.urls")).toBeUndefined();
+  });
+
+  it("flags missing ticket_url when price is not free", () => {
+    const result = auditResearchPayload({
+      event: { price: "€15" },
+    });
+    expect(result.findings.find((f) => f.field === "event.ticket_url")).toBeDefined();
+  });
+
+  it("does not flag missing ticket_url when price is Free", () => {
+    const result = auditResearchPayload({
+      event: { price: "Free" },
+    });
+    expect(result.findings.find((f) => f.field === "event.ticket_url")).toBeUndefined();
+  });
+
+  it("does not flag missing ticket_url when price is free (case-insensitive)", () => {
+    const result = auditResearchPayload({
+      event: { price: "free" },
+    });
+    expect(result.findings.find((f) => f.field === "event.ticket_url")).toBeUndefined();
+  });
+
+  it("flags missing ticket_url when no price is set", () => {
+    const result = auditResearchPayload({
+      event: {},
+    });
+    expect(result.findings.find((f) => f.field === "event.ticket_url")).toBeDefined();
+  });
+});
+
+describe("formatAuditFindings", () => {
+  it("formats findings as human-readable text", () => {
+    const output = formatAuditFindings([
+      {
+        field: "featured",
+        message: "No featured people provided.",
+        action: "Add entries to featured[].",
+
+      },
+      {
+        field: "venue.google_place_id",
+        message: "No google_place_id for venue 'Shelter'.",
+        action: "Search Google Maps.",
+
+      },
+    ]);
+    expect(output).toContain("2 issues found");
+    expect(output).toContain("featured");
+    expect(output).toContain("No featured people provided.");
+    expect(output).toContain("-> Add entries to featured[].");
+    expect(output).toContain("venue.google_place_id");
+    expect(output).toContain("Fix these issues and retry.");
+  });
+
+  it("uses singular 'issue' for 1 finding", () => {
+    const output = formatAuditFindings([
+      {
+        field: "event.title",
+        message: "No event title.",
+        action: "Set event.title.",
+
+      },
+    ]);
+    expect(output).toContain("1 issue found");
+  });
+});

package/src/lib/research-audit.ts

@@ -0,0 +1,204 @@
+import type { ResearchPayload } from "./research-schema";
+
+export type AuditFinding = {
+  field: string;
+  message: string;
+  action: string;
+};
+
+export type AuditResult = {
+  pass: boolean;
+  findings: AuditFinding[];
+};
+
+export function auditResearchPayload(payload: ResearchPayload): AuditResult {
+  const findings = [
+    ...auditFeatured(payload),
+    ...auditOrganizer(payload),
+    ...auditVenue(payload),
+    ...auditEvent(payload),
+  ];
+
+  return { pass: findings.length === 0, findings };
+}
+
+function finding(field: string, message: string, action: string): AuditFinding {
+  return { field, message, action };
+}
+
+function auditFeatured(payload: ResearchPayload): AuditFinding[] {
+  if (!payload.featured?.length) {
+    return [
+      finding(
+        "featured",
+        "No featured people provided.",
+        "Read the event page for anyone mentioned (performers, chefs, hosts, speakers). Add each to featured[].",
+      ),
+    ];
+  }
+
+  const findings: AuditFinding[] = [];
+  for (let i = 0; i < payload.featured.length; i++) {
+    const person = payload.featured[i];
+    const label = `featured[${i}] ('${person.name}')`;
+
+    if (!person.type?.trim()) {
+      findings.push(
+        finding(
+          `featured[${i}].type`,
+          `${label} has no type.`,
+          `Set featured[${i}].type to their role (e.g., 'DJ', 'chef', 'host', 'speaker', 'visual artist').`,
+        ),
+      );
+    }
+
+    if (!person.socials?.length) {
+      findings.push(
+        finding(
+          `featured[${i}].socials`,
+          `${label} has no social profiles.`,
+          `Check the venue/organizer's Instagram for posts about this event — look for @${person.name.toLowerCase().replace(/\s+/g, '')} in tags or caption. If not tagged, search '${person.name} instagram'. Add verified URLs to featured[${i}].socials[].`,
+        ),
+      );
+    }
+
+    if (!person.context?.trim()) {
+      findings.push(
+        finding(
+          `featured[${i}].context`,
+          `${label} has no context.`,
+          `Visit ${person.name}'s Instagram profile — pull genre, bio, and notable work for featured[${i}].context. Include any Spotify/Bandcamp/website links from their bio.`,
+        ),
+      );
+    }
+  }
+  return findings;
+}
+
+function auditOrganizer(payload: ResearchPayload): AuditFinding[] {
+  if (!payload.organizer?.name?.trim()) {
+    return [
+      finding("organizer", "No organizer provided.", "Identify who is organizing this event and set organizer.name."),
+    ];
+  }
+
+  const name = payload.organizer.name;
+  if (!payload.organizer.socials?.length) {
+    return [
+      finding(
+        "organizer.socials",
+        `Organizer '${name}' has no social profiles.`,
+        `Find '${name}' on Instagram (browse their profile directly). Pull socials from their bio. Add URLs to organizer.socials[].`,
+      ),
+    ];
+  }
+  return [];
+}
+
+function auditVenue(payload: ResearchPayload): AuditFinding[] {
+  if (!payload.venue?.name?.trim()) {
+    return [finding("venue", "No venue name provided.", "Identify the venue from the event page and set venue.name.")];
+  }
+
+  const findings: AuditFinding[] = [];
+  const name = payload.venue.name;
+
+  if (!payload.venue.city?.trim()) {
+    findings.push(
+      finding("venue.city", `No city provided for venue '${name}'.`, `Set venue.city to the city where '${name}' is located.`),
+    );
+  }
+
+  if (!payload.venue.google_place_id?.trim()) {
+    const city = payload.venue.city?.trim() ?? "the city";
+    findings.push(
+      finding(
+        "venue.google_place_id",
+        `No google_place_id for venue '${name}'.`,
+        `Search Google Maps for '${name} ${city}' and extract the place ID from the share URL.`,
+      ),
+    );
+  }
+  return findings;
+}
+
+function auditEvent(payload: ResearchPayload): AuditFinding[] {
+  if (!payload.event) {
+    return [
+      finding(
+        "event",
+        "No event details provided.",
+        "Extract the event title, date, and type from the event page and populate the event section.",
+      ),
+    ];
+  }
+
+  const findings: AuditFinding[] = [];
+
+  if (!payload.event.title?.trim()) {
+    findings.push(finding("event.title", "No event title provided.", "Set event.title to the event name from the source page."));
+  }
+
+  if (!payload.event.date?.trim()) {
+    findings.push(
+      finding("event.date", "No event date provided.", "Set event.date in ISO 8601 format (e.g., '2026-04-05T11:30:00+02:00')."),
+    );
+  }
+
+  if (!payload.event.type?.trim()) {
+    findings.push(
+      finding(
+        "event.type",
+        "No event type provided.",
+        "Set event.type (e.g., 'club night', 'concert', 'food event', 'festival', 'exhibition', 'market').",
+      ),
+    );
+  }
+
+  if (!payload.event.urls?.length) {
+    findings.push(
+      finding(
+        "event.urls",
+        "No event URLs provided.",
+        "Add the source page URL to event.urls[]. Search for the event on RA, Facebook, or the venue's website and add those too.",
+      ),
+    );
+  } else if (payload.event.urls.length === 1) {
+    findings.push(
+      finding(
+        "event.urls",
+        "Only 1 event URL provided.",
+        "Search for this event on RA (ra.co), Facebook Events, or the venue's website and add additional URLs to event.urls[].",
+      ),
+    );
+  }
+
+  const isFree = payload.event.price?.trim().toLowerCase() === "free";
+  if (!payload.event.ticket_url?.trim() && !isFree) {
+    findings.push(
+      finding(
+        "event.ticket_url",
+        "No ticket URL provided.",
+        "Find the ticketing page for this event and set event.ticket_url. If the event is free, set event.price to 'Free'.",
+      ),
+    );
+  }
+
+  return findings;
+}
+
+export function formatAuditFindings(findings: AuditFinding[]): string {
+  const count = findings.length;
+  const lines: string[] = [
+    `\nResearch payload audit failed. ${count} issue${count === 1 ? "" : "s"} found:\n`,
+  ];
+
+  for (const f of findings) {
+    lines.push(`  ${f.field}`);
+    lines.push(`    ${f.message}`);
+    lines.push(`    -> ${f.action}\n`);
+  }
+
+  lines.push("Fix these issues and retry.\n");
+  return lines.join("\n");
+}

package/src/lib/research-schema.test.ts

@@ -10,7 +10,7 @@ import {
 describe("validateResearchPayload", () => {
   it("accepts a full payload with all fields", () => {
     const payload = validateResearchPayload({
-      performers: [
+      featured: [
         {
           name: "DJ Nobu",
           type: "DJ",
@@ -42,8 +42,8 @@ describe("validateResearchPayload", () => {
       },
       context: "Two rooms",
     });
-    expect(payload.performers).toHaveLength(2);
-    expect(payload.performers![0].type).toBe("DJ");
+    expect(payload.featured).toHaveLength(2);
+    expect(payload.featured![0].type).toBe("DJ");
     expect(payload.venue?.context).toBe("Underground club, 350 capacity");
     expect(payload.event?.type).toBe("club night");
   });
@@ -52,26 +52,34 @@ describe("validateResearchPayload", () => {
     expect(validateResearchPayload({})).toEqual({});
   });
 
-  it("accepts a payload with only performers", () => {
+  it("accepts a payload with only featured", () => {
     const payload = validateResearchPayload({
-      performers: [{ name: "Objekt" }],
+      featured: [{ name: "Objekt" }],
     });
-    expect(payload.performers).toHaveLength(1);
+    expect(payload.featured).toHaveLength(1);
   });
 
-  it("rejects a payload where performers is not an array", () => {
-    expect(() => validateResearchPayload({ performers: "DJ Nobu" })).toThrow("Invalid research payload");
+  it("rejects a payload where featured is not an array", () => {
+    expect(() => validateResearchPayload({ featured: "DJ Nobu" })).toThrow("Invalid research payload");
   });
 
   it("rejects a performer missing name", () => {
-    expect(() => validateResearchPayload({ performers: [{ genre: "techno" }] })).toThrow("Invalid research payload");
+    expect(() => validateResearchPayload({ featured: [{ genre: "techno" }] })).toThrow("Invalid research payload");
+  });
+
+  it("migrates legacy 'performers' key to 'featured'", () => {
+    const payload = validateResearchPayload({
+      performers: [{ name: "DJ Nobu", type: "DJ" }],
+    });
+    expect(payload.featured).toHaveLength(1);
+    expect(payload.featured![0].name).toBe("DJ Nobu");
   });
 });
 
 describe("stitchResearchContext", () => {
   it("produces formatted output preserving entity context", () => {
     const result = stitchResearchContext({
-      performers: [
+      featured: [
         {
           name: "DJ Nobu",
           type: "DJ",
@@ -99,7 +107,7 @@ describe("stitchResearchContext", () => {
       context: "Cash only at door",
     });
 
-    expect(result).toContain("## Performers");
+    expect(result).toContain("## Featured");
     expect(result).toContain("- DJ Nobu (DJ, techno)");
     expect(result).toContain("Berlin-based, known for long hypnotic sets");
     expect(result).toContain("Profiles: https://instagram.com/djnobu");
@@ -122,9 +130,9 @@ describe("stitchResearchContext", () => {
 
   it("omits sections without data", () => {
     const result = stitchResearchContext({
-      performers: [{ name: "Objekt" }],
+      featured: [{ name: "Objekt" }],
     });
-    expect(result).toContain("## Performers");
+    expect(result).toContain("## Featured");
     expect(result).not.toContain("## Organizer");
     expect(result).not.toContain("## Venue");
     expect(result).not.toContain("## Event");
@@ -169,9 +177,9 @@ describe("generateResearchSkeleton", () => {
 
   it("includes all entity sections with example data", () => {
     const skeleton = generateResearchSkeleton();
-    expect(skeleton.performers![0].name).toBeTruthy();
-    expect(skeleton.performers![0].type).toBeTruthy();
-    expect(skeleton.performers![0].context).toBeTruthy();
+    expect(skeleton.featured![0].name).toBeTruthy();
+    expect(skeleton.featured![0].type).toBeTruthy();
+    expect(skeleton.featured![0].context).toBeTruthy();
     expect(skeleton.organizer!.context).toBeTruthy();
     expect(skeleton.venue!.context).toBeTruthy();
     expect(skeleton.event!.type).toBeTruthy();

package/src/lib/research-schema.ts

@@ -1,7 +1,7 @@
 import { Type, type Static } from "@sinclair/typebox";
 import Ajv from "ajv";
 
-const PerformerSchema = Type.Object({
+const FeaturedPersonSchema = Type.Object({
   name: Type.String(),
   type: Type.Optional(Type.String()),
   genre: Type.Optional(Type.String()),
@@ -33,7 +33,7 @@ const EventSchema = Type.Object({
 });
 
 export const ResearchPayloadSchema = Type.Object({
-  performers: Type.Optional(Type.Array(PerformerSchema)),
+  featured: Type.Optional(Type.Array(FeaturedPersonSchema)),
   organizer: Type.Optional(OrganizerSchema),
   venue: Type.Optional(VenueSchema),
   event: Type.Optional(EventSchema),
@@ -46,6 +46,11 @@ const ajv = new Ajv({ allErrors: true });
 const validate = ajv.compile(ResearchPayloadSchema);
 
 export function validateResearchPayload(data: unknown): ResearchPayload {
+  // Backward compat: accept legacy "performers" key as "featured"
+  if (data && typeof data === "object" && "performers" in data && !("featured" in data)) {
+    const { performers, ...rest } = data as Record<string, unknown>;
+    data = { ...rest, featured: performers };
+  }
   if (validate(data)) {
     return data;
   }
@@ -55,7 +60,7 @@ export function validateResearchPayload(data: unknown): ResearchPayload {
 
 export function generateResearchSkeleton(): ResearchPayload {
   return {
-    performers: [
+    featured: [
       {
         name: "DJ Nobu",
         type: "DJ",
@@ -91,9 +96,9 @@ export function generateResearchSkeleton(): ResearchPayload {
       context: "Amsterdam-based collective, running events since 2007. Annual festival + club nights.",
     },
     venue: {
-      name: "Shelter Amsterdam",
+      name: "Shelter",
       city: "Amsterdam",
-      google_place_id: "",
+      google_place_id: "ChIJX8_place_id_example",
       context: "Underground club beneath A'DAM Tower, 350 capacity, one room, Funktion-One sound.",
     },
     event: {
@@ -138,8 +143,8 @@ export function mapResearchToUploadFields(
 export function stitchResearchContext(payload: ResearchPayload): string {
   const sections: string[] = [];
 
-  if (payload.performers?.length) {
-    const lines = payload.performers.map((p) => {
+  if (payload.featured?.length) {
+    const lines = payload.featured.map((p) => {
       const parts = [`- ${p.name}`];
       const attrs: string[] = [];
       if (p.type) attrs.push(p.type);
@@ -149,7 +154,7 @@ export function stitchResearchContext(payload: ResearchPayload): string {
       if (p.context) parts.push(`  ${p.context}`);
       return parts.join("\n");
     });
-    sections.push(`## Performers\n${lines.join("\n")}`);
+    sections.push(`## Featured\n${lines.join("\n")}`);
   }
 
   if (payload.organizer?.name) {