arrolio 0.1.0

data/TODO.complete/53-second-flavor-spike.md

@@ -0,0 +1,74 @@
+---
+priority: P0
+impact: high
+depends_on: [52]
+layer: architecture
+status: done
+est: 2d
+---
+
+## Problem
+
+The generic pipeline handled only one real flavor (OIML). Without a
+second flavor implemented using only XSL + 3 generated YAML files, the
+"any flavor is pure configuration" claim was unverified.
+
+## Approach
+
+Created a synthetic second flavor at
+`spec/fixtures/flavors/altvocab/` with a deliberately non-Metanorma
+vocabulary:
+
+| Role | sample (standoc) | altvocab |
+|------|------------------|----------|
+| Container | `metanorma` | `article` |
+| Metadata | `bibdata` | `meta` |
+| Sections container | `sections` | `body` |
+| Section | `clause` | `sec` |
+| Heading | `fmt-title` (depth) | `h2` (level) |
+| Paragraph | `p` | `para` |
+| List item | `li` | `li` (same) |
+| Marker | `fmt-name` | `marker` |
+| Note label | `fmt-name` | `label` |
+| Figure image | `image` | `img` |
+| Figure caption | `fmt-name` | `caption` |
+| Table row/cell | `tr`/`td,th` | `row`/`cell,header` |
+| Bibliography | `bibliography` | `refs` |
+| References | `references` | `list` |
+| Item | `bibitem` | `entry` |
+| Inline strong | `strong` | `b` |
+| Inline italic | `em` | `i` |
+| Stem | `stem`/`fmt-stem` | `math`/`mathfmt` |
+
+This is a genuinely different vocabulary — not just renamed standoc.
+The fact that the generic adapter parses it correctly proves there is
+no hidden Metanorma dependency.
+
+The flavor is rendered through the same `ConfigDrivenPipeline` with
+zero core code changes. All element selectors come from the flavor's
+`adapter_rules.yml`. All flow rules come from its `flow_rules.yml`.
+All styles come from its `layout_spec.yml`. It declares its own
+`manifest.yml`.
+
+## Done-When
+
+- [x] Second flavor directory exists at `spec/fixtures/flavors/altvocab/`
+- [x] Uses a deliberately non-Metanorma vocabulary (article/sec/para/h2)
+- [x] Renders a fixture via the generic pipeline with zero core changes
+- [x] All selectors come from `adapter_rules.yml`
+- [x] Manifest is loadable via `Flavor::Manifest.load`
+- [x] Specs verify parse correctness + PDF render + manifest exposure
+- [x] All 267+ specs still pass
+
+## Verification
+
+- `spec/arrolio/second_flavor_spike_spec.rb` (3 specs)
+- `bundle exec rake` is green
+- `bundle exec ruby exe/arrolio2pdf <fixture.xml> out.pdf spec/fixtures/flavors/altvocab`
+
+## Outcome
+
+The generic design is now proven across two distinct vocabularies
+(Metanorma standoc + synthetic altvocab). Adding a third real-world
+flavor (ISO, IEC, BSI, DITA, DocBook) is a configuration exercise, not
+a code change.

data/TODO.complete/54-flavor-manifest-contract.md

