From c9c53bc772d30c1573e78a9a518184a57cb51b4d Mon Sep 17 00:00:00 2001
From: Sebastian Legarraga <64795732+slegarraga@users.noreply.github.com>
Date: Thu, 6 Aug 2026 18:58:04 -0400
Subject: [PATCH] docs: document compare and share URL patterns

Signed-off-by: Sebastian Legarraga <64795732+slegarraga@users.noreply.github.com>
---
 README.md       |  2 +-
 docs/SHARING.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 docs/SHARING.md

diff --git a/README.md b/README.md
index 75ea0cb..fc1ab2d 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ Open-source catalog for MSP edge hardware — **Peplink**, **Starlink**, and **F
 
 - Typed product catalog (`src/data/catalog/`) — no database
 - Compare up to four devices · CSV / Markdown / print PDF
-- **Share links** — product or compare URL with an optional note for recipients (`?m=…` on the link)
+- **Share links** — product or compare URL with an optional note for recipients (`?m=…` on the link). See [`docs/SHARING.md`](docs/SHARING.md) for exact URL patterns and real examples.
 - Command palette (⌘K) · favorites & recent views in `localStorage`
 - Site brief — requirements checklist with multi-device links
 - SEO: sitemap, product metadata, JSON-LD, **favicon**, and **social preview images** (per product + compare)
diff --git a/docs/SHARING.md b/docs/SHARING.md
new file mode 100644
index 0000000..3baea5c
--- /dev/null
+++ b/docs/SHARING.md
@@ -0,0 +1,56 @@
+# Sharing URLs for teams
+
+DeviceView supports stable share links for a single product and for a side-by-side comparison. The paths are safe to paste in Slack, WhatsApp, email, or a ticket because the app renders static product data and keeps user state in the browser.
+
+## Product link
+
+Use the product path:
+
+```text
+/products/<slug>
+```
+
+Real examples:
+
+- `/products/peplink-balance-310`
+- `/products/starlink-mini-kit`
+- `/products/fortinet-fortigate-60f`
+
+The slug is the stable URL for that device. Do not rename a slug without adding a redirect in `next.config.ts`, because existing share links and bookmarks depend on it.
+
+## Comparison link
+
+Compare up to four products with the `p` query parameter:
+
+```text
+/compare?p=slug1,slug2,slug3,slug4
+```
+
+Real example:
+
+```text
+/compare?p=peplink-balance-310,peplink-balance-310x,starlink-mini-kit,fortinet-fortigate-60f
+```
+
+Slugs are comma-separated. Extra slugs beyond the first four are ignored by the app.
+
+## Optional share note
+
+Add an optional client-side note with `m`:
+
+```text
+/products/peplink-balance-310?m=<base64url-note>
+/compare?p=peplink-balance-310,peplink-balance-310x&m=<base64url-note>
+```
+
+The note is base64url-encoded, capped at 480 characters, and shown as an in-app banner to the recipient. It is client-only by design: link crawlers ignore it for Open Graph previews.
+
+## Open Graph previews
+
+Product links use the per-product Open Graph image, and comparison links use `/og/compare?p=...`. Both are generated from absolute URLs, so `NEXT_PUBLIC_SITE_URL` must point to the production origin with no trailing slash:
+
+```bash
+NEXT_PUBLIC_SITE_URL=https://deviceview.example.com
+```
+
+When pasting a share link, use the full deployed URL (`https://deviceview.example.com/products/...`) rather than a local path.