fontisan 0.4.7 → 0.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9957716f86dad58d8ff9b5f0bc49bc7044ab20f073bd26b5b87f09d8a5aa1cb1
-  data.tar.gz: 5ac5083c8db47532bc1331c82209c02bc6d8b7095b8f2c27c41fecced8230b32
+  metadata.gz: 38b49343b74d1876d57ec13992fc49fdc2879a44d1f0fe3c6529bd3a2f8f7a75
+  data.tar.gz: cc69156566e86294177d9046f39ebde8334f87807da38a7a5dd83ddd2eea8247
 SHA512:
-  metadata.gz: e1fa7608f49e922735d6b677456cbf4864ced9a32e3e771960229f685208c67be6079f9b1bfcfc6f393c83bf8d5b7e0e158c397b618080229a14dd274718724e
-  data.tar.gz: 730148059f3819b6dd49c1f8b86ab9d2e4d8508671b54b59cc240e638472b0da0dd5e5b7187f30b09bbd12d8e149a93903097068a45ac281224f2482464fa2ea
+  metadata.gz: 2822ae02861c4183bbd42ded8005fa17d28d59175155767413f94b4400faaf28fb61dad38736f3fcd11235746e1b254151c8e8918480b5ccb146882742c3ec99
+  data.tar.gz: eefb0dbf8e3360e7b8aeb89dfcfbf62425c255075ee1a3d2c030cd2551f90f08d980f7ea7b8c56c382b0a1cb69933654a57fc4e57d069ebe6809ace84e7d0b42

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+
+- Audit/UCD documentation residue from the v0.3.0 audit/UCD subsystem
+  removal: deleted `docs/cli/audit.md`, dropped the "🔍 Font Audit"
+  feature card and "Font Audit" sidebar group, removed audit entries
+  from `docs/cli/index.md`. No behavior change.
+- CLDR subsystem (`Fontisan::Cldr`, `Models::Cldr::LanguageCoverage`,
+  `lib/fontisan/config/cldr.yml`) and the `fontisan cldr` CLI
+  subcommand. CLDR was added in TODO 21 as infrastructure for
+  `fontisan audit`'s per-language coverage extractor; with the audit
+  subsystem moved to ucode (v0.3.0), CLDR had no remaining consumer
+  in fontisan. Not released in a published gem version.
+
 ### Added
 
 - `Stitcher` explicit subfont declaration model: every `include_*`

data/README.adoc

@@ -1260,6 +1260,42 @@ Status: INVALID
 ----
 ====
 
+=== Collection structural validation (`validate-collection`)
+
+For collection-level structural checks (face count, per-face glyph cap,
+optional cmap-union size) without running the full per-face profile
+machinery, use the dedicated `validate-collection` command:
+
+[source,shell]
+----
+# Glyph-cap-only check (default)
+fontisan validate-collection family.ttc
+
+# Require exactly 5 faces
+fontisan validate-collection family.ttc --expected-faces 5
+
+# Tighter per-face glyph cap + minimum cmap coverage
+fontisan validate-collection family.ttc \
+  --max-glyphs 60000 \
+  --expected-cmap-union 100000
+----
+
+Exit code is `0` when every requested check passes, `1` when any
+check fails. With no options, only the per-face glyph cap is checked
+(default `65,535`).
+
+This command is intentionally separate from `fontisan validate PATH`
+(MECE): `validate` runs profile-based per-face checks;
+`validate-collection` runs collection-level structural checks. They
+do not share a subcommand tree.
+
+For programmatic access to the same metadata, see
+`Fontisan::Collection::Reader` — the read-only counterpart to
+`Collection::Builder`. It opens a TTC/OTC/dfont and exposes
+`face_count`, per-face `stats` (glyph/codepoint counts), and the
+cmap union across all faces, without hand-rolling the TTC header
+bytes.
+
 === Ruby API usage
 
 ==== Architecture
@@ -2187,6 +2223,29 @@ fontisan convert font.ttf --to woff2 --output font.woff2 \
 fontisan convert font.ttf --to woff --output font.woff --zlib-level 9
 ----
 