@@ -0,0 +1,72 @@
+---
+priority: P1
+impact: med
+depends_on: [50]
+layer: architecture
+status: done
+est: 1d
+---
+
+## Problem
+
+A flavor directory was just "three YAML files". There was no
+machine-readable manifest declaring the flavor's name, version,
+upstream XSL, required fonts, or config-file locations. This meant:
+
+- No way to detect a broken/truncated flavor directory at load time.
+- No way to surface flavor metadata in error messages.
+- No discovery mechanism for installed flavor gems.
+
+## Approach
+
+1. **`flavors/<name>/manifest.yml`** is the flavor's contract:
+
+   ```yaml
+   name: oiml
+   version: 1.0.0
+   description: OIML International Recommendation
+   upstream:
+     xsl: oiml.xsl
+   doctypes:
+     - recommendation
+     - document
+   fonts:
+     required:
+       - Times New Roman
+       - Jost
+     optional:
+       - Cambria Math
+   config_files:
+     layout_spec: layout_spec.yml
+     adapter_rules: adapter_rules.yml
+     flow_rules: flow_rules.yml
+   ```
+
+2. **`Arroolio::Flavor::Manifest`** class (autoloaded from
+   `lib/arrolio/flavor/manifest.rb`): loads + validates the manifest,
+   provides typed accessors (`name`, `version`, `description`,
+   `required_fonts`, `optional_fonts`, `config_path_for(:layout_spec)`).
+3. **`ConfigDrivenPipeline.new(flavor_dir:)`** auto-detects the
+   manifest if present and exposes it via `pipeline.manifest`.
+4. **`Flavor::Manifest.load(flavor_dir)`** raises
+   `Arroolio::FlavorError` (new typed error) with structured metadata
+   when the manifest is missing or malformed.
+5. **Manifests added** to `flavors/oiml/manifest.yml` and
+   `spec/fixtures/flavors/sample/manifest.yml`.
+
+## Done-When
+
+- [x] `Arroolio::Flavor::Manifest` class with typed accessors
+- [x] `Arroolio::FlavorError` typed error for missing/malformed manifests
+- [x] `flavors/oiml/manifest.yml` exists
+- [x] `spec/fixtures/flavors/sample/manifest.yml` exists
+- [x] `ConfigDrivenPipeline` exposes `pipeline.manifest`
+- [x] Specs cover: valid manifest load, missing manifest, malformed
+      manifest, missing required field
+- [x] All 249+ specs still pass
+
+## Verification
+
+- `bundle exec rspec spec/arrolio/flavor/manifest_spec.rb`
+- `bundle exec rake` is green
+- OIML r060/1 fixture still renders via the generic pipeline

data/TODO.complete/55-header-footer-style-configuration.md

@@ -0,0 +1,57 @@
+---
+priority: P1
+impact: med
+depends_on: [50, 63]
+layer: render
+status: done
+est: 1d
+---
+
+## Problem
+
+The renderer (`lib/arrolio/renderer/pdf.rb`) hardcoded OIML-specific
+header/footer and cover-logo values:
+
+- Margins: `26.5 * MM_TO_PT` / `25.5 * MM_TO_PT` (OIML values)
+- Header/footer font: `'Arial'` hardcoded
+- Header/footer size: `9.0` hardcoded
+- Rule width: `0.5` hardcoded
+- Cover logo dimensions: `35.0mm` / `1459.0/1667.0` aspect (OIML logo)
+- Cover logo margin: `25.5mm`
+
+These are all OIML conventions. A flavor with different margins,
+fonts, or logo dimensions would not render correctly without
+modifying core — violating OCP.
+
+## Approach
+
+1. **LayoutSpec carries config**: `LayoutSpec` now exposes
+   `header_footer_config` and `cover_logo_config` Hashes, loaded from
+   `layout_spec.yml`'s `header_footer:` and `cover_logo:` blocks.
+2. **Renderer reads from layout_spec**: `Renderer::Pdf#render`
+   accepts a `layout_spec:` keyword; `header_footer_style` and
+   `cover_logo_style` read values from it (falling back to
+   engine-safe defaults when nil).
+3. **Pipeline passes layout_spec through**: `ConfigDrivenPipeline`
+   forwards `layout_spec:` to `Renderer::Pdf#render`.
+4. **Flavor YAML declares its values**: `flavors/oiml/layout_spec.yml`
+   declares `header_footer:` (Arial 9pt + 0.5pt rule + 26.5/25.5mm
+   margins) and `cover_logo:` (35mm / 0.8758 aspect / 25.5mm margin).
+5. **Sample fixture also declares** its own (Helvetica-based) values.
+
+## Done-When
+
+- [x] `LayoutSpec` exposes `header_footer_config` and `cover_logo_config`
+- [x] `Loader` reads them from `layout_spec.yml`
+- [x] `Renderer::Pdf#render` accepts `layout_spec:` and reads values
+- [x] No hardcoded `'Arial'` or `26.5` literals in the renderer logic
+- [x] Engine-safe defaults apply when `layout_spec:` is nil
+- [x] Specs verify: configured values used, defaults used, both paths
+      tested
+- [x] OIML r060/1 still renders 28 pages via the generic pipeline
+
+## Verification
+
+- `spec/arrolio/layout_spec_config_spec.rb` (7 specs)
+- `bundle exec rake` is green
+- OIML render via `exe/arrolio2pdf` produces a 28-page PDF

data/TODO.complete/56-generic-adapter-mece-decomposition.md

