Merge pull request #20 from shotstack/derk/font-family-guidance

[2/2] docs: document filename-first font.family and Roboto fallback

Author: dazzatronus

skills/shotstack/references/fonts.md

@@ -32,7 +32,11 @@ Load a font from a public URL via `timeline.fonts[]`, then reference its **file
 }
 ```
 
-The `font.family` value is the URL's filename without extension, and it **must** match the URL's basename exactly. For URL `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf`, family = `JTUSjIg1_i6t8kCHKm45xW5rygbi49c`. If `family` and the URL basename diverge, the font silently fails to load.
+The `font.family` value is the URL's filename without extension, matched ignoring case (a `-Regular` or `-Bold` style suffix can also be dropped). For URL `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf`, family = `JTUSjIg1_i6t8kCHKm45xW5rygbi49c`.
+
+The family name stored inside the font file also matches, but it isn't always the name on Google Fonts: a variable font whose default weight isn't Regular stores the weight too (Space Grotesk's file calls itself `Space Grotesk Light`). Prefer the filename, which can't differ from what you loaded.
+
+A `font.family` that matches nothing renders in Roboto without a render error. The exception is a lone entry in `timeline.fonts[]`, which is used whatever `font.family` says, so a wrong name stays hidden until a second font is added. `shotstack validate` warns on any `font.family` that isn't a built-in or a loaded filename.
 
 ## Verified font catalogue
 
@@ -77,9 +81,9 @@ These twelve fonts are pre-installed in the render engine and don't need a `time
 
 The renderer accepts both spaced (`Open Sans`) and concatenated (`OpenSans`) family names for these.
 
-## Why system fonts fail
+## Why system fonts don't work
 
-System fonts like `Arial`, `Helvetica`, `Times New Roman`, `Courier New`, etc. are **not installed** on the render engine. Using them produces a "Font not found" error at render time.
+System fonts like `Arial`, `Helvetica`, `Times New Roman`, `Courier New`, etc. are **not installed** on the render engine. Text set in them renders in Roboto, with no render error.
 
 **Wrong:**
 

skills/shotstack/references/timeline.md

@@ -114,7 +114,7 @@ Custom fonts loaded from a URL, available to all `rich-text` and `rich-caption`
 }
 ```
 
-The `font.family` you reference in an asset must be the **basename of the file** (without `.ttf`/`.otf`/`.woff`).
+Reference a loaded font in `font.family` by the **basename of the file** (without `.ttf`/`.otf`/`.woff`). It always matches; a family that matches nothing renders in Roboto without an error.
 
 For the Montserrat URL above, `font.family` is `JTUSjIg1_i6t8kCHKm45xW5rygbi49c`.
 

skills/shotstack/references/troubleshooting.md

@@ -7,7 +7,7 @@ Common errors and the fix for each. **Catch most of them before rendering:** `sh
 - "Unknown property: alignment" / wrong property names
 - "Invalid option: expected one of top|middle|bottom"
 - Video looks stretched / squishing after rendering
-- "Font not found"
+- Text renders in Roboto instead of your font
 - Captions cover the whole frame
 - Clips flicker / "clips overlap" on one track
 - Timeline renders but layers are wrong
@@ -54,11 +54,11 @@ The Shotstack `fit` enum is **inverted from CSS**:
 
 **Fix:** use `fit: "crop"` (or omit `fit` — `crop` is the default) for the typical "scale and crop" behaviour you'd expect from CSS `object-fit: cover`.
 
-## "Font not found"
+## Text renders in Roboto instead of your font
 
-You used a font name that isn't in the built-in list and didn't load it via `timeline.fonts[]`.
+`font.family` didn't match any font, so the renderer fell back to Roboto without an error. Either the font isn't built in and wasn't loaded via `timeline.fonts[]`, or `family` doesn't match the loaded font: a typo, or a name that differs from the one stored in the font file.
 
-**Fix:** add the font URL to `timeline.fonts[]` and use the file basename as `family`. See `references/fonts.md`. If you really need a system font, use `Roboto` (built-in) as a substitute.
+**Fix:** add the font URL to `timeline.fonts[]` and use the file basename as `family`. `shotstack validate` flags a `family` that isn't a built-in or a loaded filename. See `references/fonts.md`. If you really need a system font, use `Roboto` (built-in) as a substitute.
 
 ## Captions cover the whole frame
 

skills/shotstack/shared/agent-core.md

@@ -264,7 +264,7 @@ One overlay is a `rich-text` job. **Several videos "in different styles" is not*
 
 ## Fonts
 
-Use **custom Google Fonts via `timeline.fonts[]`**. System fonts (`Arial`, `Helvetica`, `Times New Roman`) are NOT installed and will fail with "Font not found".
+Use **custom Google Fonts via `timeline.fonts[]`**. System fonts (`Arial`, `Helvetica`, `Times New Roman`) are NOT installed; text set in them renders in Roboto, with no render error.
 
 **CRITICAL: Do NOT construct or fabricate Google Fonts URLs from memory.** Google rotates them (`v26 → v31 → ...`) and the hash filenames change with each version. Any URL you reconstruct from training data is almost certainly a 404. **Use ONLY the verified entries below, copied verbatim.**
 
@@ -313,7 +313,7 @@ Variable fonts cover the full weight range (100–900) from a single URL — set
 }
 ```
 
-The `font.family` value MUST match the `family` column in the table above (it's the filename basename without `.ttf`). If `family` and the URL's basename don't match, the font will not load.
+Use the `family` column from the table above: the URL's filename without `.ttf`, matched ignoring case. The family name stored inside the font file also matches, but it isn't always the name on Google Fonts (Space Grotesk's file calls itself `Space Grotesk Light`), so the filename is the safe choice. A `font.family` that matches nothing renders in Roboto with no error. The exception is a lone entry in `timeline.fonts[]`, which is used whatever `font.family` says, so a wrong name only shows once a second font is added. `shotstack validate` warns on any `font.family` that isn't a built-in or a loaded filename.
 
 ## Top 5 mistakes