six-degrees 0.2.0

package/.next/standalone/scripts/check-node.mjs

@@ -0,0 +1,28 @@
+// Runs before `npm run dev` and `npm run build`.
+//
+// The database is Node's built-in node:sqlite, which arrived in 22.13. On an
+// older Node the app installs and starts perfectly and then throws
+// "Cannot find module 'node:sqlite'" on the first query — a runtime error that
+// reads like a broken app rather than a missing requirement. `engines` in
+// package.json is only a warning by default, so it does not catch this either.
+
+const NEED = [22, 13];
+const [major, minor] = process.versions.node.split('.').map(Number);
+
+if (major < NEED[0] || (major === NEED[0] && minor < NEED[1])) {
+  const need = NEED.join('.');
+  console.error(`
+  ┌──────────────────────────────────────────────────────────────┐
+  │  6 Degrees needs Node ${need} or newer.                          │
+  └──────────────────────────────────────────────────────────────┘
+
+  You have Node ${process.versions.node}.
+
+  The database uses node:sqlite, which is built into Node from ${need}.
+  On older versions the app starts and then fails on its first query.
+
+  Install the current LTS from https://nodejs.org and run this again.
+  With nvm:  nvm install --lts && nvm use --lts
+`);
+  process.exit(1);
+}

package/.next/standalone/scripts/check-stale-server.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Runs before `npm run dev`.
+//
+// A dev server started before a `git pull` keeps serving what it had at launch,
+// and when you start a second one Next quietly takes the next free port. Your
+// browser is still pointed at the first, so the app looks like the pull never
+// happened — the exact confusion that cost an evening: correct commit, correct
+// files, old screen.
+//
+// This does not kill anything. It tells you what is already listening and gives
+// you the line to run.
+
+import { execFileSync } from 'node:child_process';
+
+const PORTS = [3000, 3001, 3002, 3210];
+
+function listeners() {
+  try {
+    const out = execFileSync('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString();
+    return out
+      .split('\n')
+      .filter((l) => /^node\b/.test(l))
+      .map((l) => {
+        const pid = l.split(/\s+/)[1];
+        const port = (l.match(/:(\d+)\s+\(LISTEN\)/) || [])[1];
+        return port ? { pid, port: Number(port) } : null;
+      })
+      .filter(Boolean)
+      .filter((p) => PORTS.includes(p.port));
+  } catch {
+    return [];   // no lsof, or not permitted — never block the dev server
+  }
+}
+
+const running = listeners();
+if (running.length > 0) {
+  const list = running.map((r) => `port ${r.port} (pid ${r.pid})`).join(', ');
+  console.log(`
+  ┌──────────────────────────────────────────────────────────────┐
+  │  Something is already serving on a port this app uses.       │
+  └──────────────────────────────────────────────────────────────┘
+
+  Already listening: ${list}
+
+  If that is an older copy of this app, it is still serving the code it had
+  when it started — including from before your last git pull. Starting another
+  one now takes the NEXT free port, so your browser keeps showing the old one.
+
+  To replace it:
+
+      pkill -f "next dev"; pkill -f "next-server"; npm run dev
+
+  Continuing anyway — watch the port this prints, it may not be ${running[0].port}.
+`);
+}

package/.next/standalone/scripts/gen-synthetic.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * Generates the sample network that ships with the app.
+ *
+ * Every person in it is invented. The point is to have something to look at on
+ * a first run, in screenshots, and in the demo — without putting a single real
+ * person's name, employer or face in a public repository.
+ *
+ * Deterministic: the same seed always produces the same network, so the file
+ * only changes when this script does, and diffs stay reviewable.
+ *
+ *   node scripts/gen-synthetic.mjs [--seed 20260824] [--out public/demo-data.json]
+ */
+import { writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { scoreNetwork, explainScore } from '../lib/scoring.js';
+
+// ── deterministic PRNG (mulberry32) ────────────────────────────────────────
+function rng(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const FIRST = [
+  'Ada','Bo','Cleo','Dev','Esme','Finn','Gia','Hugo','Iris','Jai','Kira','Lev','Mina','Nils','Otto',
+  'Pia','Quinn','Rune','Sana','Tobias','Ula','Vero','Wren','Xanthe','Yuki','Zane','Amara','Bodhi',
+  'Cassia','Dario','Elio','Freya','Gideon','Halle','Ines','Jonah','Kaya','Liora','Marek','Nadia',
+  'Oona','Paolo','Rhea','Soren','Tamsin','Ursa','Viggo','Wilder','Ximena','Yusuf','Zora','Callum',
+  'Delphine','Emeka','Fiora','Gustav','Hana','Idris','Juno','Kepler','Linnea','Mateo','Noor',
+];
+const LAST = [
+  'Ashworth','Baptiste','Calloway','Delacroix','Eriksen','Farrow','Gallagher','Halvorsen','Ibarra',
+  'Jansson','Kowalczyk','Lindqvist','Marchetti','Nakamura','Okonkwo','Pereira','Quintero','Rasmussen',
+  'Silvestri','Thorne','Ueda','Vasquez','Whitlock','Ximenes','Yamamoto','Zabala','Brennan','Castellan',
+  'Dumont','Espinoza','Fontaine','Grimaldi','Hollis','Ingram','Jokinen','Kristiansen','Lindgren',
+  'Moreau','Nyberg','Ostrowski','Petrov','Rosales','Stavros','Tsegaye','Varga','Weatherby',
+];
+
+// Invented companies, spread across the prestige ladder so the tier mix looks
+// like a real network rather than everyone landing in one band.
+const COMPANIES = [
+  { name: 'Northwind Labs',      weight: 6 },
+  { name: 'Halcyon',             weight: 5 },
+  { name: 'Verity Systems',      weight: 5 },
+  { name: 'Lumen Robotics',      weight: 4 },
+  { name: 'Kestrel Analytics',   weight: 4 },
+  { name: 'Meridian Health',     weight: 4 },
+  { name: 'Orchard Pay',         weight: 4 },
+  { name: 'Tessellate',          weight: 3 },
+  { name: 'Bright Harbor Media', weight: 3 },
+  { name: 'Ironwood Capital',    weight: 3 },
+  { name: 'Sable & Finch',       weight: 3 },
+  { name: 'Cobalt Studio',       weight: 3 },
+  { name: 'Fernhill Foods',      weight: 2 },
+  { name: 'Ridgeline Outfitters',weight: 2 },
+  { name: 'Aperture Grid',       weight: 2 },
+  { name: 'Quarry Interactive',  weight: 2 },
+  { name: 'Blue Larch',          weight: 2 },
+  { name: 'Everly Group',        weight: 2 },
+  { name: 'Pinecrest University',weight: 2 },
+  { name: '',                    weight: 2 },  // some people list no employer
+];
+
+const TITLES = [
+  'Chief Executive Officer','Founder','President','Chief Technology Officer',
+  'VP of Engineering','VP of Marketing','SVP of Operations','Managing Director',
+  'Director of Product','Director of Engineering','Head of Growth','Head of Design',
+  'Senior Engineering Manager','Group Product Manager','Engineering Manager',
+  'Principal Engineer','Staff Software Engineer','Lead Data Scientist',
+  'Senior Software Engineer','Senior Product Designer','Senior Manager, Partnerships',
+  'Account Manager','Client Partner','Brand Strategist',
+  'Software Engineer','Product Designer','Data Analyst','Program Coordinator',
+  'Marketing Intern','Research Assistant',
+];
+
+// ── scoring: the app's own model (lib/scoring.js), nothing copied ──
+// Invented companies are unknown to its list of real ones, so they get scores
+// the way a user sets their own (Paths → Scores), spread across the ladder so
+// the tier mix looks like a real network.
+const COMPANY_SCORES = new Map(Object.entries({
+  'Northwind Labs': 9, 'Halcyon': 9, 'Verity Systems': 8, 'Lumen Robotics': 8,
+  'Kestrel Analytics': 7, 'Meridian Health': 7, 'Orchard Pay': 7, 'Tessellate': 6,
+  'Bright Harbor Media': 6, 'Ironwood Capital': 8, 'Sable & Finch': 5, 'Cobalt Studio': 5,
+  'Fernhill Foods': 4, 'Ridgeline Outfitters': 4, 'Aperture Grid': 5, 'Quarry Interactive': 4,
+  'Blue Larch': 4, 'Everly Group': 5, 'Pinecrest University': 3,
+}));
+
+/** Score rows in place with the app's model; returns them. */
+function scoreRows(rows) {
+  const { scores } = scoreNetwork(rows, { overrides: COMPANY_SCORES });
+  for (const r of rows) {
+    const s = scores.get(r.id);
+    const c = s.circle;
+    Object.assign(r, {
+      seniority_score: s.title.points,
+      company_prestige_score: s.companyScore,
+      power_score: s.power,
+      tier: s.tier,
+      // The sample's companies were scored for it, not by the viewer.
+      score_why: explainScore(s, s.boost).replace(', your score', ', sample score'),
+      circle_power: c ? Math.round(c.circlePower * 100) / 100 : 0,
+      circle_s_count: c?.sCount || 0,
+      circle_a_count: c?.aCount || 0,
+      circle_elite_pct: c ? Math.round(c.elitePct * 100) / 100 : 0,
+      is_catalyst: Boolean(c?.isCatalyst),
+      catalyst_score: c?.isCatalyst ? c.sCount + c.aCount : 0,
+    });
+  }
+  return rows;
+}
+
+function pickWeighted(rand, items) {
+  const total = items.reduce((s, i) => s + i.weight, 0);
+  let r = rand() * total;
+  for (const i of items) if ((r -= i.weight) < 0) return i.name;
+  return items[items.length - 1].name;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const seed = Number(args[args.indexOf('--seed') + 1]) || 20260824;
+  const outArg = args.indexOf('--out');
+  const out = outArg > -1 ? args[outArg + 1] : 'public/demo-data.json';
+
+  const rand = rng(seed);
+  const used = new Set();
+  const uniqueName = () => {
+    for (let i = 0; i < 500; i++) {
+      const n = `${FIRST[Math.floor(rand() * FIRST.length)]} ${LAST[Math.floor(rand() * LAST.length)]}`;
+      if (!used.has(n)) { used.add(n); return n; }
+    }
+    return `Person ${used.size + 1}`;
+  };
+
+  const person = (degree, sourceId) => {
+    const name = uniqueName();
+    const title = TITLES[Math.floor(rand() * TITLES.length)];
+    const company = pickWeighted(rand, COMPANIES);
+    const slug = name.toLowerCase().replace(/[^a-z]+/g, '-');
+    return {
+      id: `syn-${degree}-${used.size}-${Math.floor(rand() * 1e6).toString(36)}`,
+      degree,
+      source_connection_id: sourceId ?? null,
+      name,
+      headline: company ? `${title} at ${company}` : title,
+      company,
+      role: title,
+      profile_url: `https://www.linkedin.com/in/${slug}`,
+      profile_image_url: null,        // invented people have no photographs
+      connected_date: null,
+      seniority_score: 0, company_prestige_score: 0, power_score: 0, tier: null, score_why: null,
+      influence_signals: {},
+      is_catalyst: false,
+      catalyst_score: 0,
+      circle_power: 0, circle_s_count: 0, circle_a_count: 0, circle_elite_pct: 0,
+      outreach_status: null,
+      unlock_status: null,
+      scanned_company: null,
+    };
+  };
+
+  const D1_COUNT = 150;
+  const BRIDGE_COUNT = 14;
+
+  const degree1 = scoreRows(Array.from({ length: D1_COUNT }, () => person(1)));
+  degree1.sort((a, b) => b.power_score - a.power_score);
+
+  // The highest-leverage people become bridges with a mapped circle behind
+  // them, which is what makes the Bridges view worth opening.
+  const bridges = degree1.slice(0, BRIDGE_COUNT);
+  const degree2 = [];
+  for (const b of bridges) {
+    const size = 18 + Math.floor(rand() * 45);
+    const circle = Array.from({ length: size }, () => person(2, b.id));
+    degree2.push(...circle);
+  }
+  // Everyone again, together: circles now exist, so bridges get their boost.
+  scoreRows([...degree1, ...degree2]);
+  degree1.sort((a, b) => b.power_score - a.power_score);
+  degree2.sort((x, y) => y.power_score - x.power_score);
+
+  const payload = {
+    user: { id: 'synthetic-demo-user', name: 'You', headline: 'Sample network' },
+    degree1,
+    degree2,
+    counts: { degree1: degree1.length, degree2: degree2.length },
+    meta: {
+      synthetic: true,
+      seed,
+      generated_by: 'scripts/gen-synthetic.mjs',
+      note: 'Every person in this file is invented. No real individual is represented.',
+    },
+  };
+
+  mkdirSync(path.dirname(out), { recursive: true });
+  writeFileSync(out, JSON.stringify(payload));
+
+  const tiers = {};
+  degree1.forEach((c) => { tiers[c.tier] = (tiers[c.tier] || 0) + 1; });
+  const kb = Math.round(JSON.stringify(payload).length / 1024);
+  console.log(`wrote ${out}  (${kb} KB, seed ${seed})`);
+  console.log(`  1st degree : ${degree1.length}`);
+  console.log(`  2nd degree : ${degree2.length} across ${BRIDGE_COUNT} bridges`);
+  console.log(`  catalysts  : ${bridges.filter((b) => b.is_catalyst).length}`);
+  console.log(`  tier mix   : ${['S','A','B','C','D'].map((t) => `${t}:${tiers[t] || 0}`).join('  ')}`);
+}
+
+main();

package/.next/standalone/scripts/image_store.py

@@ -0,0 +1,125 @@
+"""Permanent avatar capture.
+
+LinkedIn CDN image URLs (media.licdn.com) are signed and expire in ~3 weeks, so
+storing the raw URL means every avatar breaks on that cycle. Instead, while the
+signed URL is still fresh (right after scraping), we download the bytes, crop to a
+small square, and re-encode as a tiny WebP saved under the user's data directory
+(~/.six-degrees/avatars, or $SIX_DEGREES_HOME/avatars). The record stores the local
+path /avatars/<slug>.webp, which never expires and is served by app/avatars/[file].
+
+Avatars live outside the repo on purpose: they are photographs of real people and
+must never be committed, and an installed copy of the app must not write into its
+own package directory.
+
+Typical output: 96x96 WebP ~2-4 KB per person (vs ~15-40 KB for the original).
+"""
+
+import io
+import hashlib
+import pathlib
+
+import requests
+from PIL import Image, ImageOps
+
+import os
+
+def _data_dir():
+    return pathlib.Path(os.environ.get("SIX_DEGREES_HOME") or (pathlib.Path.home() / ".six-degrees"))
+
+AVATAR_DIR = _data_dir() / "avatars"
+
+SIZE = 96        # nodes render small; 96px stays crisp on retina
+QUALITY = 72     # WebP quality — good balance for face icons
+TIMEOUT = 15
+
+
+def _slug(key):
+    """Stable filename derived from a person's profile URL (or any stable key)."""
+    return hashlib.sha1(key.strip().encode("utf-8")).hexdigest()[:16]
+
+
+# Pictures already claimed by somebody, keyed by the hash of the downloaded
+# bytes. Filled as a run proceeds and consulted before anything is written.
+_claimed = {}
+
+
+def reset_claims():
+    """Start a fresh run. Only useful for tests and long-lived processes."""
+    _claimed.clear()
+
+
+def store_avatar(image_url, key, overwrite=True):
+    """Download image_url, compress to a small square WebP, save under the data dir.
+
+    Returns the local web path ("/avatars/<slug>.webp") or None if the fetch/decode
+    fails (e.g. the signed URL already expired -> 403), or if this exact picture
+    already belongs to somebody else.
+
+    That last case matters more than it sounds. Files are named after the PERSON —
+    sha1(profile_url) — so one photograph handed to fifty people used to become fifty
+    separate files holding identical bytes, and nothing downstream could tell. On one
+    real database that was 2,821 of 3,486 photographs: mostly LinkedIn's placeholder
+    silhouette for people who have no picture, plus genuine mis-attributions from a
+    scraper that matched people by the text of their link. Both look the same from
+    here, and both are wrong to save. Initials are honest; somebody else's face is not.
+    """
+    if not image_url or not key:
+        return None
+    slug = _slug(key)
+    out = AVATAR_DIR / f"{slug}.webp"
+    if out.exists() and not overwrite:
+        return "/avatars/%s.webp" % slug
+    try:
+        resp = requests.get(image_url, timeout=TIMEOUT)
+        if resp.status_code != 200 or not resp.content:
+            return None
+
+        # Hash what actually arrived, before any re-encoding, so two fetches of
+        # the same picture under different signed URLs still collide.
+        digest = hashlib.sha256(resp.content).hexdigest()
+        owner = _claimed.get(digest)
+        if owner is not None and owner != key:
+            return None
+        _claimed[digest] = key
+
+        img = Image.open(io.BytesIO(resp.content))
+        img = ImageOps.exif_transpose(img).convert("RGB")
+        img = ImageOps.fit(img, (SIZE, SIZE), Image.LANCZOS)  # center-crop to square
+        AVATAR_DIR.mkdir(parents=True, exist_ok=True)
+        img.save(out, "WEBP", quality=QUALITY, method=6)
+        return "/avatars/%s.webp" % slug
+    except Exception as e:  # network hiccup, non-image body, decode error
+        print("  [image_store] skip %s: %s" % (key[:40], e))
+        return None
+
+
+def localize_images(images):
+    """Turn scraper image records that point at expiring licdn URLs into permanent
+    local ones. Input/output: list of {"profileUrl", "imageUrl"}. Entries whose
+    download or compression fails are dropped (kept as no-image rather than a dead URL)."""
+    out = []
+    ok = 0
+    for rec in images:
+        purl = rec.get("profileUrl")
+        iurl = rec.get("imageUrl")
+        local = store_avatar(iurl, purl) if (purl and iurl) else None
+        if local:
+            out.append({"profileUrl": purl, "imageUrl": local})
+            ok += 1
+    shared = len(images) - ok
+    print("  [image_store] captured %d/%d avatars -> %s" % (ok, len(images), AVATAR_DIR))
+    if shared > 0:
+        print("  [image_store] %d skipped: no picture, or the same picture as someone else" % shared)
+    return out
+
+
+if __name__ == "__main__":
+    # Quick self-test: python image_store.py <image_url> <key>
+    import sys
+    if len(sys.argv) >= 3:
+        path = store_avatar(sys.argv[1], sys.argv[2])
+        if path:
+            f = REPO / "public" / path.lstrip("/")
+            print("saved %s (%d bytes)" % (path, f.stat().st_size))
+        else:
+            print("failed (URL likely expired or not an image)")

package/.next/standalone/scripts/make-dmg-background.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Render scripts/dmg/background.html into scripts/dmg/background.tiff — the
+// picture behind the .dmg window: drag across, then the one-time Open Anyway step.
+//
+// Run by hand when the picture changes, and commit the .tiff. The build only
+// copies it, so packaging never depends on a browser being installed (the
+// release runners have Chrome, but a build that needs one to succeed is a build
+// that fails for no reason one day).
+//
+// Needs Google Chrome (or CHROME=/path/to/a/chromium) and macOS's sips and
+// tiffutil. Produces a two-resolution TIFF, 640 × 440 at 72 dpi plus 1280 × 880
+// at 144 dpi, which is how Finder picks the sharp one on a Retina screen.
+
+import { execFileSync, spawn } from 'node:child_process';
+import { mkdtempSync, rmSync, existsSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.join(HERE, 'dmg', 'background.html');
+const OUT = path.join(HERE, 'dmg', 'background.tiff');
+const W = 640;
+const H = 440;
+
+const CHROME = process.env.CHROME || '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+if (!existsSync(CHROME)) {
+  console.error(`Chrome not found at ${CHROME}. Set CHROME=/path/to/chrome and run again.`);
+  process.exit(1);
+}
+
+// Headless Chrome writes the screenshot within a few seconds and then, on some
+// macOS versions, never exits. So: start it, wait for the file to appear and stop
+// growing, then end it ourselves.
+async function shoot(scale, png, work) {
+  const child = spawn(CHROME, [
+    '--headless=new', '--disable-gpu', '--hide-scrollbars', '--no-first-run',
+    '--no-default-browser-check', '--disable-extensions',
+    // A fresh profile asks the macOS keychain for Chrome's storage key, which
+    // can raise a permission prompt. Nothing here needs stored secrets.
+    '--use-mock-keychain',
+    // Its own profile, so this never collides with a Chrome you have open.
+    `--user-data-dir=${path.join(work, `profile-${scale}`)}`,
+    `--force-device-scale-factor=${scale}`,
+    `--window-size=${W},${H}`,
+    `--screenshot=${png}`,
+    pathToFileURL(SRC).href,
+  ], { stdio: 'ignore', detached: true });
+
+  const deadline = Date.now() + 60000;
+  let last = -1;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 500));
+    if (!existsSync(png)) continue;
+    const size = statSync(png).size;
+    if (size > 0 && size === last) break;
+    last = size;
+  }
+  try { process.kill(-child.pid, 'SIGKILL'); } catch { /* already gone */ }
+  if (!existsSync(png)) throw new Error('Chrome did not write a screenshot within 60 seconds.');
+}
+
+const work = mkdtempSync(path.join(tmpdir(), 'dmg-bg-'));
+try {
+  const shots = [];
+  for (const scale of [1, 2]) {
+    const png = path.join(work, scale === 1 ? 'bg.png' : 'bg@2x.png');
+    await shoot(scale, png, work);
+    execFileSync('sips', ['-s', 'dpiWidth', String(72 * scale), '-s', 'dpiHeight', String(72 * scale), png],
+      { stdio: 'ignore' });
+    shots.push(png);
+  }
+  execFileSync('tiffutil', ['-cathidpicheck', ...shots, '-out', OUT], { stdio: 'inherit' });
+  console.log(`✓ ${path.relative(process.cwd(), OUT)}`);
+} finally {
+  rmSync(work, { recursive: true, force: true });
+}