@@ -0,0 +1,56 @@
+---
+priority: P1
+impact: high
+depends_on: [50, 52, 63]
+layer: architecture
+status: done
+est: 1d
+---
+
+## Problem
+
+The generic adapter still hardcoded Metanorma standoc vocabulary
+throughout (`preface`, `bibliography`, `references`, `bibitem`,
+`clause`, `foreword`, `title`, `span`, `tab`, `br`). A flavor with a
+different vocabulary (DITA, DocBook, JATS) would not work without
+modifying core — violating OCP.
+
+## Approach
+
+1. **Extended `selectors` block** in `adapter_rules.yml`: added keys
+   for `preface_container`, `preface_children`, `bibliography_container`,
+   `bibliography_reference`, `bibliography_item`, `fallback_title`,
+   `span`, `tab_inline`, `break_inline`.
+2. **`GenericAdapter` reads selectors** for every element it touches —
+   no hardcoded element names outside the clearly-labelled
+   `DEFAULT_SELECTORS` constant.
+3. **`DEFAULT_SELECTORS` documents the standoc convention** as a
+   fallback so flavors that omit selectors still work, but every
+   real flavor (OIML + sample fixture) declares its full selector set.
+4. **`scripts/xsl_to_config.rb`** emits the full `selectors` block
+   (27 keys) in generated `adapter_rules.yml`.
+5. **Bug fix**: `extract_bibliography` had referenced `preface_elem`
+   in the bibliography scope — fixed to `biblio_elem`.
+6. **Strict typing in constructor**: `Content::Document.new` now
+   validates that `sections`, `preface`, and `bibliography` arrays
+   contain only `Content::Section` instances, raising `ContentError`
+   at the construction site rather than deep in the pipeline.
+
+## Done-When
+
+- [x] `GenericAdapter` has no Metanorma element names outside
+      `DEFAULT_SELECTORS`
+- [x] `DEFAULT_SELECTORS` includes the 9 new document-structure keys
+- [x] OCP grep spec enforces no `fmt-*`, no flavor literals, no OIML
+      references in the generic core
+- [x] Non-Metanorma vocabulary spec proves the adapter parses
+      custom XML using only selectors
+- [x] `Content::Document` constructor validates Section typing
+- [x] Real OIML pipeline still renders 28 pages via the generic
+      pipeline
+
+## Verification
+
+- `spec/arrolio/ocp_grep_spec.rb` — 5 OCP guard specs
+- `bundle exec rake` is green (244 examples)
+- OIML render: 28 pages, ~258 KB

data/TODO.complete/57-strict-section-typing.md

@@ -0,0 +1,49 @@
+---
+priority: P0
+impact: high
+depends_on: [50, 63]
+layer: adapter
+status: done
+est: 1d
+---
+
+## Problem
+
+`Content::Document#sections` returned a mixed Array that, despite
+earlier fixes, had no constructor-level guarantee of being
+`Section[]`. A flavor whose adapter mistakenly pushed a Paragraph
+into the array would fail deep in the pipeline with `NoMethodError:
+undefined method 'heading?'` rather than at the construction site.
+
+This is a typing failure: `sections` should be `Section[]` by
+contract. Validation belongs in the constructor.
+
+## Approach
+
+1. **Constructor validation**: `Content::Document.new` raises
+   `ContentError` if any element of `sections` (or `preface`,
+   `bibliography`) is not a `Content::Section`.
+2. **Adapter guarantee**: `GenericAdapter#extract_sections` returns
+   only Section instances — non-section children of `<sections>` are
+   skipped (the previous behavior pushed zzSTDTitle paragraphs,
+   which is now handled by the cover extraction).
+3. **Specs** cover the validation: a real Section passes; a
+   Paragraph raises with structured metadata.
+
+## Done-When
+
+- [x] `Content::Document#sections` is guaranteed `Section[]` by
+      constructor validation
+- [x] `Content::Document#preface` and `#bibliography` are likewise
+      validated as `Section[]`
+- [x] `GenericAdapter#extract_sections` returns `Section[]` only
+- [x] Specs cover: valid sections pass; non-section raises
+      ContentError
+- [x] Real OIML pipeline renders (25+ pages) without typing failures
+
+## Verification
+
+- `spec/arrolio/content/document_spec.rb` (or similar) covers the
+  constructor validation
+- `bundle exec rake` is green
+- OIML r060/1 fixture renders via the generic pipeline

data/TODO.complete/58-flavor-packaging-gem-convention.md

