[docs] Add the Reo.dev beacon to the documentation site

CHANGELOG.md

@@ -9,11 +9,14 @@
 
 ### Docs
 
+- The Reo.dev beacon runs on the documentation site, as `docs/reo.js`. Mintlify includes any `.js` in the content directory on every page — there is no head-injection key in `docs.json` — so a root file is the whole install, and it is the form Reo's own Mintlify guide prescribes. The loader is kept byte-for-byte as Reo issues it so it stays diffable against the vendor snippet; `__tests__/docs/reo.test.ts` drives it in a DOM and asserts the client ID in the CDN URL is the same one handed to `Reo.init`, because a mismatched pair loads a working script that reports to nobody and the only symptom is an empty dashboard weeks later (#790)
 - The 1.0.2 documentation overhaul is reverted: `docs/` and `README.md` go back byte-for-byte to the commit #756 merged onto, along with the 14 generated locales and 14 translated READMEs #759 regenerated from those English sources. The release half of #756 stays — `package.json` and the Cargo workspace are untouched, since they have moved on to 1.0.4-beta.0 and the release tag the CLI builds its daemon download URL from is that npm version. Under `## 1.0.2` the heading and its release narrative stay, because 1.0.2 did ship; the `### Docs` entries underneath described the overhaul and go with it. Leaving the locales in place was the alternative considered and rejected: the nightly translate job is content-hash cached, so pages whose pre-overhaul English hashes it had already seen would have been skipped rather than repaired, stranding every non-English reader on a translation of text that no longer exists (#773)
 - The landing page no longer opens with the harness paragraph claiming that "the same events, the same policies, and the same session history apply to every one" of the twelve. Removed from `docs/index.mdx` and all 14 locales (#773)
 
 ### Dependencies
 
+- The `sharp` override moves 0.35.0 → 0.35.4, closing GHSA-rgj7-g3m4-5g8c (CVSS 8.9 — two Critical libheif RCEs inherited through libvips, reachable when processing untrusted input). Same surface-late shape as browserslist above and the chromadb entries: the advisory published 2026-09-08 21:25 UTC, between main's green Supply Chain run at 14:18 and its red one the next morning, so it turned every open branch red without any dependency change of its own — reproduced identically by running CI's scanner image against main's untouched lockfile. It stays an override rather than becoming a direct dependency because sharp is still only an optional dependency of next; what changed since #591 pinned it is the direction of the constraint. That pin was needed because next asked for `^0.34.5`, a range that excluded the then-fixed 0.35.0 — next 16.3.4 now asks for `^0.35.4`, so the pin had inverted into the thing holding the tree *below* what its dependent wants. Verified past a green lockfile the same way #591 did: sharp 0.35.4 loads against libvips 8.18.6 (`@img/sharp-libvips-*` 1.3.0 → 1.3.3) and round-trips a PNG encode; the scanner image reports "No issues found" (exit 0) with `osv-scanner.toml` gaining no new entry (#790)
+
 - `fp-cloud-cli`: typer 0.27.1 → 0.27.2, click 8.4.2 → 8.5.0, posthog 7.42.0 → 7.44.2 (#771)
 
 - `osv-scanner.toml` ignores GHSA-8mgp-746c-j5xp (nltk 3.10.3, CVSS 8.3) until 2026-11-20. Surfaced 2026-09-03 against an already-approved PR — nothing on the branch introduced it and nothing on the branch can resolve it, which is the case the allow-list exists for. nltk is transitive via `llama-index-core` and appears only in `sdk/python/uv.lock`, the dev/test lockfile that pins every extra so CI can exercise the adapters; the SDK's own runtime dependency list is empty and the `llamaindex` extra is imported lazily, so it reaches no shipped code path. OSV reports "0 vulnerabilities can be fixed" and an empty FIXED VERSION, so the only alternative is dropping the extra and its adapter tests. Dated to match the chromadb entries so the list is revisited in one pass

__tests__/docs/reo.test.ts

@@ -0,0 +1,140 @@
+/**
+ * `docs/reo.js` — the Reo.dev beacon on the documentation site.
+ *
+ * Analytics is the archetype of code that fails silently: the docs render
+ * identically whether the beacon loaded, loaded under someone else's client ID,
+ * or never ran at all. Nobody notices from the page — only from a dashboard
+ * that stays empty, weeks later, with no way to tell a quiet week from a broken
+ * install.
+ *
+ * So this drives the script the way a browser does — eval it into a DOM, catch
+ * the `<script>` it appends, fire its `onload` against a stubbed `Reo` — and
+ * pins the three things that make the difference between reporting and not:
+ * the file is where Mintlify looks, the loader points at Reo's CDN, and the
+ * client ID in the URL is the same one handed to `Reo.init`.
+ *
+ * Same shape as `stars.test.ts`, for the same reason: the script is an IIFE
+ * with no exports, and a fresh document per case keeps one run's appended
+ * script out of the next one's assertions.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+interface ReoWindow {
+  document: Document;
+  Reo?: { init: (opts: { clientID?: string }) => void };
+  eval(code: string): unknown;
+}
+const { JSDOM } = createRequire(import.meta.url)("jsdom") as {
+  JSDOM: new (
+    html: string,
+    options?: Record<string, unknown>,
+  ) => { window: ReoWindow };
+};
+
+const DOCS = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "docs");
+const PATH = join(DOCS, "reo.js");
+const SCRIPT = readFileSync(PATH, "utf-8");
+
+/** The tenant this install reports to. Changing it is changing customers. */
+const CLIENT_ID = "023277be3290bc6";
+
+interface Run {
+  window: ReoWindow;
+  /** The `<script>` elements the snippet appended to `<head>`, in order. */
+  injected: () => HTMLScriptElement[];
+  /** Client IDs passed to `Reo.init`, in order. */
+  inits: string[];
+}
+
+function run({ reo = true }: { reo?: boolean } = {}): Run {
+  const dom = new JSDOM("<!doctype html><html><head></head><body></body></html>", {
+    runScripts: "outside-only",
+    url: "https://docs.befailproof.ai/",
+  });
+  const window = dom.window;
+  const inits: string[] = [];
+  if (reo) {
+    window.Reo = {
+      init(opts) {
+        inits.push(String(opts && opts.clientID));
+      },
+    };
+  }
+  window.eval(SCRIPT);
+  return {
+    window,
+    injected: () =>
+      Array.from(
+        window.document.head.querySelectorAll("script"),
+      ) as HTMLScriptElement[],
+    inits,
+  };
+}
+
+describe("docs/reo.js", () => {
+  it("sits at the docs content root, where Mintlify injects it", () => {
+    // Mintlify includes `.js` from the content directory on every page. A file
+    // anywhere else — `docs/images/`, the repo root, a locale folder — is
+    // shipped and never executed, and the site looks exactly the same.
+    expect(existsSync(PATH)).toBe(true);
+  });
+
+  it("loads the beacon from Reo's CDN for our client ID", () => {
+    const r = run();
+    const tags = r.injected();
+    expect(tags).toHaveLength(1);
+    expect(tags[0].src).toBe(
+      `https://static.reo.dev/${CLIENT_ID}/reo.js`,
+    );
+  });
+
+  it("initialises with the same client ID the script URL carries", () => {
+    // The snippet spells the ID twice. Two different tenants there loads a
+    // perfectly working script that reports nowhere we can read.
+    const r = run();
+    expect(r.inits).toEqual([]); // nothing until the CDN script has loaded
+    r.injected()[0].onload?.(new r.window.document.defaultView!.Event("load"));
+    expect(r.inits).toEqual([CLIENT_ID]);
+  });
+
+  it("does not block rendering on the beacon", () => {
+    // A script built with `createElement` and appended is async by default, so
+    // reading the property back proves nothing on its own — it is true whether
+    // the loader sets `async`, sets `defer`, or sets neither. The source
+    // assertion is what actually pins the flag; this one catches a rewrite that
+    // drops to a parser-blocking `document.write`.
+    expect(run().injected()[0].async).toBe(true);
+    expect(SCRIPT).toContain("n.async=!0");
+  });
+
+  it("runs at most once per page load", () => {
+    // Mintlify injects the file once per full page load, not per client-side
+    // navigation, so the vendor snippet carries no re-entry guard. If that ever
+    // changes, a second run must not stack a second beacon — this is the
+    // tripwire that would fail first.
+    const r = run();
+    expect(r.injected()).toHaveLength(1);
+  });
+
+  it("matches the snippet Reo issues for Mintlify, character for character", () => {
+    // Reo's Mintlify guide gives one minified loader line. Keeping it verbatim
+    // is what makes this file diffable against the vendor docs; a hand-edit
+    // that reshapes it should be a deliberate, reviewed change. Reo's *other*
+    // install pages ship the same loader with `defer` in place of `async` —
+    // functionally identical here, but this is installed from the Mintlify
+    // page, so that is the text it is held to.
+    const loader = SCRIPT.split("\n").filter(
+      (l) => !l.startsWith(" *") && !l.startsWith("/*") && l.trim() !== "",
+    );
+    expect(loader).toHaveLength(1);
+    expect(loader[0]).toBe(
+      `!function(){var e,t,n;e="${CLIENT_ID}",t=function(){Reo.init({clientID:"${CLIENT_ID}"})},` +
+        `(n=document.createElement("script")).src="https://static.reo.dev/"+e+"/reo.js",` +
+        `n.async=!0,n.onload=t,document.head.appendChild(n)}();`,
+    );
+  });
+});