tablefacts 0.1.0 → 0.2.0

package/src/menu/lib/tables.mjs

@@ -0,0 +1,44 @@
+// The table names a menu import writes. Several restaurants can share one
+// Supabase database, so each restaurant's tables carry its own prefix
+// (`cannario_menu_categories`, `makibar_menu_categories`, ...). The prefix is
+// restaurant-specific and lives in the source's `config.mjs`; the CLI's
+// `--table-prefix` overrides it for one run.
+import { optionError } from "../../lib/errors.mjs";
+
+// The only prefixes accepted: empty, or lowercase letters, digits and
+// underscores ending in "_". A value that passed this allow-list is safe to
+// build the table names from; nothing else is ever put into the SQL text.
+const PREFIX = /^[a-z][a-z0-9_]*_$|^$/;
+
+/**
+ * `tablePrefix` when it is empty or a safe `<name>_` prefix (an ECONFIG error otherwise).
+ * @param {string} [tablePrefix]
+ * @returns {string}
+ */
+export function validateTablePrefix(tablePrefix) {
+  const value = tablePrefix ?? "";
+  if (!PREFIX.test(value)) {
+    throw optionError(
+      "tablePrefix",
+      `${JSON.stringify(value)} is not a valid table prefix: \`tablePrefix\` must be empty or lowercase letters, digits and underscores ending in "_", such as "makibar_".`,
+      "ECONFIG",
+    );
+  }
+  return value;
+}
+
+/**
+ * The three `public` menu tables for a prefix, e.g.
+ * `{ categories: "public.makibar_menu_categories", sections: "public.makibar_menu_sections", products: "public.makibar_menu_products" }`.
+ * The default (empty prefix) is the unprefixed `public.menu_*` set.
+ * @param {string} [tablePrefix]
+ * @returns {{ categories: string, sections: string, products: string }}
+ */
+export function menuTables(tablePrefix) {
+  const prefix = validateTablePrefix(tablePrefix);
+  return {
+    categories: `public.${prefix}menu_categories`,
+    sections: `public.${prefix}menu_sections`,
+    products: `public.${prefix}menu_products`,
+  };
+}

package/src/menu/raw/config.mjs

