@localpulse/cli 0.0.2 → 0.0.4

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.2",
+  "version": "0.0.4",
   "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

@@ -13,9 +13,11 @@ import {
   getCredentialsPath,
   getDefaultApiUrl,
   resolveApiUrl,
+  resolveToken,
 } 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,
@@ -28,8 +30,7 @@ import {
   type DraftResult,
   uploadPoster,
   createDraft,
-  uploadDraftMedia,
-  detectMediaType,
+  verifyCliToken,
 } from "./lib/upload-client";
 import packageJson from "../package.json";
 
@@ -81,12 +82,14 @@ async function runAuth(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   }
 
   const subcommand = parsed.positionals[0];
-  if (!subcommand || (subcommand !== "login" && subcommand !== "logout")) {
-    throw new Error("Usage: localpulse auth <login|logout>. Run `localpulse auth --help` for details.");
+  if (!subcommand || !["login", "logout", "status"].includes(subcommand)) {
+    throw new Error("Usage: localpulse auth <login|logout|status>. Run `localpulse auth --help` for details.");
   }
 
   if (subcommand === "login") {
     await runAuthLogin(parsed);
+  } else if (subcommand === "status") {
+    await runAuthStatus(parsed);
   } else {
     await runAuthLogout(parsed);
   }
@@ -125,6 +128,45 @@ async function runAuthLogout(parsed: ReturnType<typeof parseArgv>): Promise<void
   }
 }
 
