@@ -45,7 +45,7 @@ One new markdown file is enough — the website rebuilds from frontmatter on dep
 - `publisher`: optional. Name the **rights-holding publisher**, never the host. Set it whenever that publisher has more than one catalog entry, so the entries group; setting it on a publisher that currently has only one entry is also fine and saves a backfill later. Do not set it to a generic host (GitHub, Hugging Face, itch.io) or to a distributor that does not hold the rights. Distinguish sibling organisations that are genuinely different rights holders: `blender.md` (the application, Blender Foundation) carries no `publisher`, while the asset bundles under `studio.blender.org` carry `Blender Studio`. Kenney, Quaternius, KayKit, Google Fonts, OpenGameArt, LuizMelo, 0x72, Blender Studio, Material Maker, Alif Type, GGBotNet and 3dmodelscc0 are the largest groups in use today; treat that as illustrative, not as the permitted set.
 - `subcategories`: lower-case kebab-case (`base-meshes`, `field-recordings`). Reuse a value already in the catalog before inventing one, and do not add a variant of an existing value that differs only in plural or spelling. Where both forms were in use, the more common one was kept (`characters`, `environment`, `interior`, `tileset`, `vectors`).
 - `formats`: what you actually get, in one of four kinds. **File formats**, as commonly written: usually upper case (`PNG`, `FBX`, `JSON`, `VOX`), tool-specific ones as the tool writes them (`gdshader`, `tmx`, `ktx2`). **Engine or language targets**, as the product writes them (`glTF`, `Godot`, `Unity`, `Python`, `React`). **Delivery types** for software with no file format of its own, lower-case kebab-case (`godot-addon`, `blender-extension`, `npm`, `cli`, `library`, `desktop-app`, `mobile-app`, `middleware`, `model`). And `various` for an aggregator whose files come in too many formats to list. Platforms (`windows`, `macos`, `ios`) and descriptions (`heightfield`, `examples`) are `tags`, not formats. Reuse the spelling already in the catalog.
-- `grid_dimensions` / `camera_perspective` / `hardware_tags`: optional 2D/UI metadata.
+- `grid_dimensions` / `camera_perspective` / `hardware_tags`: optional metadata for 2D and UI entries. `3d` and `characters` entries leave `camera_perspective` out: it describes a 2D camera, and those entries have none.
 - `verified`: ISO date (`YYYY-MM-DD`) of your last license check.
 - `status`: `active` | `needs-review` | `deprecated`. `active` means the licence, the commercial stance and the credit requirement are all settled: an `unknown` in `license`, `commercial` or `attribution_required` keeps an entry at `needs-review`. The validator enforces this (V14), and rejects `formats` or `subcategories` values that differ only by case, punctuation or a trailing "s" from one already in use (V13).
 
 
@@ -17,8 +17,8 @@ status: active
 # license_spdx: CC0-1.0
 # attribution_string: "Credit line if attribution_required"
 # commercial: varies   # aggregators only; not a blanket commercial grant
-# grid_dimensions: 16x16
-# camera_perspective: top_down   # isometric_3_4 | side_scroller | 2d_flat
+# grid_dimensions: 16x16          # 2D and UI entries only
+# camera_perspective: top_down   # isometric_3_4 | side_scroller | 2d_flat. 2D and UI entries only; 3D and characters leave it out
 # hardware_tags: [steam_deck, switch_2]
 ---
 
 
@@ -13,6 +13,31 @@ Static GitHub Pages UI for this catalog.
 | `site/config.json` → `categories` / `guides` | Labels and guide links |
 | `site/public/*` | Page chrome / design |
 
