diff --git a/PERSPECTIVE.md b/PERSPECTIVE.md
new file mode 100644
index 0000000..190e96d
--- /dev/null
+++ b/PERSPECTIVE.md
@@ -0,0 +1,49 @@
+# Perspective — dataflow specifics
+
+Shared rationale lives in the canonical guide: **`/home/pt/pf_app/PERSPECTIVE.md`**
+(loading, version policy, Arrow constraints, deploy pattern, upgrade smoke test).
+This file records only what's specific to dataflow.
+
+> **Distribution:** these are the **`@perspective-dev/*`** packages (repo
+> github.com/perspective-dev/perspective), **not** FINOS `@finos/perspective`. Same
+> engine, separate npm scope and release schedule — don't mix the two.
+
+---
+
+## Current state
+
+- **Loader:** npm `/inline` (`ui/src/pages/Pivot.jsx`) — bundled WASM, offline-capable. ✅
+  This is the target loader; pf_app should adopt it.
+- **Data:** JSON rows via `api.getViewData(source, 100000, 0)`, capped at 100k. ✅
+  Correct for dataflow's read-only, click-to-inspect model. No need to move to Arrow
+  unless view sizes grow well past 100k.
+- **Deploy:** `deploy.sh` + `dataflow.service` (systemd) + nginx. ✅ Reference pattern
+  for the org; pf_app should copy it.
+- **Charts:** `viewer-d3fc` is imported, so the chart plugins are available in the UI.
+  Default plugin config is datagrid-only (`{ edit_mode: 'SELECT_REGION' }`).
+- **Layout safety:** `cleanLayout()` filters saved configs against valid columns before
+  restore — the reference implementation; keep it.
+
+## The version pair is correct — do NOT "fix" it to 4.4.1
+
+`ui/package.json` pins **viewer/client/datagrid at `^4.5.1`** and **`viewer-d3fc` at
+`^4.4.1`**. This looks like a skew but is **deliberate and necessary** — it's the only
+combination that keeps both of dataflow's hard requirements:
+
+- **Inline WASM bundling.** `Pivot.jsx` imports `@perspective-dev/client/inline`,
+  `@perspective-dev/viewer/inline`, and `@perspective-dev/viewer/themes`. Those export
+  paths **exist only in 4.5.x** — they are absent from 4.4.1's `exports` map.
+- **d3fc chart plugins.** `viewer-d3fc` is published only up to **4.4.1**.
+
+Verified the hard way: pinning all four to 4.4.1 and rebuilding fails with
+`"./inline" is not exported … from @perspective-dev/client`. So the 4.5.1/4.4.1 pair
+stays. Don't touch it.
+
+**What to actually do:**
+- Keep the versions as-is; **commit `package-lock.json`** so the resolved set can't drift
+  on `npm install`. (Optionally tighten the carets to exact `4.5.1`/`4.4.1` to make that
+  explicit.)
+- Treat any Perspective bump as gated by the canonical smoke test (§7): a d3fc **chart**
+  renders, dark/light re-themes, and save→reload→drop-column layout restore.
+- Revisit only when `viewer-d3fc` ships a 4.5.x — then a fully-coherent inline-capable
+  4.5.x suite becomes possible and the pair can collapse to one version.