+`--to` accepts multiple targets so a single invocation produces N
+output files from one input font. Pass a comma-separated list
+(`--to woff,woff2`) or repeat the flag (`--to woff --to woff2`).
+Duplicates are deduplicated.
+
+[source,shell]
+----
+# Emit both WOFF and WOFF2 in one invocation
+fontisan convert font.ttf --to woff,woff2 --output font
+# → font.woff, font.woff2
+----
+
+Output-path rules for multi-format:
+
+* `--output out` (no extension) + N formats → append `.<format>` per
+  target (`out.woff`, `out.woff2`).
+* `--output out.ttf` (extension present) + N formats → exits 1
+  (ambiguous which format gets the extension).
+* `--output out.ttf` + one format → use as given (existing behaviour).
+
+Multi-format is single-font → single-font only. Combining multi-format
+with collection input (TTC/OTC/dfont) exits 1.
+
 For detailed information on all available options and conversion scenarios,
 see the link:docs/CONVERSION_GUIDE.adoc[Conversion Guide].
 
@@ -2499,8 +2558,63 @@ stitcher.add_source(:noto_cjk, Fontisan::FontLoader.load("NotoSansCJK.ttf"))
 stitcher.include_range(0x41..0x5A, from: :noto_sans, into: :latin)
 stitcher.include_range(0x4E00..0x9FFF, from: :noto_cjk, into: :cjk)
 
-# Write as OTC with CFF2 subfonts and table deduplication
-stitcher.write_collection("out.otc", format: :otf2)
+# Write as OTC with CFF2 subfonts and table deduplication.
+# Returns a Stitcher::CollectionResult (path, bytes, per-subfont stats).
+result = stitcher.write_collection("out.otc", format: :otf2)
+result.face_count                 # => 2
+result.subfonts.map(&:name)       # => [:latin, :cjk]
+result.subfonts.first.glyph_count # maxp.num_glyphs of face 0
+----
+
+=== Donor maps and partitioning
+
+`include_codepoints_map(cp_map, into:)` takes a `{codepoint => donor}`
+map and groups internally — one call handles N codepoints from M
+donors:
+
+[source,ruby]
+----
+stitcher.include_codepoints_map(
+  { 0x41 => :noto_sans, 0x4E00 => :noto_cjk },
+  into: :main,
+)
+----
+
+For automatic plane-aware splitting, use
+`Stitcher::PartitionStrategy::ByPlane`. It groups codepoints by
+Unicode plane and sub-splits planes that overflow the cap along the
+large CJK-extension block boundaries:
+
+[source,ruby]
+----
+require "fontisan/stitcher/partition_strategy"
+
+blueprint = Fontisan::Stitcher::PartitionStrategy::ByPlane.new
+             .call(cp_map, cap: 65_484)
+blueprint.apply_to(stitcher) # declares one subfont per partition
+----
+
+If a single CJK extension block alone exceeds the cap, ByPlane raises
+`Fontisan::PartitionCapExceededError`. ByBlock/ByScript partitioners
+(via Unicode Blocks.txt / Scripts.txt) are tracked as a follow-up —
+the framework is open for them.
+
+=== Per-subfont metadata
+
+`Ufo::Info.for_subfont(family:, subfont:, version:, ...)` builds the
+standard name-table fields for one subfont of a collection. The
+family name embeds the subfont (`"essenfont SIP"`), the PostScript
+name uses the hyphenated form (`"essenfont-SIP"`), and the version is
+parsed into `version_major` / `version_minor` per the UFO
+major.minor shape.
+
+[source,ruby]
+----
+stitcher.set_info(
+  Fontisan::Ufo::Info.for_subfont(
+    family: "essenfont", subfont: :SIP, version: "0.1"
+  ).to_plist,
+)
 ----
 
 === CBDT/CBLC passthrough (color emoji)

data/docs/.vitepress/config.ts

@@ -263,13 +263,6 @@ export default defineConfig({
             { text: "Overview", link: "/cli/" },
           ],
         },