+## Public JSON
+
+Every deploy publishes the whole catalog as
+[`data.json`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/data.json), for scripts
+and tools that want the metadata without scraping the page. The page itself loads
+`data.js`, the same payload assigned to `window.__CATALOG__`.
+
+- Top-level keys: `generatedAt`, `site`, `categories`, `guides`, `featured`, `stats`,
+  `entries`.
+- Each entry carries its frontmatter fields (`id`, `name`, `url`, `category`,
+  `subcategories`, `license`, `license_spdx` where set, `commercial`,
+  `attribution_required`, `attribution_string` where set, `formats`, `tags`, `verified`,
+  `status`, `publisher` where set, and the optional 2D fields), plus `path` (the entry's
+  file in this repo), `summary` (the first paragraph of its body), and two derived sort
+  fields, `attributionClass` and `licenseRank`.
+- It is regenerated from `catalog/` on every push to `main`. Field names are stable;
+  new optional fields may appear. The licence facts are only as current as each entry's
+  `verified` date: re-check the source before you ship on one.
+
+## Social preview
+
+`docs/images/readme/og-card.png` is a 1200x630 screenshot of this site's first screen.
+`build.mjs` copies it into `dist` and emits the `og:image` and `twitter:image` tags.
+Retake it when the hero changes.
+
 ## Commands
 
 ```bash
 
@@ -14,6 +14,11 @@ const PUBLIC = path.join(__dirname, "public");
 const DIST = path.join(__dirname, "dist");
 const CONFIG_PATH = path.join(__dirname, "config.json");
 const VOCAB_PATH = path.join(__dirname, "license-vocabulary.json");
+// Social preview image: a first-party screenshot of this site, kept with the
+// other first-party stills (the validator allows binaries there) and copied
+// into dist at build time.
+const OG_CARD_NAME = "og-card.png";
+const OG_CARD_SRC = path.join(ROOT, "docs", "images", "readme", OG_CARD_NAME);
 
 /** Sort rank for "license permissiveness": least owed first. */
 const ATTRIBUTION_RANK = { none: 0, notice: 1, required: 2, any: 3 };
@@ -325,10 +330,21 @@ function guideRowsHtml(guides, repo) {
     .join("\n");
 }
 
-function headMetaHtml(site, stats, generatedAt) {
+function headMetaHtml(site, stats, generatedAt, hasCard) {
   const url = site.siteUrl;
   const title = site.title;
   const desc = site.tagline;
+  const card = `${url.replace(/\/+$/, "")}/${OG_CARD_NAME}`;
+  const cardMeta = hasCard
+    ? [
+        `<meta property="og:image" content="${esc(card)}" />`,
+        `<meta property="og:image:width" content="1200" />`,
+        `<meta property="og:image:height" content="630" />`,
+        `<meta property="og:image:alt" content="${esc(`${title}: ${desc}`)}" />`,
+        `<meta name="twitter:card" content="summary_large_image" />`,
+        `<meta name="twitter:image" content="${esc(card)}" />`,
+      ]
+    : [`<meta name="twitter:card" content="summary" />`];
   return [
     `<link rel="canonical" href="${esc(url)}" />`,
     `<meta name="theme-color" content="#1a4d3e" media="(prefers-color-scheme: light)" />`,
@@ -338,7 +354,7 @@ function headMetaHtml(site, stats, generatedAt) {
     `<meta property="og:title" content="${esc(title)}" />`,
     `<meta property="og:description" content="${esc(desc)}" />`,
     `<meta property="og:url" content="${esc(url)}" />`,
-    `<meta name="twitter:card" content="summary" />`,
+    ...cardMeta,
     `<meta name="twitter:title" content="${esc(title)}" />`,
     `<meta name="twitter:description" content="${esc(desc)}" />`,
     `<meta name="generator" content="site/build.mjs ${esc(generatedAt)}" />`,
@@ -441,6 +457,10 @@ function main() {
 
   if (fs.existsSync(DIST)) fs.rmSync(DIST, { recursive: true, force: true });
   copyDir(PUBLIC, DIST);
+  const hasCard = fs.existsSync(OG_CARD_SRC);
+  if (hasCard) fs.copyFileSync(OG_CARD_SRC, path.join(DIST, OG_CARD_NAME));
+  // data.json is the public machine-readable catalog (see site/README.md);
+  // the page itself loads data.js.
   fs.writeFileSync(path.join(DIST, "data.json"), JSON.stringify(payload, null, 2));
   fs.writeFileSync(
     path.join(DIST, "data.js"),
@@ -454,7 +474,7 @@ function main() {
   const stamp = payload.generatedAt.slice(0, 10);
   const visible = entries.filter((e) => e.status !== "deprecated");
   const substitutions = {
-    HEAD_META: headMetaHtml(config.site, stats, payload.generatedAt),
+    HEAD_META: headMetaHtml(config.site, stats, payload.generatedAt, hasCard),
     STARTER_ROWS: starterRowsHtml(featured),
     ENTRY_ROWS: groupedRowsHtml(visible, config.categories, repoUrl, now),
     CATEGORY_CHIPS: categoryChipsHtml(visible, config.categories),
 
@@ -74,7 +74,7 @@ const BINARY_EXT = new Set([
   ".pak",
 ]);
 const SKIP_WALK = new Set([".git", "node_modules", "dist", "RESEARCH"]);
-/** Generated output and README documentation stills — not third-party packs. */
+/** Generated output and first-party stills (README screenshots, the social card): not third-party packs. */
 const ALLOWED_BINARY_PREFIXES = ["site/dist/", "docs/images/readme/"];
 const EMOJI_RE = /\p{Extended_Pictographic}/u;
 const MD_LINK_RE = /!\[[^\]]*\]\(([^)]+)\)|\[[^\]]*\]\(([^)]+)\)/g;