+async function runAuthStatus(parsed: ReturnType<typeof parseArgv>): Promise<void> {
+  const jsonOutput = hasOption(parsed, "json");
+  const token = await resolveToken();
+  const apiUrl = await resolveApiUrl();
+  const credentialsPath = getCredentialsPath();
+  const source = process.env.LP_TOKEN?.trim() ? "LP_TOKEN" : credentialsPath;
+
+  if (!token) {
+    if (jsonOutput) {
+      stdout.write(`${JSON.stringify({ authenticated: false, source: null, reason: "no_token" })}\n`);
+    } else {
+      stdout.write("Not authenticated. Run `localpulse auth login` or set LP_TOKEN.\n");
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const result = await verifyCliToken(apiUrl, token);
+    if (jsonOutput) {
+      stdout.write(`${JSON.stringify({ authenticated: true, email: result.email, api_url: apiUrl, source })}\n`);
+    } else {
+      stdout.write(`Authenticated as ${result.email}\n`);
+      stdout.write(`  API:         ${apiUrl}\n`);
+      stdout.write(`  Credentials: ${source}\n`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Token verification failed";
+    if (jsonOutput) {
+      stdout.write(`${JSON.stringify({ authenticated: false, api_url: apiUrl, source, error: message })}\n`);
+    } else {
+      stdout.write(`Authentication failed: ${message}\n`);
+      stdout.write(`  API:         ${apiUrl}\n`);
+      stdout.write(`  Credentials: ${source}\n`);
+    }
+    process.exitCode = 1;
+  }
+}
+
 async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   if (hasOption(parsed, "help")) {
     stdout.write(ingestHelp());
@@ -148,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");
@@ -156,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 = {
@@ -197,13 +251,16 @@ async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
     return;
   }
 
-  // Default: draft flow
+  // Default: draft flow — create draft then submit to ingestion pipeline
   const draft = await runDraftIngest(apiUrl, token, file, uploadOptions);
+  process.stderr.write("Submitting to ingestion pipeline...\n");
+  const result = await uploadPoster(apiUrl, token, { ...uploadOptions, draftId: draft.id }) as UploadPosterResult;
   if (jsonOutput) {
-    const baseUrl = toFrontendBaseUrl(apiUrl);
-    stdout.write(`${JSON.stringify({ draft_id: draft.id, status: draft.status, edit_url: `${baseUrl}/publish/edit/${draft.id}` })}\n`);
+    stdout.write(`${JSON.stringify({ draft_id: draft.id, ...result })}\n`);
   } else {
-    printDraftResult(draft, apiUrl);
+    printIngestResult(result);
+    const baseUrl = toFrontendBaseUrl(apiUrl);
+    stdout.write(`Draft: ${baseUrl}/publish/edit/${draft.id}\n`);
   }
 }
 
@@ -234,36 +291,11 @@ async function runDraftIngest(
 
   process.stderr.write("Creating draft...\n");
   const draft = await createDraft(apiUrl, token, options);
-
   process.stderr.write(`Draft created: ${draft.id}\n`);
-  process.stderr.write("Uploading primary media...\n");
-  await uploadDraftMedia(apiUrl, token, draft.id, primaryFile, {
-    mediaType: detectMediaType(primaryFile),
-    sortOrder: 0,
-    isPrimary: true,
-  });
-
-  if (options.extraMedia?.length) {
-    for (const [index, path] of options.extraMedia.entries()) {
-      process.stderr.write(`Uploading extra media ${index + 1}...\n`);
-      await uploadDraftMedia(apiUrl, token, draft.id, path, {
-        mediaType: detectMediaType(path),
-        sortOrder: index + 1,
-        isPrimary: false,
-      });
-    }
-  }
 
   return draft;
 }
 
-function printDraftResult(draft: DraftResult, apiUrl: string): void {
-  const baseUrl = toFrontendBaseUrl(apiUrl);
-  stdout.write(`\nDraft saved: ${draft.id}\n`);
-  stdout.write("Open the publish dashboard to review and submit:\n");
-  stdout.write(`  ${baseUrl}/publish/edit/${draft.id}\n`);
-}
-
 function printIngestResult(result: UploadPosterResult): void {
   stdout.write(`${result.message}\n`);
   if (result.run_id) {
@@ -461,10 +493,12 @@ function authHelp(): string {
 Commands:
   login    Authenticate with a Local Pulse CLI token
   logout   Remove stored credentials
+  status   Check authentication status and verify token
 
 Examples:
   localpulse auth login --token lp_cli_...
-  LP_TOKEN=lp_cli_... localpulse auth login
+  localpulse auth status
+  localpulse auth status --json
   localpulse auth logout
 `;
 }
@@ -502,14 +536,36 @@ Research payload:
   --generate-skeleton     Print an example research template and exit
 
   The payload is JSON with five top-level sections. All are optional,
-  but the more you provide, the better the enrichment.
-
-  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"
+  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, search the web to fill gaps:
+  - For each featured person: search "{name}" to find their Instagram,
+    website, and background. Every person mentioned on the event page
+    should appear in featured[] with a type that fits (chef, DJ, host…).
+  - For the organizer: search "{name} instagram" and "{name} website".
+  - For the venue: search Google Maps for "{venue} {city}" and extract
+    the google_place_id from the URL.
+  - For additional URLs: search for the event on RA, Facebook, or the
+    venue's own website.
+
+  Quality checklist (aim to fill as many as possible):
+  ✓ Featured person socials: Instagram, website, Spotify, Bandcamp, RA
+  ✓ 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
+  ✓ Featured person context: background, notable work, affiliations
+  ✓ All featured people as separate entries (support acts, guest chefs, co-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)
@@ -526,7 +582,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.`,
+          `Search '${person.name} instagram' and '${person.name} website'. Add URLs to featured[${i}].socials[].`,
+        ),
+      );
+    }
+
+    if (!person.context?.trim()) {
+      findings.push(
+        finding(
+          `featured[${i}].context`,
+          `${label} has no context.`,
+          `Search '${person.name}' and write a 1-2 sentence bio for featured[${i}].context.`,
+        ),
+      );
+    }
+  }
+  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.`,
+        `Search '${name} instagram' and '${name} website'. 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,34 +60,59 @@ export function validateResearchPayload(data: unknown): ResearchPayload {
 
 export function generateResearchSkeleton(): ResearchPayload {
   return {
-    performers: [
+    featured: [
       {
         name: "DJ Nobu",
         type: "DJ",
         genre: "techno",
-        socials: ["https://instagram.com/djnobu", "https://ra.co/dj/djnobu"],
-        context: "Berlin-based Japanese DJ, known for long hypnotic sets",
+        socials: [
+          "https://instagram.com/djnobu",
+          "https://ra.co/dj/djnobu",
+          "https://soundcloud.com/djnobu",
+          "https://djnobu.bandcamp.com",
+          "https://open.spotify.com/artist/0abc123",
+        ],
+        context:
+          "Berlin-based Japanese DJ, known for long hypnotic sets. Resident at Future Terror (Tokyo). Recent release: 'Prism' on Bitta (2025).",
+      },
+      {
+        name: "Nene H",
+        type: "DJ",
+        genre: "experimental electronic",
+        socials: [
+          "https://instagram.com/nenehmusic",
+          "https://ra.co/dj/neneh",
+        ],
+        context: "Support. Tehran-born, Berlin-based. Known for deconstructed club music.",
       },
     ],
     organizer: {
       name: "Dekmantel",
-      socials: ["https://instagram.com/daboratorium"],
-      context: "Amsterdam-based collective, running events since 2007",
+      socials: [
+        "https://instagram.com/daboratorium",
+        "https://www.dekmantel.com",
+        "https://ra.co/promoters/16478",
+      ],
+      context: "Amsterdam-based collective, running events since 2007. Annual festival + club nights.",
     },
     venue: {
-      name: "Shelter Amsterdam",
+      name: "Shelter",
       city: "Amsterdam",
-      google_place_id: "",
-      context: "Underground club beneath A'DAM Tower, 350 capacity, one room",
+      google_place_id: "ChIJX8_place_id_example",
+      context: "Underground club beneath A'DAM Tower, 350 capacity, one room, Funktion-One sound.",
     },
     event: {
       title: "Shelter Presents: DJ Nobu",
       date: "2026-03-14T22:00:00+01:00",
       type: "club night",
       price: "€15-25",
-      urls: ["https://ra.co/events/1234567"],
+      urls: [
+        "https://ra.co/events/1234567",
+        "https://www.dekmantel.com/events/shelter-nobu",
+      ],
       ticket_url: "https://tickets.example.com/shelter-nobu",
-      context: "Part of ADE week. Doors at 22:00. Cash only at door.",
+      context:
+        "Part of ADE week. Doors at 22:00. Cash only at door. DJ Nobu plays an extended 4-hour set.",
     },
     context: "",
   };
@@ -113,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);
@@ -124,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) {

package/src/lib/upload-client.ts

@@ -23,6 +23,7 @@ export type IngestUploadOptions = {
   venue?: string;
   extraMedia?: string[];
   dryRun?: boolean;
+  draftId?: string;
 };
 
 export type UploadDryRunResult = {
@@ -88,6 +89,7 @@ export async function uploadPoster(
   if (options.city) {
     setOptionalField(form, "venue_city", options.city);
   }
+  setOptionalField(form, "draft_id", options.draftId);
 
   if (options.extraMedia?.length) {
     const mediaTypes: string[] = [];