@@ -1,6 +1,12 @@
 // Everything restaurant-specific about the image-menu import. Edit this file,
 // not the other scripts, when the menu is organised differently.
 export default {
+  // This restaurant's tables in a shared Supabase database: the import writes
+  // public.mombasa_menu_categories / _menu_sections / _menu_products. Change
+  // it (or pass `--table-prefix`) when importing another restaurant; leave it
+  // empty only when this restaurant owns the unprefixed menu_* tables.
+  tablePrefix: "mombasa_",
+
   // The page that shows the menu pictures, or direct image URLs.
   // `tablefacts menu raw <url> [<url>...]` overrides it for one run.
   url: "https://www.mombasa.co/carta-restaurante-espanol/",

package/src/menu/raw/import.mjs

@@ -85,6 +85,8 @@ export async function fetchImageMenu({ urls = [], only, provider, model, minWidt
     menu,
     notes,
     title: `Image menu: ${chosen.length} pages from ${host} (${reading} read with ${providers[provider].label} ${model}, ${chosen.length - reading} from the saved transcriptions), prices in ${currency}`,
+    // The restaurant's own table set, so a shared database is never touched by accident.
+    tablePrefix: config.tablePrefix,
   };
 }
 
@@ -93,7 +95,8 @@ export async function fetchImageMenu({ urls = [], only, provider, model, minWidt
  * @param {import('../../lib/types.mjs').ImportImageMenuOptions} [options]
  * @returns {Promise<import('../../lib/types.mjs').ImportResult>}
  */
-export async function importImageMenu({ urls, only, provider, model, minWidth, refresh, apiKey, env, config, ...importOptions } = {}) {
+export async function importImageMenu({ urls, only, provider, model, minWidth, refresh, apiKey, env, config = defaultConfig, ...importOptions } = {}) {
   const fetched = await fetchImageMenu({ urls, only, provider, model, minWidth, refresh, apiKey, env, config, projectDir: importOptions.projectDir, log: importOptions.log });
-  return importMenu({ ...fetched, ...importOptions, env });
+  // An explicit `tablePrefix` (or the CLI's --table-prefix) wins over the config's.
+  return importMenu({ ...fetched, ...importOptions, tablePrefix: importOptions.tablePrefix ?? config.tablePrefix, env });
 }

package/src/research/README.md

@@ -28,42 +28,52 @@ see the [main README](../../README.md#use-it-as-a-library). `out` (relative path
 | --- | --- | --- |
 | Google Maps (Places API) | address, map point, phone, hours, price, cuisine types, photos, status | Needs `GOOGLE_PLACES_API_KEY` in `.env` (Places API (New) enabled). Phone and hours fields are billed at the Enterprise rate; one search per run |
 | OpenStreetMap (Nominatim) | address, map point, sometimes phone, hours, website, socials | No key. Often stale or sparse |
+| Web search (DuckDuckGo) | candidate website, Instagram, TripAdvisor, Maps and hub links | No key. Runs only when Google and OpenStreetMap find no place or no website, so the reported "name-only finds nothing" case now has a fallback |
 | Website | JSON-LD, contact page, WhatsApp, reserve platform, menu links, images, logo, theme colour, page text | Falls back to Playwright on 403 or client-rendered pages (`--render` forces it) |
-| Instagram | handle, followers, bio, bio link | Public share card only. Usually login-walled |
-| TripAdvisor | JSON-LD (address, phone, cuisine, price, rating) | Usually bot-blocked: the link is kept for a manual read |
+| Instagram | handle, followers, bio, bio link | Tries the public share card, the web profile API, oEmbed and finally a search-engine snippet of the bio. Requests identify honestly and never log in; often all surfaces are walled |
+| TripAdvisor | JSON-LD (address, phone, cuisine, price, rating) | Usually bot-blocked. Playwright is tried on a 403 or a thin page like any website, but DataDome still wins. The name and city are read from the URL slug without fetching, and the link is kept for a manual read (stated at the top of the report) |
 | Linktree and similar | WhatsApp, reserve, menu, delivery links | Found from the website, Instagram bio or `--linktree` |
 
-Sources find each other (website → Instagram, TripAdvisor, hub). Order of trust per field is in `lib/merge.mjs`; two sources agreeing is "high", one is "medium", a guess is "low".
+Sources find each other (web search or website → Instagram, TripAdvisor, hub). Order of trust per field is in `lib/merge.mjs`; two sources agreeing is "high", one is "medium", a guess is "low".
 
 ## How it runs
 
 - **Concurrent lookups.** Google and OpenStreetMap run together; then the website is read. Instagram, TripAdvisor and
-  the link-in-bio page start as soon as their address is known (given, or found on the website), so a slow source does
-  not hold up the others. Report notes keep a fixed order whatever finishes first. Photo downloads run four at a time.
+  the link-in-bio page start as soon as their address is known (given, or found on the website or web search), so a slow
+  source does not hold up the others. Report notes keep a fixed order whatever finishes first. Photo downloads run four at a time.
+- **Web-search fallback.** When Google and OpenStreetMap find no place or no website, a key-free DuckDuckGo query
+  runs and its candidate links feed the rest of the pipeline. It is one extra request, only when it is needed.
 - **One shared browser.** Playwright's Chromium is launched at most once per run, only when a page needs rendering
   (`--render`, a 403, a client-rendered page), is shared by the website, TripAdvisor and link-in-bio readers, and is
   closed at the end even on failure.
 - **Fetch cap.** Pages are read up to 2 MB each; larger bodies are truncated, so a huge page cannot exhaust memory.
 
+## Runs and re-runs
+
+Output goes to `.tablefacts/research/<slug>/`; two spellings of the same name ("Makibar" and "Maki Bar") make two
+folders. A similar-name run is noted in the report, and `.tablefacts/research/latest.json` always points at the newest
+report, so reading every folder cannot resurface a stale one.
+
 ## Limits
 
 - It does not log in anywhere or get past bot protection. A blocked source is reported, not worked around.
 - It finds facts, not copy, logos or licensed photos.
-- A wrong match (a sister branch, a closed place) is the main risk: read the Warnings and "Sources disagree" first.
+- A wrong match (a sister branch, a closed place) is the main risk: read the Warnings and "Sources disagree" first. When Google returns several places with the same name, the report says so and asks which branch.
+- Only public surfaces are tried for Instagram/TripAdvisor. When they are walled, the report keeps the link and says so at the top; it does not defeat the wall.
 
 ## For agents
 
-Use it first, whenever you are given only a restaurant's name and place (or little else).
+Use it first, whenever you are given only a restaurant's name and place (or little else). If Google and OpenStreetMap find no place or no website, a key-free web search runs automatically, so a name-only call is no longer an empty report.
 
-1. **Run it** from the repo root: `tablefacts research "<name>" "<city, country>" --country <ISO>`. Add `--website`, `--instagram`, `--tripadvisor` or `--linktree` for anything the user gave you; a user-supplied value is trusted over a search result. It takes under a minute, needs no prompts and prints the output folder.
-2. **Read `out/<slug>/report.md`**, in this order: Warnings, "What each source did", Facts, "Sources disagree". Confirm the match is the right restaurant (name, address, not closed) before using anything. If it matched the wrong place, rerun with a more specific location or `--website`.
+1. **Run it** from the repo root: `tablefacts research "<name>" "<city, country>" --country <ISO>`. Add `--website`, `--instagram`, `--tripadvisor` or `--linktree` for anything the user gave you; a user-supplied value is trusted over a search result. Uploading a Google Maps link as `--website` (or pasting it in the report as `mapsUrl`) unlocks coordinates; ask for it first when the report is thin. It takes under a minute, needs no prompts and prints the output folder.
+2. **Read `out/<slug>/report.md`**, in this order: the kept-links notice and Warnings, "What each source did", Facts, "Sources disagree", "Ask the client". Confirm the match is the right restaurant (name, address, not closed) before using anything. If it matched the wrong place, rerun with a more specific location or `--website`.
 3. **Treat every value as unconfirmed.** Fill `BRIEF.md` with the value and its source, never as client-confirmed. Anything under "not found" stays a placeholder and goes in your hand-off as an open question. Do not invent it.
-4. **Apply the facts**: review `setup-answers.txt`, run `npm run setup < .tablefacts/research/<slug>/setup-answers.txt`, read `git diff`. Setup does not cover `phone`, `email`, `MENU_LOCALE`, `brand.tagline`, `visit.hoursRows` or `jsonld.ts`: take those from the report by hand. Hours are ready to paste. Add street, phone and hours to `jsonld.ts` only for values the client confirmed.
+4. **Apply the facts**: review `setup-answers.txt`, run `npm run setup < .tablefacts/research/<slug>/setup-answers.txt`, read `git diff`. A low-confidence guess (marked "low (guess)") is left blank so setup keeps the template's placeholder; it is never written in as a fact. Setup does not cover `phone`, `email`, `MENU_LOCALE`, `brand.tagline`, `visit.hoursRows` or `jsonld.ts`: take those from the report by hand. Hours are ready to paste. Add street, phone and hours to `jsonld.ts` only for values the client confirmed.
 5. **Use the leads**: a Cluvi menu link means `tablefacts menu cluvi`, a PDF means `tablefacts menu raw` (`src/menu/README.md`). The theme colour and logo candidates are hints for `tokens.css` and `public/logo.svg`, not decisions.
-6. **Blocked sources** (Instagram, TripAdvisor) are normal. Open the link yourself, or ask the user for the bio and hours. Do not try to get around a login wall.
+6. **Blocked sources** (Instagram, TripAdvisor) are normal. The top of the report names any link that was kept unread; open it yourself, or ask the user for the bio and hours. Do not try to get around a login wall. `.tablefacts/research/latest.json` points at the newest run when the same place was researched under a different spelling.
 
-`profile.json` has the same data as JSON for scripting: `fields.<name>` is `{ value, source, confidence, alternatives? }`, `hours.rows.{es,en}` are `hoursRows`, and `raw` holds each source's untouched result. Field names: `name street locality region country coordinates phone whatsapp email instagram facebook tiktok tripadvisor website reserveUrl priceRange mapsUrl descriptor cuisines menuLocale`.
+`profile.json` has the same data as JSON for scripting: `fields.<name>` is `{ value, source, confidence, alternatives? }`, `hours.rows.{es,en}` are `hoursRows`, and `raw` holds each source's untouched result (including `search`). Field names: `name street locality region country coordinates phone whatsapp email instagram facebook tiktok tripadvisor website reserveUrl priceRange mapsUrl descriptor cuisines menuLocale`.
 
 Do not commit `out/`, and never paste the Google key anywhere but `.env`. Photos it downloads belong to the restaurant or the photographer: use them as reference, not as site assets.
 
-Code map: `research.mjs` runs the sources in order and writes the files; `lib/google.mjs`, `osm.mjs`, `website.mjs`, `social.mjs` read one source each; `merge.mjs` holds the per-field trust order; `hours.mjs` normalises hours; `report.mjs` writes the report and the setup answers. A new source is a reader returning plain data, a line in `research.mjs` and its candidates in `merge.mjs`.
+Code map: `research.mjs` runs the sources in order and writes the files; `lib/google.mjs`, `osm.mjs`, `search.mjs`, `website.mjs`, `social.mjs` read one source each; `merge.mjs` holds the per-field trust order; `hours.mjs` normalises hours; `report.mjs` writes the report and the setup answers. A new source is a reader returning plain data, a line in `research.mjs` and its candidates in `merge.mjs`.

package/src/research/index.mjs

@@ -1,8 +1,8 @@
 // Programmatic entry for the research pipeline: gathers what the public web says
 // about a restaurant and writes profile.json, report.md and setup-answers.txt.
 // Silent by default and never exits the process; the CLI lives in research.mjs.
-import { mkdir, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
 import { resolveEnv } from "../lib/env.mjs";
 import { optionError } from "../lib/errors.mjs";
 import { normalizeLog } from "../lib/log.mjs";
@@ -11,8 +11,9 @@ import { downloadPhotos, searchGoogle } from "./lib/google.mjs";
 import { buildProfile } from "./lib/merge.mjs";
 import { searchOsm } from "./lib/osm.mjs";
 import { renderReport, setupAnswers } from "./lib/report.mjs";
+import { searchWeb } from "./lib/search.mjs";
 import { readHub, readInstagram, readTripadvisor } from "./lib/social.mjs";
-import { mapPool, slugify } from "./lib/util.mjs";
+import { mapPool, sameText, slugify } from "./lib/util.mjs";
 import { createBrowser, scrapeSite } from "./lib/website.mjs";
 
 /**
@@ -31,6 +32,7 @@ export async function research(options = {}) {
 
   const slug = slugify(name);
   const outDir = options.out ? resolveIn(options.projectDir, options.out) : workDirIn(options.projectDir, "research", slug);
+  const researchDir = dirname(outDir);
   const query = { name, location, slug, country, website, instagram: instagramOpt, tripadvisor: tripadvisorOpt, linktree };
   const notes = [];
 
@@ -50,7 +52,7 @@ export async function research(options = {}) {
 
   // One Chromium for the whole run, launched only if a page needs rendering.
   const browser = createBrowser();
-  let site, instagram, hub, tripadvisor, taUrl, handle, google, osm;
+  let site, instagram, hub, tripadvisor, taUrl, handle, google, osm, search, branches = [];
   try {
     // Google and OpenStreetMap only need the name and place, so they run together; their notes are added in this order afterwards.
     const googleNotes = [];
@@ -65,20 +67,33 @@ export async function research(options = {}) {
     notes.push(...googleNotes, ...osmNotes);
     google = googleResult?.place ?? null;
     osm = osmResult?.place ?? null;
+    // Several Google places with the same name are likely branches of one chain; the template assumes one address.
+    branches = (googleResult?.candidates ?? []).filter((c) => sameText(c.name, name));
 
-    const websiteUrl = website ?? google?.website ?? osm?.website;
+    // No website yet: a key-free web search turns a bare name + place into candidate links.
+    if (!website && !google?.website && !osm?.website) {
+      search = await source("Web search", () => searchWeb({ name, location }));
+      if (search) {
+        const found = search.candidates.length ? ` (${search.candidates.slice(0, 2).map((c) => c.title || c.url).join(", ")})` : "";
+        notes.push(`Web search: ${search.results.length ? `${search.results.length} result(s) for "${search.query}"${found}` : `no results for "${search.query}"`}`);
+      }
+    }
+
+    const websiteUrl = website ?? google?.website ?? osm?.website ?? search?.website;
     site = websiteUrl ? await source("Website", () => scrapeSite(websiteUrl, { renderJs: render, browser })) : null;
-    if (site) notes.push(`Website: read ${site.pages.length} page(s) of ${site.url}${site.pages.some((p) => p.rendered) ? " (rendered with Playwright)" : ""}`);
+    if (site) notes.push(`Website: read ${site.pages.length} page(s) of ${site.url}${site.pages.some((p) => p.rendered) ? " (rendered with Playwright)" : ""}${!website && !google?.website && !osm?.website ? " (found by web search)" : ""}`);
     else if (!websiteUrl) notes.push("Website: none found. Pass the website (--website / `website`) if the restaurant has one.");
 
     // Follow the leads the first sources gave. What is already known (handle, TripAdvisor link, hub link)
     // starts right away; the rest waits only for the source that can supply it.
-    handle = (instagramOpt ?? site?.links.instagram[0] ?? osm?.instagram ?? "").replace(/^https?:\/\/(www\.)?instagram\.com\//i, "").replace(/^@/, "").split(/[/?#]/)[0];
-    taUrl = tripadvisorOpt ?? site?.links.tripadvisor[0] ?? (site?.jsonld?.sameAs ?? []).find((u) => /tripadvisor\./.test(u));
-    const directHubUrl = linktree ?? site?.links.hubs[0];
+    handle = (instagramOpt ?? site?.links.instagram[0] ?? osm?.instagram ?? search?.instagram ?? "").replace(/^https?:\/\/(www\.)?instagram\.com\//i, "").replace(/^@/, "").split(/[/?#]/)[0];
+    taUrl = tripadvisorOpt ?? site?.links.tripadvisor[0] ?? (site?.jsonld?.sameAs ?? []).find((u) => /tripadvisor\./.test(u)) ?? search?.tripadvisor;
+    const directHubUrl = linktree ?? site?.links.hubs[0] ?? search?.hubs?.[0];
     const readHubAt = (url) => source("Link-in-bio", () => readHub(url, { browser }));
 
-    const instagramP = handle ? source("Instagram", () => readInstagram(handle)) : null;
+    // The search snippet for the profile is a last resort when Instagram walls the bio.
+    const igSnippet = search?.results?.find((r) => /instagram\.com\//i.test(r.url) && r.url.toLowerCase().includes(`/${handle.toLowerCase()}`))?.snippet ?? "";
+    const instagramP = handle ? source("Instagram", () => readInstagram(handle, { snippet: igSnippet })) : null;
     const tripadvisorP = taUrl ? source("TripAdvisor", () => readTripadvisor(taUrl, { browser })) : null;
     // The hub URL comes from the options or the website, else from the Instagram bio.
     const hubTask = (async () => {
@@ -103,17 +118,27 @@ export async function research(options = {}) {
     }
 
     // Notes keep the order of the sequential flow: Instagram, link-in-bio, TripAdvisor.
-    if (instagram) notes.push(instagram.blocked ? `Instagram @${handle}: not readable (${instagram.blocked}). Add the bio by hand, or use \`tablefacts photos instagram\` for posts.` : `Instagram @${handle}: profile card read`);
+    if (instagram) notes.push(instagram.blocked ? `Instagram @${handle}: not readable (${instagram.blocked}). Add the bio by hand, or use \`tablefacts photos instagram\` for posts.` : `Instagram @${handle}: profile read (${instagram.surface ?? "share card"})`);
     else if (!handle) notes.push("Instagram: no handle found. Pass the handle (--instagram / `instagram`).");
     if (hub) notes.push(hub.blocked ? `Link-in-bio ${hubUrl}: not readable (${hub.blocked})` : `Link-in-bio: read ${hub.url}`);
-    if (tripadvisor) notes.push(tripadvisor.blocked ? `TripAdvisor ${taUrl}: blocked (${tripadvisor.blocked}). The link is kept; read it by hand.` : "TripAdvisor: page read");
-    else notes.push("TripAdvisor: no link found. Pass the page (--tripadvisor / `tripadvisor`).");
+    if (tripadvisor) {
+      // The URL slug is a hint the source kept for a manual read; it never becomes a field on its own.
+      const hint = tripadvisor.slug ? ` URL suggests "${tripadvisor.slug.name}"${tripadvisor.slug.location ? `, ${tripadvisor.slug.location}` : ""}.` : "";
+      notes.push(tripadvisor.blocked ? `TripAdvisor ${taUrl}: blocked (${tripadvisor.blocked}). The link is kept; read it by hand.${hint}` : "TripAdvisor: page read");
+    } else notes.push("TripAdvisor: no link found. Pass the page (--tripadvisor / `tripadvisor`).");
   } finally {
     await browser.close();
   }
 
-  const profile = buildProfile({ query, google, osm, site, hub: hub?.blocked ? null : hub, instagram, tripadvisor: tripadvisor?.blocked ? null : tripadvisor });
-  if (tripadvisor?.blocked && taUrl && !profile.fields.tripadvisor) profile.fields.tripadvisor = { value: taUrl, source: "website", confidence: "medium" };
+  const profile = buildProfile({ query, google, osm, site, hub: hub?.blocked ? null : hub, instagram, tripadvisor, search });
+  const taOrigin = tripadvisorOpt ? "you" : (hub?.links?.tripadvisor ?? []).includes(taUrl) ? "link-in-bio" : search?.tripadvisor === taUrl ? "search" : "website";
+  if (tripadvisor?.blocked && taUrl && !profile.fields.tripadvisor) profile.fields.tripadvisor = { value: taUrl, source: taOrigin, confidence: "medium" };
+  if (branches.length > 1) profile.warnings.push(`Google returns ${branches.length} places named like "${name}" (${branches.map((b) => b.address).filter(Boolean).join("; ")}). This looks like a chain: confirm which branch this site is for.`);
+
+  // A link a source could not read is stated at the top of the report, not only in the source list.
+  const kept = [];
+  if (tripadvisor?.blocked && taUrl) kept.push({ label: "TripAdvisor", url: taUrl, reason: tripadvisor.blocked });
+  if (instagram?.blocked && handle) kept.push({ label: `Instagram @${handle}`, url: `https://www.instagram.com/${handle}/`, reason: instagram.blocked });
 
   // Optional photo downloads: reference material, never wired into the site.
   const photos = [];
@@ -137,11 +162,21 @@ export async function research(options = {}) {
     photos.push(...saved.filter(Boolean));
   }
 
+  // Two names for one place ("Makibar" and "Maki Bar") used to make two folders, and reading them all showed
+  // a stale report. Note the sibling run and keep a pointer to the newest, so the last run is the one to read.
+  const loose = slug.replace(/-/g, "");
+  const siblings = options.out ? [] : await readdir(researchDir, { withFileTypes: true })
+    .then((entries) => entries.filter((e) => e.isDirectory() && e.name.replace(/-/g, "") === loose && join(researchDir, e.name) !== outDir).map((e) => e.name))
+    .catch(() => []);
+  if (siblings.length) notes.push(`Other runs with a similar name exist (${siblings.join(", ")}); \`latest.json\` points at the newest. Older folders may be stale.`);
+
   const files = { profile: resolve(outDir, "profile.json"), report: resolve(outDir, "report.md"), setupAnswers: resolve(outDir, "setup-answers.txt") };
   await mkdir(outDir, { recursive: true });
-  await writeFile(files.profile, JSON.stringify({ ...profile, raw: { google, osm, site, hub, instagram, tripadvisor }, photos }, null, 2));
-  await writeFile(files.report, renderReport(profile, { notes, photos }));
+  await writeFile(files.profile, JSON.stringify({ ...profile, raw: { google, osm, site, hub, instagram, tripadvisor, search }, photos }, null, 2));
+  await writeFile(files.report, renderReport(profile, { notes, photos, kept }));
   await writeFile(files.setupAnswers, setupAnswers(profile));
+  // Only the default layout gets the "newest" pointer; a custom --out is the caller's own tree.
+  if (!options.out) await writeFile(join(researchDir, "latest.json"), JSON.stringify({ slug, name, location, generatedAt: profile.generatedAt, outDir, report: files.report }, null, 2));
 
   return { profile, notes, photos, outDir, files };
 }

package/src/research/lib/merge.mjs

@@ -35,11 +35,12 @@ const cleanUrl = (u) => {
   } catch { return u; }
 };
 
-export function buildProfile({ query, google, osm, site, hub, instagram, tripadvisor }) {
+export function buildProfile({ query, google, osm, site, hub, instagram, tripadvisor, search }) {
   const g = google ?? {};
   const o = osm ?? {};
   const ld = site?.jsonld ?? null;
   const ta = tripadvisor?.jsonld ?? null;
+  const taSlug = tripadvisor?.slug ?? null;
   const warnings = [];
   const ok = (v) => (v ? v : undefined);
   const hubLinks = hub?.links ?? {};
@@ -54,7 +55,7 @@ export function buildProfile({ query, google, osm, site, hub, instagram, tripadv
   const igLinks = [...(site?.links?.instagram ?? []), ...(hubLinks.instagram ?? [])];
 
   const fields = {
-    name: choose([{ value: g.name, source: "google" }, { value: ld?.name, source: "website" }, { value: ta?.name, source: "tripadvisor" }, { value: o.name, source: "osm" }, { value: site?.meta.siteName, source: "website" }], sameText),
+    name: choose([{ value: g.name, source: "google" }, { value: ld?.name, source: "website" }, { value: ta?.name, source: "tripadvisor" }, { value: o.name, source: "osm" }, { value: site?.meta.siteName, source: "website" }, { value: taSlug?.name, source: "tripadvisor (URL)", low: true }], sameText),
     street: choose([{ value: g.street, source: "google" }, { value: ld?.address.street, source: "website" }, { value: ta?.address.street, source: "tripadvisor" }, { value: o.street, source: "osm" }], sameText),
     locality: choose([{ value: g.locality, source: "google" }, { value: ld?.address.locality, source: "website" }, { value: o.locality, source: "osm" }], sameText),
     region: choose([{ value: g.region, source: "google" }, { value: ld?.address.region, source: "website" }, { value: o.region, source: "osm" }], sameText),
@@ -62,14 +63,14 @@ export function buildProfile({ query, google, osm, site, hub, instagram, tripadv
     coordinates: choose([{ value: g.coords, source: "google" }, { value: o.coords, source: "osm" }, { value: ld?.geo, source: "website" }], coordSame),
     phone: choose([{ value: g.phone, source: "google" }, { value: ok(links("tel")[0]), source: "website" }, { value: ld?.telephone, source: "website" }, { value: ta?.telephone, source: "tripadvisor" }, { value: instagram?.phones?.[0], source: "instagram" }, { value: o.phone, source: "osm" }], phoneSame),
     email: choose([{ value: ld?.email, source: "website" }, { value: links("mail").find((m) => !/sentry|wixpress|example|domain\./i.test(m)), source: "website" }, { value: o.email, source: "osm" }]),
-    instagram: choose([{ value: query.instagram && handleOf(query.instagram), source: "you" }, ...igLinks.map((h) => ({ value: h, source: "website" })), ...(ld?.sameAs ?? []).filter((u) => /instagram\.com/.test(u)).map((u) => ({ value: handleOf(u), source: "website" })), { value: o.instagram && handleOf(o.instagram), source: "osm" }]),
-    facebook: choose([{ value: links("facebook")[0], source: "website" }, { value: o.facebook, source: "osm" }]),
-    tiktok: choose([{ value: links("tiktok")[0], source: "website" }]),
-    tripadvisor: choose([{ value: query.tripadvisor, source: "you" }, { value: links("tripadvisor")[0], source: "website" }, { value: (ld?.sameAs ?? []).find((u) => /tripadvisor\./.test(u)), source: "website" }]),
-    website: choose([{ value: query.website && cleanUrl(query.website), source: "you" }, { value: g.website && cleanUrl(g.website), source: "google" }, { value: o.website && cleanUrl(o.website), source: "osm" }]),
+    instagram: choose([{ value: query.instagram && handleOf(query.instagram), source: "you" }, ...igLinks.map((h) => ({ value: h, source: "website" })), ...(ld?.sameAs ?? []).filter((u) => /instagram\.com/.test(u)).map((u) => ({ value: handleOf(u), source: "website" })), { value: o.instagram && handleOf(o.instagram), source: "osm" }, { value: search?.instagram && handleOf(search.instagram), source: "search" }]),
+    facebook: choose([{ value: links("facebook")[0], source: "website" }, { value: o.facebook, source: "osm" }, { value: search?.facebook && cleanUrl(search.facebook), source: "search" }]),
+    tiktok: choose([{ value: links("tiktok")[0], source: "website" }, { value: search?.tiktok && cleanUrl(search.tiktok), source: "search" }]),
+    tripadvisor: choose([{ value: query.tripadvisor, source: "you" }, { value: links("tripadvisor")[0], source: "website" }, { value: (ld?.sameAs ?? []).find((u) => /tripadvisor\./.test(u)), source: "website" }, { value: search?.tripadvisor && cleanUrl(search.tripadvisor), source: "search" }]),
+    website: choose([{ value: query.website && cleanUrl(query.website), source: "you" }, { value: g.website && cleanUrl(g.website), source: "google" }, { value: o.website && cleanUrl(o.website), source: "osm" }, { value: search?.website && cleanUrl(search.website), source: "search" }]),
     reserveUrl: choose([...links("reserve").map((u) => ({ value: u, source: "website" }))]),
     priceRange: choose([{ value: g.priceRange, source: "google" }, { value: ld?.priceRange, source: "website" }, { value: ta?.priceRange, source: "tripadvisor" }]),
-    mapsUrl: choose([{ value: g.mapsUrl, source: "google" }, { value: links("maps")[0], source: "website" }]),
+    mapsUrl: choose([{ value: g.mapsUrl, source: "google" }, { value: links("maps")[0], source: "website" }, { value: search?.mapsUrl && cleanUrl(search.mapsUrl), source: "search" }]),
     descriptor: choose([{ value: g.descriptor, source: "google" }]),
   };
 
@@ -110,10 +111,10 @@ export function buildProfile({ query, google, osm, site, hub, instagram, tripadv
   return {
     query, generatedAt: new Date().toISOString(), warnings, fields, hours,
     textHours: [...(site?.hoursText ?? [])],
-    links: { menu: links("menu"), delivery: links("delivery"), reserve: links("reserve"), waze: links("waze"), hubs: [...new Set([...(site?.links?.hubs ?? []), ...(instagram?.links ?? []).filter((l) => /linktr|beacons|bio\.link|lnk\.bio|taplink/.test(l))])] },
+    links: { menu: links("menu"), delivery: links("delivery"), reserve: links("reserve"), waze: links("waze"), hubs: [...new Set([...(site?.links?.hubs ?? []), ...(search?.hubs ?? []), ...(instagram?.links ?? []).filter((l) => /linktr|beacons|bio\.link|lnk\.bio|taplink/.test(l))])] },
     ratings: [g.rating && { source: "google", value: g.rating, count: g.ratingCount }, ld?.rating && { source: "website", ...ld.rating }, ta?.rating && { source: "tripadvisor", ...ta.rating }].filter(Boolean),
     images: { logos: [...(site?.logos ?? []), ...(hub?.logos ?? [])].filter((l) => l.url), site: site?.images ?? [], hub: hub?.images ?? [], googlePhotos: g.photos?.length ?? 0, instagramImage: instagram?.image ?? "", themeColor: site?.meta.themeColor ?? "" },
     copySources: { googleSummary: g.summary ?? "", siteDescription: site?.meta.description ?? "", instagramBio: instagram?.bio ?? "", tripadvisor: tripadvisor?.description ?? "", headings: site?.headings ?? [], paragraphs: site?.paragraphs ?? [] },
-    social: { instagram: instagram ? { handle: instagram.handle, followers: instagram.followers, posts: instagram.posts, blocked: instagram.blocked } : null },
+    social: { instagram: instagram ? { handle: instagram.handle, followers: instagram.followers, posts: instagram.posts, blocked: instagram.blocked, partial: instagram.partial, surface: instagram.surface } : null },
   };
 }

package/src/research/lib/report.mjs

@@ -33,17 +33,54 @@ const ROWS = [
 
 const cell = (s) => String(s).replace(/\|/g, "\\|");
 
-export function renderReport(p, { notes, photos }) {
+// Web text lands in a file agents are told to act on: collapse newlines and
+// neutralise backticks so third-party text cannot forge headings or a code fence.
+const flat = (s) => String(s ?? "").replace(/\s+/g, " ").replace(/`/g, "'").trim();
+
+/**
+ * Splits the fields into what was discovered from a source, what was only echoed
+ * back from the user's own input, and low-confidence guesses, so a summary can
+ * say "N facts, M from your input" instead of counting all of them as found.
+ */
+export function fieldSummary(p) {
+  const held = Object.entries(p.fields ?? {}).filter(([, f]) => {
+    const v = f?.value;
+    return v !== undefined && v !== null && v !== "" && !(Array.isArray(v) && !v.length);
+  });
+  const parts = (f) => String(f.source ?? "").split(" + ").map((s) => s.trim()).filter(Boolean);
+  return {
+    discovered: held.filter(([, f]) => f.confidence !== "low" && parts(f).some((s) => s !== "you")).map(([k]) => k),
+    echoed: held.filter(([, f]) => {
+      const sources = parts(f);
+      return f.confidence !== "low" && sources.length > 0 && sources.every((s) => s === "you");
+    }).map(([k]) => k),
+    guessed: held.filter(([, f]) => f.confidence === "low").map(([k]) => k),
+  };
+}
+
+/** The CLI summary: what came from a source, what was only echoed, what was a low guess. */
+export function summaryLines(p) {
+  const { discovered, echoed, guessed } = fieldSummary(p);
+  const list = (a) => (a.length ? a.join(", ") : "none");
+  const lines = [`Found ${discovered.length} fact(s) from sources: ${list(discovered)}`];
+  if (echoed.length) lines.push(`Echoed ${echoed.length} from your input: ${list(echoed)}`);
+  if (guessed.length) lines.push(`Not counted (low-confidence guess): ${list(guessed)}`);
+  return lines;
+}
+
+export function renderReport(p, { notes, photos, kept = [] }) {
   const out = [];
   const q = p.query;
-  out.push(`# Research: ${q.name}${q.location ? `, ${q.location}` : ""}`, "", `Generated ${p.generatedAt}. Everything here is **unconfirmed**: check it with the client and copy the answers into \`BRIEF.md\`. Sources disagree often, and the confidence column says how many agreed.`, "");
+  out.push(`# Research: ${flat(q.name)}${q.location ? `, ${flat(q.location)}` : ""}`, "", `Generated ${p.generatedAt}. Everything here is **unconfirmed**: check it with the client and copy the answers into \`BRIEF.md\`. Sources disagree often, and the confidence column says how many agreed.`, "");
+  for (const k of kept) out.push(`> **Kept for a manual read:** ${k.label} (${k.url}) — could not be read (${k.reason}). Nothing was extracted from it; open it yourself.`, "");
   if (p.warnings.length) out.push("## Warnings", "", ...p.warnings.map((w) => `- ${w}`), "");
   if (notes.length) out.push("## What each source did", "", ...notes.map((n) => `- ${n}`), "");
 
   out.push("## Facts", "", "| Item | Value | Source | Confidence | Goes in |", "| --- | --- | --- | --- | --- |");
   for (const [label, key, goes] of ROWS) {
     const f = p.fields[key];
-    out.push(`| ${label} | ${f ? cell(val(f)) : "_not found_"} | ${f?.source ?? ""} | ${f?.confidence ?? ""} | ${goes} |`);
+    const confidence = f ? (f.confidence === "low" ? "low (guess)" : f.confidence) : "";
+    out.push(`| ${label} | ${f ? cell(val(f)) : "_not found_"} | ${f?.source ?? ""} | ${confidence} | ${goes} |`);
   }
   out.push("");
 
@@ -75,7 +112,12 @@ export function renderReport(p, { notes, photos }) {
   out.push("");
 
   if (p.ratings.length) out.push("## Ratings (context only)", "", ...p.ratings.map((r) => `- ${r.source}: ${r.value}${r.count ? ` (${r.count} reviews)` : ""}`), "");
-  if (p.social.instagram && !p.social.instagram.blocked) out.push(`Instagram @${p.social.instagram.handle}: ${p.social.instagram.followers} followers, ${p.social.instagram.posts} posts.`, "");
+  const ig = p.social.instagram;
+  if (ig && !ig.blocked) {
+    const counts = ig.followers || ig.posts ? `${ig.followers || "?"} followers, ${ig.posts || "?"} posts.` : "";
+    const note = ig.partial ? "Bio from a search snippet (the profile itself was walled)." : counts ? "" : "Profile card read; followers and bio are not public.";
+    out.push(`Instagram @${ig.handle}: ${[counts, note].filter(Boolean).join(" ")}`.trim(), "");
+  }
 
   out.push("## Images", "");
   out.push(`- Website images found: ${p.images.site.length}; link-in-bio: ${p.images.hub.length}; Google photos available: ${p.images.googlePhotos}.`);
@@ -86,13 +128,21 @@ export function renderReport(p, { notes, photos }) {
 
   out.push("## Material for the copy", "", "Facts and tone only. Rewrite it in the template's voice in both languages; do not paste it.", "");
   const c = p.copySources;
-  for (const [label, text] of [["Google summary", c.googleSummary], ["Site description", c.siteDescription], ["Instagram bio", c.instagramBio], ["TripAdvisor", c.tripadvisor]]) if (text) out.push(`- **${label}:** ${text}`);
-  if (c.headings.length) out.push(`- **Site headings:** ${c.headings.slice(0, 12).join(" / ")}`);
-  for (const t of c.paragraphs.slice(0, 6)) out.push(`  - ${t}`);
+  for (const [label, text] of [["Google summary", c.googleSummary], ["Site description", c.siteDescription], ["Instagram bio", c.instagramBio], ["TripAdvisor", c.tripadvisor]]) if (text) out.push(`- **${label}:** ${flat(text)}`);
+  if (c.headings.length) out.push(`- **Site headings:** ${c.headings.slice(0, 12).map(flat).join(" / ")}`);
+  for (const t of c.paragraphs.slice(0, 6)) out.push(`  - ${flat(t)}`);
   out.push("");
 
   const missing = ROWS.filter(([, key]) => !p.fields[key] && ["name", "street", "coordinates", "whatsapp", "instagram", "reserveUrl", "cuisines"].includes(key)).map(([l]) => l);
-  out.push("## Ask the client", "", ...[...missing, "Opening hours incl. holidays", "Logo as SVG and original photos", "The story, signature dishes and events", "Production domain"].filter((v, i, a) => a.indexOf(v) === i && (v !== "Opening hours incl. holidays" || true)).map((m) => `- ${m}`), "");
+  const ask = !p.fields.website && !p.fields.mapsUrl
+    ? "Send the restaurant's website or a Google Maps link — that unlocks the address, map point and place ID."
+    : !p.fields.coordinates
+      ? "A Google Maps link would pin the exact location."
+      : !p.fields.whatsapp
+        ? "Ask for the WhatsApp number taken with reservations, and confirm it accepts messages."
+        : "Ask for the current website and social profiles to cross-check the rest.";
+  const asks = ["Opening hours incl. holidays", "Logo as SVG and original photos", "The story, signature dishes and events", "Production domain"];
+  out.push("## Ask the client", "", `- **Best next question:** ${ask}`, ...[...new Set([...missing, ...asks])].map((m) => `- ${m}`), "");
   out.push("## Next", "", "```bash", `npm run setup < .tablefacts/research/${q.slug}/setup-answers.txt`, "git diff   # review before keeping it", "```", "", "Blank lines in that file keep the template's current value, so anything not found stays a placeholder.", "");
   return out.join("\n");
 }
@@ -100,19 +150,22 @@ export function renderReport(p, { notes, photos }) {
 /** One line per prompt of `data/scripts/setup.mjs`, in its order. Blank keeps the current value. */
 export function setupAnswers(p) {
   const f = p.fields;
-  const ig = f.instagram?.value;
+  // A low-confidence guess stays blank so setup keeps the template's placeholder,
+  // instead of a guess being written in as though it were a discovered fact.
+  const sure = (field) => (field && field.confidence !== "low" ? field : null);
+  const ig = sure(f.instagram)?.value;
   return [
-    val(f.name),
+    val(sure(f.name)),
     "", // production URL: the new domain, not the current website
-    f.reserveUrl?.value ?? "",
-    f.whatsapp?.display ?? "",
+    sure(f.reserveUrl)?.value ?? "",
+    sure(f.whatsapp)?.display ?? "",
     ig ? `@${ig}` : "",
-    val(f.street),
-    val(f.locality),
-    val(f.region),
-    val(f.country),
-    f.coordinates?.value?.lat ?? "",
-    f.coordinates?.value?.lng ?? "",
-    val(f.cuisines),
+    val(sure(f.street)),
+    val(sure(f.locality)),
+    val(sure(f.region)),
+    val(sure(f.country)),
+    sure(f.coordinates)?.value?.lat ?? "",
+    sure(f.coordinates)?.value?.lng ?? "",
+    val(sure(f.cuisines)),
   ].join("\n") + "\n";
 }

package/src/research/lib/search.mjs

@@ -0,0 +1,127 @@
+// Key-free web search, used when Google Places and OpenStreetMap find no place
+// (or no website): a bare name + place otherwise yields an empty report. It only
+// surfaces candidate links (website, Instagram, TripAdvisor, Maps, hub); the rest
+// of the pipeline follows them. DuckDuckGo's Lite endpoint is tried first (the
+// same results in simpler HTML, no JavaScript), then the html endpoint. No key
+// and no login. A bot wall makes the source fail like any other.
+import { fetchText, fold, sameText, tokens, decodeHtml, instagramHandle } from "./util.mjs";
+
+const DDG = [
+  "https://lite.duckduckgo.com/lite/",
+  "https://html.duckduckgo.com/html/",
+];
+
+// Hosts that are directories or social pages, never the restaurant's own site.
+const NOT_WEBSITE =
+  /(duckduckgo|bing|google|youtube|facebook|instagram|tiktok|twitter|(^|\.)x\.com$|tripadvisor|yelp|wikipedia|foursquare|mapquest|waze|trip\.com|expedia|booking|airbnb|justdial|zomato|rappi|ubereats|pedidosya|doordash|grubhub|glovo|opentable|thefork|eltenedor|exploretock|sevenrooms|covermanager|quandoo|linktr|beacons|linkin\.bio|lnk\.bio|taplink|wa\.me|whatsapp)/i;
+const INSTAGRAM = /(^|\.)instagram\.com$/i;
+const TRIPADVISOR = /tripadvisor\./i;
+const FACEBOOK = /(^|\.)facebook\.com$|(^|\.)fb\.com$/i;
+const TIKTOK = /(^|\.)tiktok\.com$/i;
+const MAPS = /maps\.app\.goo\.gl|(^|\.)google\.[a-z.]+\/maps|maps\.google\.com|goo\.gl\/maps/i;
+const HUBS = /(linktr\.ee|beacons\.ai|bio\.link|lnk\.bio|linktree\.com|taplink|campsite\.bio|solo\.to|linkin\.bio|flow\.page)/i;
+
+const textOf = (s) => decodeHtml(String(s).replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
+
+/** Unwraps DuckDuckGo's `//duckduckgo.com/l/?uddg=<url>` redirect to the real result URL. */
+export function resultUrl(href) {
+  if (!href) return null;
+  let u;
+  try { u = new URL(href, "https://html.duckduckgo.com"); } catch { return null; }
+  if (/(^|\.)duckduckgo\.com$/i.test(u.hostname)) {
+    const target = u.searchParams.get("uddg");
+    if (!target) return null;
+    try { return new URL(target).href; } catch { return null; }
+  }
+  return u.protocol === "http:" || u.protocol === "https:" ? u.href : null;
+}
+
+// One pass over the page, matching a result link or a snippet cell in order, so a
+// result with no snippet cannot borrow the next result's text.
+const RESULT_TOKEN = /<a\b([^>]*\b(?:result__a|result-link)\b[^>]*)>([\s\S]*?)<\/a>|<([a-z]+)\b[^>]*\b(?:result__snippet|result-snippet)\b[^>]*>([\s\S]*?)<\/\3>/gi;
+
+/** Pulls { url, title, snippet } out of DuckDuckGo's HTML result page (no DOM parser). */
+export function parseSearchResults(html) {
+  const out = [];
+  const seen = new Set();
+  let current = -1;
+  for (const m of html.matchAll(RESULT_TOKEN)) {
+    if (m[1] !== undefined) {
+      const href = m[1].match(/href=["']([^"']+)["']/i)?.[1] ?? "";
+      const url = resultUrl(href);
+      if (!url || seen.has(url)) { current = -1; continue; }
+      seen.add(url);
+      out.push({ url, title: textOf(m[2]), snippet: "" });
+      current = out.length - 1;
+    } else if (current >= 0 && !out[current].snippet) {
+      out[current].snippet = textOf(m[4]);
+    }
+  }
+  return out;
+}
+
+const hostOf = (url) => { try { return new URL(url).hostname.replace(/^www\./, ""); } catch { return ""; } };
+
+/**
+ * Sorts results into the links the pipeline can follow. `website` is the best
+ * non-directory result whose title/host looks like the restaurant's name; a
+ * result that only matches the place is kept as a weaker candidate.
+ */
+export function classifyResults(results, { name = "" } = {}) {
+  const links = { website: [], instagram: [], tripadvisor: [], facebook: [], tiktok: [], maps: [], hubs: [] };
+  const add = (k, v) => { if (v && !links[k].includes(v)) links[k].push(v); };
+  const candidates = [];
+  for (const { url, title, snippet } of results) {
+    const host = hostOf(url);
+    if (INSTAGRAM.test(host)) {
+      const handle = instagramHandle(url);
+      if (handle) add("instagram", handle);
+    } else if (TRIPADVISOR.test(host)) add("tripadvisor", url);
+    else if (FACEBOOK.test(host)) add("facebook", url);
+    else if (TIKTOK.test(host)) add("tiktok", url);
+    else if (MAPS.test(url)) add("maps", url);
+    else if (HUBS.test(host)) add("hubs", url);
+    else if (NOT_WEBSITE.test(host)) continue;
+    else {
+      const strong = sameText(name, title) || tokens(name).some((t) => fold(host).includes(t));
+      const score = tokens(name).filter((t) => fold(`${title} ${host} ${snippet}`).includes(t)).length;
+      candidates.push({ url, title, snippet, score, strong });
+    }
+  }
+  candidates.sort((a, b) => Number(b.strong) - Number(a.strong) || b.score - a.score);
+  for (const c of candidates) add("website", c.url);
+  return {
+    website: candidates.find((c) => c.strong)?.url ?? candidates[0]?.url ?? "",
+    instagram: links.instagram[0] ?? "",
+    tripadvisor: links.tripadvisor[0] ?? "",
+    facebook: links.facebook[0] ?? "",
+    tiktok: links.tiktok[0] ?? "",
+    mapsUrl: links.maps[0] ?? "",
+    hubs: links.hubs,
+    candidates: candidates.slice(0, 5).map(({ url, title }) => ({ url, title })),
+  };
+}
+
+/**
+ * Runs the search for a restaurant and returns its candidate links. Tries every
+ * endpoint until one returns results; if all answer but none has results, the
+ * empty result is returned so the caller still says "no results" rather than
+ * "failed". Throws only when no endpoint answers.
+ */
+export async function searchWeb({ name, location = "" }) {
+  const query = [name, location, "restaurant"].filter(Boolean).join(" ");
+  const qs = new URLSearchParams({ q: query }).toString();
+  let lastError, empty;
+  for (const base of DDG) {
+    let r;
+    try { r = await fetchText(`${base}?${qs}`, { headers: { accept: "text/html" } }); }
+    catch (e) { lastError = e; continue; }
+    if (!r.ok) { lastError = new Error(`DuckDuckGo ${r.status}`); continue; }
+    const results = parseSearchResults(r.text);
+    const found = { source: "search", url: r.url, query, results, ...classifyResults(results, { name }) };
+    if (results.length) return found;
+    empty = found;
+  }
+  if (empty) return empty;
+  throw lastError ?? new Error("DuckDuckGo search failed");
+}