@@ -0,0 +1,47 @@
+---
+priority: P1
+impact: high
+depends_on: [50, 52]
+layer: architecture
+status: done
+est: 1d
+---
+
+## Problem
+
+There was no documented convention for how third parties should package,
+install, and distribute Arroolio flavors. Without one, "flavors are
+external" is an aspiration, not a deliverable.
+
+## Approach
+
+1. **Wrote `flavors/PACKAGING.md`**: the canonical guide describing
+   the anatomy of a flavor gem, the selector/layout_spec/flow_rules
+   contracts, the `Flavor::Registry` opt-in registration, the
+   `xsl_to_config.rb` workflow, and a verification checklist.
+2. **Documented the selector contract**: every XML element/attribute
+   name the generic adapter touches is named in
+   `adapter_rules.yml`'s `selectors:` block (36 keys). A flavor with a
+   non-Metanorma vocabulary overrides these.
+3. **Documented the layout_spec contract**: `header_footer:` and
+   `cover_logo:` blocks drive the renderer; `page_templates:`,
+   `styles:`, `flows:` drive the engine.
+4. **Documented the flow_rules contract**: `page_sequences:[]`,
+   `cover_content:[]`, `section:`, `content_to_flowable:`, `toc:`.
+
+## Done-When
+
+- [x] `flavors/PACKAGING.md` exists with the full packaging contract
+- [x] Selector contract documented (every key explained)
+- [x] Layout_spec contract documented (every block explained)
+- [x] Flow_rules contract documented (every block explained)
+- [x] Registration-via-Registry pattern documented
+- [x] Verification checklist for flavor encapsulation
+
+## Verification
+
+- `flavors/PACKAGING.md` is the single source of truth for flavor
+  authors
+- The gem itself ships zero flavor artifacts (gemspec excludes
+  `flavors/`)
+- The gem's own specs run without any real flavor installed

data/TODO.complete/59-xsl-converter-profiles.md

@@ -0,0 +1,76 @@
+---
+priority: P2
+impact: med
+depends_on: [50, 51]
+layer: architecture
+status: done
+est: 1d
+---
+
+## Problem
+
+`scripts/xsl_to_config.rb` hardcoded constants that were not derivable
+from the XSL but were OIML/Metanorma-specific:
+
+- 6× `'oiml.xsl'` literal strings (claimed to be derived but were hardcoded)
+- "Times New Roman Italic", "Times New Roman Bold" inline-style defaults
+- "Jost SemiBold", "Jost", "Jost Light" cover-style defaults
+- "Organisation Internationale de Métrologie Légale" + "International Organization of Legal Metrology" literals
+- Standoc element vocabulary (`clause`, `p`, `fmt-title`, `biblio-tag`, ...)
+- Hardcoded default XSL path pointing to OIML
+
+Running the converter against an ISO/IEC/DITA XSL would have produced
+YAML claiming OIML provenance with OIML font defaults — silently wrong.
+
+## Approach
+
+1. **Created `scripts/xsl_profiles/standoc.yml`** — the single file
+   where Metanorma standoc vocabulary lives. Carries:
+   - `element_mapping`, `inline_styles`, `span_class_styles`
+   - `block_level_elements`, `skip_metadata_elements`, `skip_elements`
+   - `selectors` (37 keys)
+   - `metadata_fields` (XPath mapping)
+   - `cover_fields`, `style_overrides`, `cover_content`
+   - `header_template`
+
+2. **Refactored `xsl_to_config.rb`** to read everything from the
+   profile. The converter has ZERO hardcoded element names, font
+   names, or OIML literals.
+
+3. **`generated_from` and `stylesheet`** are now derived from the XSL
+   filename via `File.basename(@xsl_path)`. A new `profile:` field
+   records which profile was used.
+
+4. **Profile is a constructor argument** with a sensible default
+   (`scripts/xsl_profiles/standoc.yml`). A future DITA profile can be
+   added without touching the converter.
+
+5. **Removed the OIML-default XSL path** from the CLI. The script now
+   requires explicit `<xsl-path> <output-dir> [profile-path]` args.
+
+## Done-When
+
+- [x] `scripts/xsl_profiles/standoc.yml` exists with the constants
+- [x] Generator accepts `profile:` argument, defaults to standoc
+- [x] No OIML-specific literals (`oiml`, `Times New Roman`, `Jost`,
+      `Organisation Internationale`) in the generator
+- [x] Generated YAML carries `generated_from: <actual-xsl-filename>`
+      and `profile: standoc.yml`
+- [x] Regenerating OIML config produces correct output
+- [x] Real OIML fixture still renders 28 pages via the regenerated config
+- [x] All specs pass
+
+## Verification
+
+- `grep 'oiml\|Times New Roman\|Jost' scripts/xsl_to_config.rb` → empty
+- `head flavors/oiml/layout_spec.yml` shows
+  `generated_from: oiml.xsl`, `profile: standoc.yml`
+- `bundle exec rake` is green
+- `bundle exec ruby exe/arrolio2pdf <fixture.xml> out.pdf flavors/oiml`
+  produces a 28-page PDF
+
+## Outcome
+
+The converter is now truly generic. Adding a new vocabulary family
+(DITA, DocBook, JATS) means adding `scripts/xsl_profiles/<family>.yml`
+— no converter changes needed.