package/.next/standalone/scripts/prepare-standalone.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Finishes the standalone build.
+ *
+ * `next build --output standalone` emits a server and its traced dependencies,
+ * but deliberately leaves out the static assets and public files — it expects
+ * the deployer to place them. When the deployment target is an npm package,
+ * that deployer is this script.
+ *
+ * It runs as part of `npm run build` rather than before packing, because
+ * `prepack` triggers a build that would wipe anything copied in beforehand —
+ * which shipped a package whose CSS and JS all 404'd.
+ */
+import { cpSync, existsSync, rmSync } from 'node:fs';
+import path from 'node:path';
+
+const ROOT = process.cwd();
+const STANDALONE = path.join(ROOT, '.next', 'standalone');
+
+if (!existsSync(STANDALONE)) {
+  console.log('  (no standalone output — nothing to prepare)');
+  process.exit(0);
+}
+
+const copies = [
+  { from: path.join(ROOT, '.next', 'static'), to: path.join(STANDALONE, '.next', 'static'), label: '.next/static' },
+  { from: path.join(ROOT, 'public'), to: path.join(STANDALONE, 'public'), label: 'public' },
+];
+
+for (const { from, to, label } of copies) {
+  if (!existsSync(from)) { console.log(`  skipped ${label} (not present)`); continue; }
+  rmSync(to, { recursive: true, force: true });
+  cpSync(from, to, { recursive: true });
+  console.log(`  copied ${label} into the standalone build`);
+}
+
+// Documentation images get traced in as a side effect and only add weight.
+const docs = path.join(STANDALONE, 'docs');
+if (existsSync(docs)) {
+  rmSync(docs, { recursive: true, force: true });
+  console.log('  dropped docs/ from the standalone build');
+}