-        {
-          text: "Font Audit",
-          collapsed: true,
-          items: [
-            { text: "audit", link: "/cli/audit" },
-          ],
-        },
         {
           text: "Font Information",
           collapsed: true,
@@ -292,6 +285,7 @@ export default defineConfig({
             { text: "convert", link: "/cli/convert" },
             { text: "subset", link: "/cli/subset" },
             { text: "validate", link: "/cli/validate" },
+            { text: "validate-collection", link: "/cli/validate-collection" },
             { text: "instance", link: "/cli/instance" },
             { text: "export", link: "/cli/export" },
             { text: "dump-table", link: "/cli/dump-table" },

data/docs/COLLECTION_VALIDATION.adoc

@@ -141,3 +141,64 @@ puts "Valid fonts: #{valid_count}"
 puts "Invalid fonts: #{invalid_count}"
 ----
 ====
+
+== Fast structural checks: `validate-collection`
+
+For collection-level structural checks (face count, per-face glyph
+cap, optional cmap-union size) without running the full per-face
+profile machinery, use the dedicated `validate-collection` command:
+
+[source,shell]
+----
+# Glyph-cap-only check (default)
+fontisan validate-collection family.ttc
+
+# Require exactly 5 faces
+fontisan validate-collection family.ttc --expected-faces 5
+
+# Tighter per-face glyph cap + minimum cmap coverage
+fontisan validate-collection family.ttc \
+  --max-glyphs 60000 \
+  --expected-cmap-union 100000
+----
+
+Exit code is `0` when every requested check passes, `1` when any
+check fails. With no options, only the per-face glyph cap is checked
+(default `65,535`).
+
+This command is intentionally separate from `fontisan validate PATH`
+(MECE): the two cover different validator categories — `validate`
+runs profile-based per-face checks, `validate-collection` runs
+collection-level structural checks. They don't share a subcommand tree.
+
+== Reading collection metadata: `Collection::Reader`
+
+`Fontisan::Collection::Reader` is the read-only counterpart to
+`Collection::Builder`. It opens an existing TTC/OTC/dfont and
+exposes per-face metadata plus the cmap union across all faces,
+without hand-rolling the TTC header bytes.
+
+[source,ruby]
+----
+reader = Fontisan::Collection::Reader.open("family.ttc")
+
+reader.face_count                  # => 3
+reader.path                        # => "family.ttc"
+
+reader.each_face do |face|
+  puts face.table("maxp").num_glyphs
+end
+
+# One Stats struct per face (index, glyph_count, codepoint_count, sfnt_version)
+reader.stats.map(&:glyph_count)    # => [3541, 21048, 991]
+
+# Union of every face's cmap keys
+reader.cmap_union.size             # => 24580
+reader.cmap_union.is_a?(Set)       # => true
+----
+
+`Reader` delegates header parsing to `FontLoader` (which already
+handles TTC, OTC, and dfont via `BinData`). Constructing a `Reader`
+on a non-collection file raises `ArgumentError`. This is the API the
+`validate-collection` command uses internally — reach for it directly
+when you want collection metadata without invoking the CLI.

data/docs/STITCHER_GUIDE.adoc

@@ -25,15 +25,19 @@ There are no defaults and no after-the-fact splitting.
 
 | `include_codepoints(cps, from:, into:)` | Add an explicit Array of codepoints
 
+| `include_codepoints_map(cp_map, into:)` | Add `{codepoint => donor}` for many codepoints and donors in one call
+
 | `include_gid(donor_gid, from:, into:)` | Add a specific GID from the source
 
 | `include_notdef(from:, into:)` | Convenience for `include_gid(0, ...)`
 
 | `set_info(hash)` | Override font info (family name, etc.)
 
+| `subfont_names` | List declared subfont names (insertion order)
+
 | `write_to(path, format:, subfont:)` | Compile one subfont to a single file
 
-| `write_collection(path, format:)` | Compile all declared subfonts into a TTC/OTC
+| `write_collection(path, format:)` | Compile all declared subfonts into a TTC/OTC; returns a `CollectionResult`
 |===
 
 `format:` is one of `:ttf`, `:otf`, `:otf2`. For collections, `:ttf`
@@ -77,6 +81,139 @@ Each subfont is compiled independently, then packed by
 (head, name, OS/2, ...) are stored once and referenced from each
 subfont's offset table.
 
+`write_collection` returns a `Stitcher::CollectionResult` Struct with
+the output `path`, total `bytes`, and one `Stitcher::SubfontStats`
+per declared subfont (`name`, `glyph_count`, `codepoint_count`). Stats
+are read from the compiled on-disk face so they reflect what was
+actually written — including glyphs the compiler adds (e.g. `.notdef`).
+
+[source,ruby]
+----
+result = stitcher.write_collection("out.otc", format: :otf2)
+result.path          # => "out.otc"
+result.bytes         # => File.size("out.otc")
+result.face_count    # => result.subfonts.size
+result.subfonts.first.glyph_count     # maxp.num_glyphs of face 0
+result.subfonts.first.codepoint_count # cmap size of face 0
+----
+
+== Donor maps (many codepoints, many donors, one call)
+
+`include_codepoints_map(cp_map, into:)` takes a `{codepoint => donor}`
+map and forwards each donor group to `include_codepoints` after sorting
+the codepoints (reproducible GID assignment). Useful when the cp →
+donor routing comes from an external plan (Unicode block table,
+partitioner output, coverage analysis).
+
+[source,ruby]
+----
+cp_map = {
+  0x41    => :latin,
+  0x42    => :latin,
+  0x4E00  => :cjk,
+  0x4E01  => :cjk,
+}
+stitcher.include_codepoints_map(cp_map, into: :main)
+# equivalent to:
+#   stitcher.include_codepoints([0x41, 0x42], from: :latin, into: :main)
+#   stitcher.include_codepoints([0x4E00, 0x4E01], from: :cjk,  into: :main)
+----
+
+== Codepoint partitioning (PartitionStrategy)
+
+When the codepoint set is too large for one subfont (or when you want
+to split by Unicode plane / block / script for organizational reasons),
+`Stitcher::PartitionStrategy` provides ready-to-use partitioner classes
+that produce a `Blueprint` (an ordered list of `Partition`s). Each
+partition names a target subfont and carries its codepoints and
+donor map.
+
+The framework is open for new partitioners — adding one is a new file
+under `lib/fontisan/stitcher/partition_strategy/` plus an autoload
+entry. No edits to existing partitioners required (OCP).
+
+=== ByPlane
+
+Groups codepoints by Unicode plane (`cp >> 16`). Each plane that fits
+under the cap becomes one partition named `:plane_<n>` (e.g.
+`:plane_0` for BMP, `:plane_2` for SIP). When a plane overflows the
+cap, ByPlane sub-splits along the large CJK-extension block
+boundaries (`CJK_Ext_B` through `CJK_Ext_F`), naming partitions
+`:plane_<n>_a`, `:plane_<n>_b`, etc.
+
+[source,ruby]
+----
+require "fontisan/stitcher/partition_strategy"
+
+cp_map = build_coverage_map  # { codepoint => donor_label, ... }
+blueprint = Fontisan::Stitcher::PartitionStrategy::ByPlane.new
+             .call(cp_map, cap: 65_484)
+
+blueprint.names       # => [:plane_0, :plane_2, ...]
+blueprint.partitions  # => [#<Partition name=:plane_0 cps=[...] ...>, ...]
+
+# Push every partition's bindings into the Stitcher in one go:
+declared = blueprint.apply_to(stitcher)
+# declared == blueprint.names
+----
+
+If a single CJK extension block alone exceeds `cap` (e.g. `CJK_Ext_B`
+has ~6,592 codepoints and the cap is set to 5,000), ByPlane raises
+`Fontisan::PartitionCapExceededError` — its codepoints are contiguous
+and ByPlane has no finer-grained boundary to sub-split on. The caller
+must either raise the cap, drop codepoints, or switch to a format
+with a higher glyph limit.
+
+The Unicode plane metadata used by ByPlane lives in
+`Fontisan::Unicode::Plane` (`Plane.of(cp)`, `Plane.label(n)`,
+`Plane::LARGE_CJK_BLOCKS`).
+
+=== Partition / Blueprint
+
+A `Partition` is a `Struct.new(:name, :cps, :donor_map, keyword_init: true)`.
+`Partition#apply_to(stitcher)` pushes its bindings via
+`include_codepoints_map`.
+
+A `Blueprint` is a `Struct.new(:partitions, keyword_init: true)`;
+`Blueprint#apply_to(stitcher)` calls `apply_to` on each partition in
+order and returns the list of declared subfont names.
+
+=== Future: ByBlock, ByScript
+
+ByBlock (Unicode Blocks.txt, ~350 entries) and ByScript (Scripts.txt)
+are tracked as a follow-up. The framework is already open for them:
+add `by_block.rb` / `by_script.rb` under
+`lib/fontisan/stitcher/partition_strategy/` and an autoload entry in
+`partition_strategy.rb`.
+
+== Per-subfont metadata (Ufo::Info.for_subfont)
+
+`Fontisan::Ufo::Info.for_subfont(family:, subfont:, version:, ...)`
+builds the standard name-table fields for one subfont of a collection.
+The family name embeds the subfont name (e.g. `"MyFont CJK"`), and
+the PostScript name uses the hyphenated form (e.g. `"MyFont-CJK"`).
+`version` is parsed into `version_major` / `version_minor` per the
+UFO major.minor shape (semver patch is dropped).
+
+[source,ruby]
+----
+info = Fontisan::Ufo::Info.for_subfont(
+  family:   "essenfont",
+  subfont:  :SIP,
+  version:  "0.1",
+)
+info.family_name           # => "essenfont SIP"
+info.postscript_font_name  # => "essenfont-SIP"
+info.postscript_full_name  # => "essenfont SIP"
+info.version_major         # => 0
+info.version_minor         # => 1
+----
+
+Optional kwargs: `subfamily:` (default `"Regular"`), `copyright:`,
+`trademark:`. `trademark` lands in `extras["openTypeNameTrademark"]`
+because it is not in `Ufo::Info::STANDARD_FIELDS` yet — round-trip
+still works through the extras channel.
+
 == Glyph deduplication
 
 By default the Stitcher deduplicates glyphs across all sources using

data/docs/cli/convert.md

@@ -32,8 +32,8 @@ These are individual font formats that can be converted:
 
 | Option | Description |
 |--------|-------------|
-| `--to FORMAT` | Target format (ttf, otf, woff, woff2) |
-| `--output FILE` | Output file path |
+| `--to FORMAT[,FORMAT...]` | Target format(s): `ttf`, `otf`, `woff`, `woff2`, `type1`/`t1`, `ttc`, `otc`, `dfont`, `svg`. Pass once with comma-separated values (`--to woff,woff2`) or multiple times (`--to woff --to woff2`) for multi-format output. |
+| `--output FILE` | Output file path (see "Output path rules" below) |
 | `--optimize` | Enable outline optimization |
 | `--flatten` | Flatten composite glyphs |
 | `--zlib-level=N` | WOFF only: zlib compression level (0–9, default 6) |
@@ -46,6 +46,37 @@ The format you pick (`--to woff` vs `--to woff2`) **is** the algorithm
 choice — WOFF mandates zlib, WOFF2 mandates Brotli. Passing a WOFF knob
 to a WOFF2 target (or vice versa) exits 1 with a clear error.
 
+## Multi-format output
+
+`--to` accepts multiple targets so a single invocation produces N
+output files from one input font. Both spellings work and produce
+identical results:
+
+```bash
+# Comma-separated (one --to flag)
+fontisan convert font.ttf --to woff,woff2 --output font
+
+# Repeated flag (Thor array form)
+fontisan convert font.ttf --to woff --to woff2 --output font
+```
+
+Duplicates are deduplicated, so `--to woff,woff2,woff` is equivalent to
+`--to woff,woff2`.
+
+### Output path rules
+
+| `--output` shape | `--to` shape | Behaviour |
+|------------------|--------------|-----------|
+| `out.ttf` (has extension) | one format | Use as given |
+| `out` (no extension) | one format | Append `.<format>` → `out.ttf` |
+| `out` (no extension) | many formats | Append `.<format>` per target → `out.woff`, `out.woff2` |
+| `out.ttf` (has extension) | many formats | **Error**: ambiguous which format gets the extension |
+
+Multi-format is single-font → single-font only. Combining multi-format
+with collection input (TTC/OTC/dfont) exits 1 — collections pack
+multiple faces and N formats × M faces explodes output count. Convert
+collections to one target format at a time.
+
 ## Common Workflows
 
 ### Convert for Web
@@ -85,6 +116,17 @@ fontisan convert font.otf --to ttf --output font.ttf
 fontisan convert font.pfb --to otf --output font.otf
 ```
 
+### Emit Multiple Web Formats in One Invocation
+
+```bash
+# Both WOFF (legacy IE9+) and WOFF2 (modern browsers) from one input
+fontisan convert font.ttf --to woff,woff2 --output font
+# → font.woff, font.woff2
+
+# Same result with the repeated-flag form
+fontisan convert font.ttf --to woff --to woff2 --output font
+```
+
 ## Working with Collections
 
 Collection formats (TTC, OTC, dfont) contain multiple fonts. To convert fonts from a collection:

data/docs/cli/index.md

@@ -20,18 +20,6 @@ Always check your font's End User License Agreement (EULA) before processing. Ma
 
 ## Quick Reference
 
-### Font Audit
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `audit` | Comprehensive per-face audit (replaces `otfinfo`) | `fontisan audit font.ttf` |
-
-The `audit` command covers identity, style, metrics, codepoint coverage,
-licensing, hinting, color capabilities, variable-font detail, and
-OpenType layout — and supports collections, `--compare` mode, and
-whole-library `--recursive --summary` mode. See
-[audit](/cli/audit) for details.
-
 ### Font Information Commands
 
 | Command | Description | Example |
@@ -52,7 +40,8 @@ whole-library `--recursive --summary` mode. See
 |---------|-------------|---------|
 | `convert` | Convert between formats | `fontisan convert input.ttf --to otf` |
 | `subset` | Subset fonts | `fontisan subset font.ttf --chars "ABC"` |
-| `validate` | Validate fonts | `fontisan validate font.ttf` |
+| `validate` | Validate single-font or per-face quality | `fontisan validate font.ttf` |
+| `validate-collection` | Structural checks on a TTC/OTC/dfont | `fontisan validate-collection fonts.ttc --expected-faces 5` |
 | `instance` | Generate variable font instances | `fontisan instance var.ttf --wght 700` |
 | `dump-table` | Extract raw table data | `fontisan dump-table font.ttf head` |
 
@@ -132,6 +121,10 @@ fontisan unicode font.ttf
 ```bash
 # Convert single font to WOFF2
 fontisan convert font.ttf --to woff2 --output font.woff2
+
+# Emit both WOFF and WOFF2 in one invocation
+fontisan convert font.ttf --to woff,woff2 --output font
+# → font.woff, font.woff2
 ```
 
 ### Work with Variable Fonts
@@ -177,21 +170,23 @@ fontisan validate font.ttf --profile google_fonts
 fontisan validate font.ttf --profile production
 ```
 
-### Audit a Font (or Library)
+### Validate Collection Structure
 
 ```bash
-# Full per-face audit
-fontisan audit font.ttf
+# Glyph-cap-only check (default behaviour)
+fontisan validate-collection family.ttc
 
-# Diff two fonts (or saved reports)
-fontisan audit --compare baseline.yaml new.ttf
+# Require exactly 5 faces, max 60,000 glyphs per face
+fontisan validate-collection family.ttc --expected-faces 5 --max-glyphs 60000
+```
 
-# Whole-library summary
-fontisan audit lib/ --recursive --summary
+### Audit a Font (or Library)
 
-# Fast inventory pass
-fontisan audit lib/ --recursive --summary --brief
-```
+The `audit` and `ucd` commands have been removed from fontisan. The
+audit/UCD subsystem moved to the
+[ucode](https://github.com/fontist/ucode) gem. For per-face font
+metadata, use [`info`](/cli/info); for pass/fail quality checks, use
+[`validate`](/cli/validate).
 
 ### Export Font Data
 
@@ -210,9 +205,6 @@ fontisan export font.ttf --format ttx --tables head,name,cmap
 
 Detailed documentation for each command:
 
-### Font Audit
-- [audit](/cli/audit) — Comprehensive per-face audit (replaces `otfinfo`); supports collections, compare, library summary
-
 ### Font Information
 - [info](/cli/info) — Extract font metadata and properties (includes brief mode)
 - [ls](/cli/ls) — List fonts in collections
@@ -225,9 +217,10 @@ Detailed documentation for each command:
 - [optical-size](/cli/optical-size) — Display optical size information
 
 ### Font Operations
-- [convert](/cli/convert) — Format conversion (TTF, OTF, WOFF, WOFF2)
+- [convert](/cli/convert) — Format conversion (TTF, OTF, WOFF, WOFF2); supports multi-format output
 - [subset](/cli/subset) — Create character subsets
-- [validate](/cli/validate) — Validate fonts against profiles
+- [validate](/cli/validate) — Per-face profile validation
+- [validate-collection](/cli/validate-collection) — Structural checks on TTC/OTC/dfont (face count, glyph cap, cmap union)
 - [instance](/cli/instance) — Generate static instances from variable fonts
 - [export](/cli/export) — Export to TTX, YAML, JSON
 - [dump-table](/cli/dump-table) — Extract raw binary table data

data/docs/cli/validate-collection.md

@@ -0,0 +1,95 @@
+---
+title: validate-collection
+---
+
+# validate-collection
+
+Validate the structural integrity of a TTC / OTC / dfont collection:
+face count, per-face glyph cap, and optional cmap-union size.
+
+This is a collection-level counterpart to
+[validate](/cli/validate), which runs profile-based per-face quality
+checks (OpenType compliance, hint validity, etc.). Use
+`validate-collection` when you care about the *shape* of the
+collection (number of faces, glyph-cap overflows, codepoint coverage)
+rather than per-face quality.
+
+## Quick Reference
+
+```bash
+fontisan validate-collection <path> [options]
+```
+
+The command exits `0` when every requested check passes and `1` when
+any check fails. With no options, only the per-face glyph cap is
+checked (default `65,535`).
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--expected-faces N` | (none) | Require exactly `N` faces in the collection. |
+| `--max-glyphs N` | `65535` | Per-face glyph cap (`maxp.numGlyphs`). Faces over this cap fail. |
+| `--expected-cmap-union N` | (none) | Require the union of cmap codepoints across all faces to be at least `N`. |
+
+## Examples
+
+```bash
+# Glyph-cap-only check (default behaviour, no optional checks)
+fontisan validate-collection family.ttc
+
+# Require exactly 5 faces
+fontisan validate-collection family.ttc --expected-faces 5
+
+# Tighter per-face glyph cap
+fontisan validate-collection family.ttc --max-glyphs 60000
+
+# Require at least 100,000 codepoints covered across all faces
+fontisan validate-collection family.ttc --expected-cmap-union 100000
+```
+
+## Sample output
+
+```
+face 0:    3541 glyphs ✓
+face 1:   21048 glyphs ✓
+face 2:     991 glyphs ✓
+all 3 faces within 65535-glyph cap ✓
+face_count: ✓
+cmap union: 24580 cps ✓
+```
+
+When a check fails, the marker becomes `✗` and a message is printed
+in parentheses; the exit code is `1`.
+
+## Programmatic access
+
+The command is a thin wrapper around
+`Fontisan::Collection::Reader`, which exposes per-face metadata
+directly:
+
+```ruby
+reader = Fontisan::Collection::Reader.open("family.ttc")
+reader.face_count                  # => 3
+reader.stats.map(&:glyph_count)    # => [3541, 21048, 991]
+reader.cmap_union.size             # => 24580
+```
+
+Use the command-class directly when you want structured results
+without stdout:
+
+```ruby
+cmd = Fontisan::Commands::ValidateCollectionCommand.new(
+  input: "family.ttc",
+  expected_faces: 3,
+)
+exit_code = cmd.run           # 0 or 1
+cmd.checks                    # => [#<Check name=:face_count passed=true ...>, ...]
+```
+
+## See also
+
+- [validate](/cli/validate) — per-face profile-based checks (OpenType
+  compliance, hint validity, etc.)
+- [pack](/cli/pack) / [unpack](/cli/pack) — create and extract
+  collections