data/TODO.complete/60-adapter-fidelity-footnotes-notes-examples.md

@@ -0,0 +1,62 @@
+---
+priority: P2
+impact: med
+depends_on: [50]
+layer: adapter
+status: blocked
+est: 2d
+---
+
+## Status: blocked
+
+Requires:
+1. A fixture document that uses `<fmt-footnote-container>` /
+   `<fmt-fn-body>` with realistic content (the OIML r060/1 fixture
+   has none).
+2. A reference PDF that renders these elements so we can measure
+   fidelity.
+3. Page-bottom footnote-line rendering support in the engine (Engine
+   currently has no mechanism for per-page footnotes that collect
+   from the body and render at the bottom).
+
+The foundation is in place — `Content::Footnote` is already defined
+(autoloaded from `lib/arrolio/content/footnote.rb`), and the skip list
+in `adapter_rules.yml` can drop `fmt-footnote-container`/`fmt-fn-body`
+once the flow builder knows how to render them. But without fixtures
+and an engine-side page-bottom collection mechanism, the implementation
+cannot be validated.
+
+## Problem (when unblocked)
+
+The generic pipeline currently loses some information that the legacy
+OIML adapter preserved:
+
+- `fmt-footnote-container` / `fmt-fn-body` are in the `skip_elements`
+  list, so footnotes are dropped from the body and never rendered.
+- `fmt-xref-label` is skipped, so cross-references to notes/examples
+  lose their visual prefix.
+- The `example-body-style` margin-left and `note` list-block indent
+  from the XSL are not translated into Arroolio layout (notes/examples
+  render as plain paragraphs without the XSL's hanging indent).
+
+## Approach (when unblocked)
+
+1. **Footnote flowable** (`Arroolio::Flowables::FootnoteFlowable`):
+   carries a marker + body, renders as superscript marker in the body
+   text and a footnote line at the page bottom.
+2. **Note hanging indent**: the XSL renders notes as `fo:list-block`
+   with `provisional-distance-between-starts: 14.5mm`. The
+   `GenericFlowBuilder` should emit a `NoteFlowable` (already exists)
+   with the configured indent.
+3. **Example body margin**: `example-body-style` margin-left 12.5mm
+   should come from the layout_spec's `example_body` style.
+4. **Cross-reference label**: `fmt-xref-label` should become a styled
+   inline run (caption_label).
+
+## Done-When (when unblocked)
+
+- [ ] Footnotes render with superscript markers + page-bottom lines
+- [ ] Notes render with a hanging indent matching the XSL
+- [ ] Examples render with the inner-paragraph left margin
+- [ ] Cross-reference labels appear with the correct style
+- [ ] Diff against the reference PDF improves for these features

data/TODO.complete/61-error-model-and-strict-mode.md

@@ -0,0 +1,62 @@
+---
+priority: P1
+impact: high
+depends_on: [50]
+layer: engine
+status: done
+est: 2d
+---
+
+## Problem
+
+The pipeline swallowed many errors silently:
+
+- Missing font file → warned and fell back to Helvetica, producing
+  visually wrong output for CJK or specialist fonts without telling
+  the caller anything was wrong.
+- No `strict:` mode for callers who want to fail loud rather than
+  render broken output.
+- `RenderError` was a bare class with no metadata.
+
+## Approach
+
+1. **`RenderError` typed metadata**: now carries `missing_fonts:` —
+   an Array of `[name, path]` pairs.
+2. **`FontMetrics::Registry.register_ttf_all(paths, strict:)`**: when
+   `strict: true`, raises `Arroolio::RenderError` listing every
+   required font whose path does not exist on disk.
+3. **`ConfigDrivenPipeline.new(strict: true)`**: forwards to the
+   registry, so the render fails at the font-registration step before
+   producing any output rather than midway through.
+4. **`ConfigDrivenPipeline.render(..., strict: true)`**: same at the
+   class level.
+5. **`pipeline.strict` reader** for inspection.
+
+## Done-When
+
+- [x] `Arroolio::RenderError` carries structured `missing_fonts:` metadata
+- [x] `FontMetrics::Registry.register_ttf_all` accepts `strict:` kwarg
+- [x] `ConfigDrivenPipeline` accepts `strict:` kwarg and forwards it
+- [x] Default behavior (strict: false) is unchanged — backwards compatible
+- [x] Specs cover: strict mode raises with missing_fonts; non-strict
+      mode does not raise; strict reader works
+
+## Verification
+
+- `spec/arrolio/strict_mode_spec.rb` (4 specs)
+- `bundle exec rake` is green
+- Real OIML fixture still renders 28 pages with `strict: false`
+
+## Future strict-mode expansions
+
+The pattern is established. Future strict checks can be added with
+minimal ceremony:
+
+- Missing image: `RenderError(missing_images:)` when an `<image src=>`
+  cannot be resolved and `strict:` is true.
+- Unknown style: `LayoutSpecError(unknown_style:)` when a style_id
+  referenced by the flow builder isn't in the layout_spec's registry.
+- Adapter selector gap: `AdapterError(missing_selector:)` when the
+  adapter needs a selector that the flavor didn't declare.
+
+These are individually TODO-worthy but follow the same template.

data/TODO.complete/62-font-resolution-and-strict-fonts.md

@@ -0,0 +1,66 @@
+---
+priority: P2
+impact: med
+depends_on: [50, 61]
+layer: render
+status: done
+est: 1d
+---
+
+## Problem
+
+`layout_spec.yml` used absolute user-local paths for fonts
+(`/Users/mulgogi/.fontist/fonts/Times.ttf`). This works on the
+developer's machine but breaks for any other consumer. The generated
+OIML `layout_spec.yml` baked in my home directory.
+
+## Approach
+
+Implemented `Arroolio::Font::Resolver` — a portable font-resolution
+abstraction with a fallback chain:
+
+1. **`FontManifest`** (from `layout_spec.yml`'s `font_manifest:` block):
+   explicit family → variant path mapping declared by the flavor.
+2. **`font_paths`** (legacy explicit paths in `layout_spec.yml`):
+   preserved for backward compatibility.
+3. **fontist** (optional runtime dependency): if the `fontist` gem is
+   available at runtime, families are looked up via fontist's
+   manifest. Skipped silently if fontist is not installed.
+4. **PDF standard 14 fallback**: Helvetica, Times-Roman, Courier, etc.
+   resolve to themselves (built-in PDF fonts).
+
+Strict mode (from TODO 61) raises `RenderError` listing every
+unresolved required font. The resolver never hard-fails when fontist
+is absent — it just falls through to the next strategy.
+
+`LayoutSpec` now carries a `font_manifest_config` Hash loaded from
+`layout_spec.yml`'s `font_manifest:` block, alongside the existing
+`header_footer_config` and `cover_logo_config`.
+
+## Done-When
+
+- [x] `Arroolio::Font::Resolver` class exists, autoloaded
+- [x] `Arroolio::Font::FontManifest` class exists, autoloaded
+- [x] `LayoutSpec#font_manifest_config` accessor exists
+- [x] `Loader` reads `font_manifest:` block from YAML
+- [x] Resolution chain: manifest → font_paths → fontist → standard 14
+- [x] Strict mode raises `RenderError` with `missing_fonts:` metadata
+- [x] Specs cover: each resolution strategy, strict mode, standard 14,
+      manifest fallback paths, missing files
+
+## Verification
+
+- `spec/arrolio/font/resolver_spec.rb` (16 specs)
+- `bundle exec rake` is green (283 specs)
+- The resolver does NOT require fontist at install time — it's a
+  runtime-optional integration via `Object.const_defined?(:Fontist)`
+
+## Outcome
+
+Flavors can now declare fonts by family name with optional explicit
+paths. When a flavor gem is packaged, the `font_manifest:` block can
+list family names; at render time the resolver picks whichever path
+the local environment provides (manifest, font_paths, or fontist).
+
+Adding a real fontist integration later is a one-line change in
+`fontist_lookup` — the abstraction is in place.