package/.next/standalone/scripts/requirements.txt

@@ -0,0 +1,4 @@
+playwright>=1.40.0
+requests>=2.31.0
+Pillow>=10.0.0
+tzdata>=2024.1; sys_platform == "win32"

package/.next/standalone/scripts/sandbox.mjs

@@ -0,0 +1,59 @@
+// `npm run fresh` — run the app as if you had never used it before.
+//
+// Everything personal lives in one place: SIX_DEGREES_HOME (default
+// ~/.six-degrees) holds the database, the captured avatars, the scraper's
+// signed-in Chrome profile and its Python environment. Point that somewhere
+// else and you are a brand-new user, with your real data untouched.
+//
+// This exists because there is no other honest way to check the first-run
+// experience once you have used the app: your own data makes every empty state
+// and every setup step invisible.
+
+import { spawn } from 'node:child_process';
+import { rmSync, existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HOME = path.join(ROOT, '.sandbox');
+const PORT = process.env.PORT || '3456';
+const reset = process.argv.includes('--reset');
+
+if (reset && existsSync(HOME)) {
+  rmSync(HOME, { recursive: true, force: true });
+  console.log('  Wiped the sandbox. This run starts from nothing again.\n');
+}
+mkdirSync(HOME, { recursive: true });
+
+const firstRun = !existsSync(path.join(HOME, 'six-degrees.sqlite'));
+
+console.log(`
+  ┌──────────────────────────────────────────────────────────────┐
+  │  Sandbox — you are a brand-new user                          │
+  └──────────────────────────────────────────────────────────────┘
+
+  Data for this run:  .sandbox/
+  Your real data:     ${process.env.SIX_DEGREES_HOME || '~/.six-degrees'}  (untouched)
+
+  ${firstRun ? 'Nothing here yet — this is a true first run.' : 'Reusing the last sandbox. Add --reset to start over.'}
+
+  Opening http://localhost:${PORT}
+  Stop with Ctrl-C.  Start over:  npm run fresh -- --reset
+`);
+
+const child = spawn(
+  'npx',
+  ['next', 'dev', '-H', '127.0.0.1', '-p', PORT],
+  {
+    cwd: ROOT,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      SIX_DEGREES_HOME: HOME,
+      SIX_DEGREES_BIND: '127.0.0.1',
+      NEXT_TELEMETRY_DISABLED: '1',
+    },
+  }
+);
+
+child.on('close', (code) => process.exit(code ?? 0));