svg_conform 0.1.4 → 0.1.5

data/README.adoc

@@ -25,6 +25,7 @@ SvgConform is distributed as a Ruby gem.
 
 * **Profile-based validation**: Validate SVG files against predefined or custom profiles
 * **Remediation**: Automatically fix common SVG conformance issues
+* **Reference manifest**: Complete tracking of IDs and references for consumer-level validation
 * **Extensible architecture**: Easy to add new rules and profiles
 * **Command-line interface**: Validate and fix files from the command line
 * **Ruby API**: Integrate validation into Ruby applications
@@ -230,1227 +231,628 @@ if !result.valid? && profile.remediation_count > 0
 end
 ----
 
+==== Accepting multiple input types
 
+The validator accepts multiple input types and always uses SAX validation for memory-safe processing:
 
-== Core components
-
-=== Architecture
-
-The SvgConform architecture is built around a modular design that separates
-concerns and allows for easy extension.
-
-
-[source]
-----
-╭────────────────────────────────────────────────────────────────╮
-│                        SvgConform                              │
-├────────────────────────────────────────────────────────────────┤
-│                                                                │
-│  ╭─────────────╮    ╭─────────────╮    ╭─────────────╮         │
-│  │     CLI     │    │  Ruby API   │    │   Profiles  │         │
-│  │             │    │             │    │   Registry  │         │
-│  ╰─────┬───────╯    ╰──────┬──────╯    ╰─────┬───────╯         │
-│        │                   │                 │                 │
-│        └───────────────────┼─────────────────┘                 │
-│                            │                                   │
-│  ╭─────────────────────────▼─────────────────────────╮         │
-│  │                     Validator                     │         │
-│  │ ╭─────────────╮  ╭─────────────╮  ╭─────────────╮ │         │
-│  │ │  Document   │  │ Validation  │  │ Remediation │ │         │
-│  │ │   Parser    │  │   Engine    │  │   Engine    │ │         │
-│  │ ╰─────────────╯  ╰─────────────╯  ╰─────────────╯ │         │
-│  ╰─────────────────────────┬─────────────────────────╯         │
-│                            │                                   │
-│  ╭─────────────────────────▼─────────────────────────╮         │
-│  │                  Profile System                   │         │
-│  │                                                   │         │
-│  │ ╭─────────────╮ ╭─────────────╮ ╭─────────────╮   │         │
-│  │ │ SVG 1.2 RFC │ │ Metanorma   │ │   Future    │   │         │
-│  │ │   Profile   │ │ SVG Profile │ │  Profiles   │   │         │
-│  │ │             │ │             │ │             │   │         │
-│  │ │ • svgcheck  │ │ • ID links  │ │ • Custom    │   │         │
-│  │ │ compatible  │ │ • No ext.   │ │   rules     │   │         │
-│  │ │ • Grayscale │ │   fonts     │ │ • Org       │   │         │
-│  │ │ • RFC 7996  │ │ • Font def. │ │   standards │   │         │
-│  │ ╰─────────────╯ ╰─────────────╯ ╰─────────────╯   │         │
-│  ╰─────────────────────────┬─────────────────────────╯         │
-│                            │                                   │
-│  ╭─────────────────────────▼─────────────────────────╮         │
-│  │        Requirements & Remediations Engine         │         │
-│  │ ╭─────────────╮  ╭─────────────╮  ╭─────────────╮ │         │
-│  │ │Requirements │  │Remediations │  │ Validation  │ │         │
-│  │ │   System    │  │   System    │  │   Results   │ │         │
-│  │ ╰─────────────╯  ╰─────────────╯  ╰─────────────╯ │         │
-│  ╰─────────────────────────┬─────────────────────────╯         │
-│                            │                                   │
-│  ╭─────────────────────────▼─────────────────────────╮         │
-│  │             svgcheck Compatibility                │         │
-│  │ ╭─────────────╮  ╭─────────────╮  ╭─────────────╮ │         │
-│  │ │ svgcheck    │  │    YAML     │  │   Report    │ │         │
-│  │ │   Parser    │  │   Mapping   │  │ Comparator  │ │         │
-│  │ ╰─────────────╯  ╰─────────────╯  ╰─────────────╯ │         │
-│  ╰─────────────────────────┬─────────────────────────╯         │
-│                            │                                   │
-│  ╭─────────────────────────▼─────────────────────────╮         │
-│  │                       Moxml                       │         │
-│  │                  (XML Processing)                 │         │
-│  ╰───────────────────────────────────────────────────╯         │
-│                                                                │
-╰────────────────────────────────────────────────────────────────╯
-----
-
-
-=== Profiles
-
-SvgConform includes predefined profiles that can be used out-of-the-box.
-Each profile is designed for different use cases and compliance standards.
-
-.Predefined SVG profiles included in SvgConform
-[cols="2,3,3,2", options="header"]
-|===
-|Profile |Use Case |Key Features |Documentation
-
-|`base`
-|Foundation profile
-|Basic validation, namespace checks, starting point for custom profiles.
-|link:docs/profiles.adoc#base-profile[Details]
-
-|`metanorma`
-|Metanorma SVG profile
-|Standard SVG for Metanorma documents. Valid HREFs and ID linking. No external
-fonts, images and CSS. No non-SVG elements or attributes.
-|link:docs/profiles.adoc#no-external-css-profile[Details]
-
-|`svg_1_2_rfc`
-|IETF RFC SVG 1.2 profile
-|RFC 7996/6949 compliant. Black/white color only, limited elements, generic
-fonts. Fully compatible with `svgcheck` outcomes.
-|link:docs/profiles.adoc#svg-1-2-rfc-profile[Details]
-
-|`svg_1_2_rfc_with_rdf`
-|IETF RFC SVG 1.2 profile with RDF metadata
-|Same as `svg_1_2_rfc`, but allows RDF/Dublin Core metadata from design tools.
-Supported by `svgcheck`.
-|link:docs/profiles.adoc#svg-1-2-rfc-with-rdf-profile[Details]
-
-|`no_external_css`
-|Self-contained SVG
-|No external references, security-focused, offline usage.
-|link:docs/profiles.adoc#no-external-css-profile[Details]
-
-|`lucid_fix`
-|Lucid cleanup
-|Remove Lucid-specific metadata, clean standard SVG output
-|link:docs/profiles.adoc#lucid-fix-profile[Details]
-|===
-
-For complete profile documentation, including inheritance, customization, RDF
-metadata support, and selection guides, see
-link:docs/profiles.adoc[SVG Profiles Documentation].
-
-For detailed information about configuring RDF metadata support in profiles, see
-link:docs/rdf_metadata_support.adoc[RDF Metadata Support Documentation].
-
-
-
-=== Requirements
-
-SvgConform includes different requirement checkers that validate various aspects
-of SVG documents.
-
-There are two main categories of requirements:
-
-* structural requirements: requirements set towards the XML structure and syntax of SVG documents
-* logical requirements: requirements set towards content and stylistic aspects of SVG documents
-
-.SvgConform supported requirement classes
-[cols="2,2,3", options="header"]
-|===
-|Type |Requirement |Description
-
-|Structural
-|link:docs/requirements.adoc#namespace-requirement[`NamespaceRequirement`]
-|Ensures proper SVG namespace declarations
-
-|Structural
-|link:docs/requirements.adoc#namespace-attributes-requirement[`NamespaceAttributesRequirement`]
-|Validates namespace attributes are from allowed namespaces
-
-|Structural
-|link:docs/requirements.adoc#allowed-elements-requirement[`AllowedElementsRequirement`]
-|Restricts which SVG elements are permitted
-
-|Structural
-|link:docs/requirements.adoc#viewbox-required-requirement[`ViewboxRequiredRequirement`]
-|Requires viewBox attributes on root elements
-
-|Logical
-|link:docs/requirements.adoc#color-restrictions-requirement[`ColorRestrictionsRequirement`]
-|Enforces color usage restrictions (e.g., grayscale only)
-
-|Logical
-|link:docs/requirements.adoc#font-family-requirement[`FontFamilyRequirement`]
-|Controls font family usage and validates font specifications
-
-|Logical
-|link:docs/requirements.adoc#no-external-css-requirement[`NoExternalCssRequirement`]
-|Prevents external CSS references to ensure self-contained documents
-
-|Logical
-|link:docs/requirements.adoc#no-external-fonts-requirement[`NoExternalFontsRequirement`]
-|Validates that no external font references are present
-
-|Logical
-|link:docs/requirements.adoc#no-external-images-requirement[`NoExternalImagesRequirement`]
-|Validates that no external image references are present
-
-|Logical
-|link:docs/requirements.adoc#forbidden-content-requirement[`ForbiddenContentRequirement`]
-|Prevents inclusion of forbidden elements and attributes
-
-|Logical
-|link:docs/requirements.adoc#id-reference-requirement[`IdReferenceRequirement`]
-|Validates that ID references point to existing elements
-
-|Logical
-|link:docs/requirements.adoc#invalid-id-references-requirement[`InvalidIdReferencesRequirement`]
-|Detects and validates broken ID references in SVG documents
-
-|Logical
-|link:docs/requirements.adoc#link-validation-requirement[`LinkValidationRequirement`]
-|Validates that links use only ASCII characters (IETF requirement)
-
-|Logical
-|link:docs/requirements.adoc#style-requirement[`StyleRequirement`]
-|Comprehensive CSS style validation including syntax and properties
-
-|Logical
-|link:docs/requirements.adoc#style-promotion-requirement[`StylePromotionRequirement`]
-|Detects style properties that should be promoted to SVG attributes
-|===
-
-
-
-=== Remediations
-
-Remediations are automatic fixing actions that can resolve requirement failures.
-Each remediation targets one or more specific requirements.
-
-SvgConform includes different remediation actions that can automatically fix
-SVG documents to resolve requirement violations.
-
-.SvgConform supported remediation classes
-[cols="2,2,3,2", options="header"]
-|===
-|Type |Remediation |Description |Targets
-
-|Content Conversion
-|link:docs/remediation.adoc#color-remediation[`ColorRemediation`]
-|Converts invalid colors to allowed alternatives using threshold-based conversion
-|link:docs/requirements.adoc#color-restrictions-requirement[`ColorRestrictionsRequirement`]
-
-|Content Conversion
-|link:docs/remediation.adoc#font-remediation[`FontRemediation`]
-|Maps font families to generic alternatives (serif, sans-serif, monospace)
-|link:docs/requirements.adoc#font-family-requirement[`FontFamilyRequirement`]
-
-|Content Conversion
-|link:docs/remediation.adoc#font-embedding-remediation[`FontEmbeddingRemediation`]
-|Converts external font references to embedded data URIs
-|link:docs/requirements.adoc#no-external-fonts-requirement[`NoExternalFontsRequirement`]
-
-|Content Conversion
-|link:docs/remediation.adoc#image-embedding-remediation[`ImageEmbeddingRemediation`]
-|Converts external image references to embedded data URIs
-|link:docs/requirements.adoc#no-external-images-requirement[`NoExternalImagesRequirement`]
-
-|Element/Attribute Removal
-|link:docs/remediation.adoc#namespace-remediation[`NamespaceRemediation`]
-|Removes invalid namespace elements and cleans up namespace declarations
-|link:docs/requirements.adoc#namespace-requirement[`NamespaceRequirement`]
-
-|Element/Attribute Removal
-|link:docs/remediation.adoc#namespace-attribute-remediation[`NamespaceAttributeRemediation`]
-|Removes attributes from disallowed namespaces
-|link:docs/requirements.adoc#namespace-attributes-requirement[`NamespaceAttributesRequirement`]
-
-|Element/Attribute Removal
-|link:docs/remediation.adoc#no-external-css-remediation[`NoExternalCssRemediation`]
-|Removes external CSS references including @import and external stylesheets
-|link:docs/requirements.adoc#no-external-css-requirement[`NoExternalCssRequirement`]
-
-|Addition
-|link:docs/remediation.adoc#viewbox-remediation[`ViewboxRemediation`]
-|Adds missing viewBox attributes to root SVG elements
-|link:docs/requirements.adoc#viewbox-required-requirement[`ViewboxRequiredRequirement`]
-
-|Style Processing
-|link:docs/remediation.adoc#style-promotion-remediation[`StylePromotionRemediation`]
-|Promotes CSS style properties to equivalent SVG attributes
-|link:docs/requirements.adoc#style-promotion-requirement[`StylePromotionRequirement`]
-
-|Reference Fixing
-|link:docs/remediation.adoc#invalid-id-references-remediation[`InvalidIdReferencesRemediation`]
-|Fixes or removes broken ID references and invalid href attributes
-|link:docs/requirements.adoc#id-reference-requirement[`IdReferenceRequirement`], `InvalidIdReferencesRequirement`
-|===
-
-
-=== Requirement and remediation mapping
-
-Remediations are mapped to requirements using the `targets` configuration in
-profile YAML files.
-
-[source,yaml]
-----
-remediations:
-  - id: "fix_invalid_colors"
-    type: "ColorRemediationAction"
-    description: "Convert invalid colors to black or white"
-    targets: ["color_restrictions"]  # Maps to ColorRestrictionsRequirement
+[source,ruby]
 ----
+validator = SvgConform::Validator.new
 
-This mapping system allows:
-
-* **Targeted fixes**: Remediations only run when their target requirements fail
-* **Flexible configuration**: Multiple remediations can target the same requirement
-* **Conditional application**: Remediations can be enabled/disabled per profile
-
-
+# String input: Direct SAX parsing
+result = validator.validate(svg_string, profile: :metanorma)
 
-=== Validation and remediation flow
+# Moxml documents/elements: Serialize once, then SAX validate
+moxml_doc = Moxml.new.parse(svg_string)
+result = validator.validate(moxml_doc, profile: :metanorma)
 
-The following steps illustrates the data flow through the core components of
-SvgConform.
+moxml_element = moxml_doc.root
+result = validator.validate(moxml_element, profile: :metanorma)
 
-. An SVG file is read and parsed into a Document object.
-. The Document is validated against a Profile using the Validator.
-. The Validator applies Requirements and collects results in a ConformanceReport object.
-. If fixing is enabled, the Validator uses the RemediationEngine to apply Remediations.
-. The fixed Document is returned along with the validation results in the ConformanceReport.
+# Nokogiri documents/elements: Serialize once, then SAX validate
+nokogiri_doc = Nokogiri::XML(svg_string)
+result = validator.validate(nokogiri_doc, profile: :metanorma)
 
-[source]
+nokogiri_element = nokogiri_doc.root  # Common in metanorma integration
+result = validator.validate(nokogiri_element, profile: :metanorma)
 ----
-┌─────────────┐    ┌─────────────┐    ┌─────────────┐
-│  SVG File   │───▶│  Document   │───▶│  Validator  │
-│             │    │   Parser    │    │             │
-└─────────────┘    └─────────────┘    └─────┬───────┘
-                                            │
-                   ┌─────────────┐          │
-                   │   Profile   │◀─────────┘
-                   └─────┬───────┘
-                         │
-                   ┌─────▼───────┐
-                   │    Rules    │
-                   └─────┬───────┘
-                         │
-                   ┌─────▼───────┐    ┌─────────────┐
-                   │Requirements │───▶│ Validation  │
-                   │             │    │   Result    │
-                   └─────────────┘    └─────┬───────┘
-                                            │
-                   ┌─────────────┐          │
-                   │Remediations │◀─────────┘
-                   └─────┬───────┘
-                         │
-                 ┌───────▼────────┐
-                 │ Fixed Document │
-                 └────────────────┘
-----
-
-=== Classes
 
-==== Document (`SvgConform::Document`)
+**Why SAX validation for all inputs?**
 
-Represents an SVG document. The SVG document in XML is parsed using the `Moxml`
-library, and provides SVG-specific functionality through the Document class.
+SAX (Simple API for XML) parsing is memory-safe and can handle arbitrarily large SVG files without hanging. DOM-based validation loads the entire tree into memory, which can cause performance issues or crashes with large files.
 
-==== Validator (`SvgConform::Validator`)
+**Benefits of accepting DOM objects**:
 
-The validator is the main entry point for SVG validation. It orchestrates the
-validation process with loading profiles, applying rules, and collecting results.
+When integrating with tools like Metanorma where SVG elements are already parsed:
 
-==== Profile (`SvgConform::Profile`)
-
-A profile is a collection of requirements and remediations that define a specific
-SVG conformance standard. Profiles are defined in YAML configuration files and are
-loaded dynamically at runtime.
-
-Notice that there are requirement violations that cannot be automatically
-remediated. For example, if an SVG uses a forbidden element, the remediation may
-simply remove it, which could lead to loss of important content.
+[source,ruby]
+----
+# ❌ Old way: User manually serializes
+result = validator.validate(svg_element.to_xml, profile: :metanorma)
 
+# ✅ New way: Library handles serialization internally
+result = validator.validate(svg_element, profile: :metanorma)
+----
 
-==== Requirements
+Benefits:
+- **Cleaner API**: No need to call `.to_xml` explicitly
+- **Type flexibility**: Works with Nokogiri, Moxml, or strings
+- **Safe for large files**: Always uses memory-efficient SAX parsing
+- **Backward compatible**: String input still works as before
 
-An SvgConform requirement is a specific validation check that determines if an SVG
-document meets certain criteria. Requirements are implemented as classes that inherit
-from `SvgConform::Requirements::BaseRequirement`.
 
-Each requirement class focuses on a single concern implemented using
-XML tree traversal and validation logic.
+=== Reference manifest
 
-Every requirement check can be configured with specific parameters to fine-tune
-its behavior.
+SvgConform provides comprehensive ID and reference tracking through its reference manifest system:
 
-Profiles can include multiple requirements to cover various aspects of SVG
-conformance.
+[source,ruby]
+----
+result = validator.validate(svg_content, profile: :metanorma)
 
-==== Remediations
+# Access the reference manifest
+manifest = result.reference_manifest
 
-An SvgConform remediation is an automatic fixing action that can be applied to
-an SVG document to resolve one or more requirement failures. Remediations are
-implemented as classes that inherit from `SvgConform::Remediations::BaseRemediation`.
+# Get all defined IDs
+manifest.available_ids.each do |id_def|
+  puts "ID: #{id_def.id_value} at line #{id_def.line_number}"
+end
 
-Each remediation class focuses on a specific fixing action implemented using
-XML tree manipulation and editing.
+# Check for unresolved internal references
+if result.has_unresolved_references?
+  result.unresolved_internal_references.each do |ref|
+    puts "Unresolved reference: #{ref.value} at line #{ref.line_number}"
+  end
+end
 
-Every remediation can be configured with specific parameters to customize its
-behavior. A remediation can target one or more specific requirements through
-configuration options.
+# Check for external references
+if result.has_external_references?
+  result.external_references.each do |ref|
+    puts "External reference: #{ref.value}"
+  end
+end
+----
 
+See link:docs/reference_manifest.adoc[Reference Manifest Documentation] for complete details.
 
 
 [[command_line_interface]]
 == Command line interface
 
-=== General
-
-The `svg_conform` command provides a comprehensive CLI for validation and fixing.
+The `svg_conform` command-line tool provides validation and remediation capabilities for SVG files.
 
+=== Basic commands
 
-=== `svg_conform profiles`
-
-The `profiles` command lists all available SVG profiles included in SvgConform.
-
-Syntax:
+==== List available profiles
 
 [source,bash]
 ----
-svg_conform profiles [OPTIONS]
-
-Options:
-  -v, --verbose           Show detailed profile information
+$ svg_conform profiles
 ----
 
-[example]
-====
+Show detailed information about profiles:
+
 [source,bash]
 ----
-# List all profiles
-$ svg_conform profiles
-
-Available SVG Profiles
-========================================
-
-╭──────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
-│ Profile              │ Description                                                                                                       │
-├──────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
-│ base                 │ Base SVG validation profile with common requirements                                                              │
-│ lucid_fix            │ Lucid SVG Fix Profile - Removes invalid use element references and namespace attributes from Lucid-generated SVGs │
-│ metanorma            │ Metanorma SVG Profile - SVG requirements for Metanorma technical documents with embedded resources                │
-│ no_external_css      │ Security-focused profile that disallows external CSS references                                                   │
-│ svg_1_2_rfc          │ SVG 1.2 RFC Profile (RFC 7996) - Black and white diagrams for technical documents                                 │
-│ svg_1_2_rfc_with_rdf │ SVG 1.2 RFC Profile with RDF metadata support - Allows RDF/Dublin Core metadata in SVG files                      │
-╰──────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+$ svg_conform profiles --verbose
 ----
-====
-
 
-
-=== `svg_conform check`
-
-The `check` command validates SVG files against a specified profile and optionally
-applies automatic remediations. It supports single files, multiple files via shell
-glob expansion, and directory scanning.
-
-Syntax:
+==== Validate a single SVG file
 
 [source,bash]
 ----
-svg_conform check [*FILES] [OPTIONS]
-svg_conform check --directory PATH [OPTIONS]
+$ svg_conform check file.svg --profile=metanorma
+----
 
-Required Options:
-  -p, --profile PROFILE         Profile to validate against
+Options:
 
-Input Options:
-  -d, --directory PATH          Directory to scan recursively for SVG files
+* `--profile=PROFILE` or `-p`: Profile to validate against (default: `svg_1_2_rfc`)
+* `--format=FORMAT`: Output format: `table` (default), `json`, or `yaml`
+* `--output=FILE` or `-o`: Save report to file
 
-Remediation Options:
-  -f, --fix                     Enable automatic remediation
-      --output-dir DIR          Output directory for remediated files (required for multi-file)
-      --in-place                Replace original files (requires --force)
-      --force                   Confirm destructive operations
-      --fix-output FILE         Output file for single file mode (default: FILE.fixed.svg)
+Example with JSON output:
 
-Reporting Options:
-      --format FORMAT           Output format for single file: table, yaml, json (default: table)
-  -o, --output FILE             Output file for single file mode
-      --report-format FORMAT    Batch report format: json, yaml
-      --report-output FILE      Save detailed batch report to file
-      --manifest FILE           Manifest file path (default: manifest.json with --fix)
-  -q, --quiet                   Suppress per-file output, show summary only
-  -v, --verbose                 Show detailed progress
+[source,bash]
+----
+$ svg_conform check file.svg -p metanorma --format=json --output=report.json
 ----
 
-The check command supports three operational modes:
-
-**Single File Mode:**
+==== Fix a single SVG file
 
-Validates a single SVG file and outputs a detailed validation report.
+Apply automatic remediations to fix conformance issues:
 
 [source,bash]
 ----
-# Basic validation
-svg_conform check file.svg -p metanorma
-
-# With remediation
-svg_conform check file.svg -p metanorma -f --fix-output fixed.svg
-
-# Output YAML report
-svg_conform check file.svg -p metanorma --format yaml -o report.yaml
+$ svg_conform check file.svg --profile=metanorma --fix
 ----
 
-**Multiple Files Mode (Shell Glob):**
-
-Validates multiple files specified via shell glob patterns. The shell expands
-patterns like `*.svg` before passing to the command.
+Specify custom output file:
 
 [source,bash]
 ----
-# Validate all SVG files in current directory
-svg_conform check *.svg -p metanorma
-
-# Validate with pattern matching
-svg_conform check images/*/*.svg -p metanorma
+$ svg_conform check file.svg -p metanorma -f --fix-output=fixed.svg
+----
 
-# Fix multiple files
-svg_conform check *.svg -p metanorma -f --output-dir fixed/
+Options:
 
-# With JSON batch report
-svg_conform check *.svg -p metanorma --report-format json --report-output report.json
-----
+* `--fix` or `-f`: Enable automatic remediation
+* `--fix-output=FILE`: Output file for remediated SVG (default: `FILE.fixed.svg`)
 
-**Directory Mode:**
+==== Process multiple files
 
-Recursively scans a directory for all SVG files using the `--directory` or `-d` flag.
+Process multiple SVG files at once:
 
 [source,bash]
 ----
-# Scan directory and validate
-svg_conform check -d images/ -p metanorma
-
-# Scan and remediate to new directory
-svg_conform check -d images/ -p metanorma -f --output-dir fixed/
-
-# Replace files in place (requires confirmation)
-svg_conform check -d images/ -p metanorma -f --in-place --force
+$ svg_conform check file1.svg file2.svg file3.svg --profile=metanorma
+----
 
-# Quiet mode with detailed JSON report
-svg_conform check -d images/ -p metanorma -f --output-dir fixed/ --quiet \
-  --report-format json --report-output report.json
+With remediation, an output directory is required:
 
-# With custom manifest file
-svg_conform check -d images/ -p metanorma -f --output-dir fixed/ --manifest mappings.json
+[source,bash]
+----
+$ svg_conform check *.svg -p metanorma --fix --output-dir=fixed/
 ----
 
-**Batch Report Format:**
+==== Process a directory
 
-When processing multiple files or directories, a batch summary is displayed:
+Recursively process all SVG files in a directory:
 
-[source]
+[source,bash]
 ----
-BATCH VALIDATION SUMMARY
-Directory: /path/to/images
-Profile: metanorma
-Files processed: 56
-Valid before: 0
-Remediated: 56
-Valid after: 56
-Failed: 0
-Success rate: 100.0%
-Manifest written to manifest.json
+$ svg_conform check --directory=images/ --profile=metanorma
 ----
 
-If `--report-format` is specified, a detailed report is generated in JSON or
-YAML format using lutaml-model serialization:
+With remediation:
 
-[source,json]
+[source,bash]
 ----
-{
-  "directory": "/path/to/images",
-  "profile": "metanorma",
-  "timestamp": "2025-10-12T15:36:25+08:00",
-  "total_files": 56,
-  "valid_before": 0,
-  "valid_after": 56,
-  "remediated": 56,
-  "failed": 0,
-  "success_rate": 100.0,
-  "files": [
-    {
-      "filename": "diagram.svg",
-      "original_path": "/path/to/images/diagram.svg",
-      "valid_before": false,
-      "valid_after": true,
-      "errors_before": 3,
-      "errors_after": 0,
-      "remediated_path": "/path/to/fixed/diagram.svg",
-      "status": "remediated"
-    }
-  ],
-  "manifest": {
-    "/path/to/images/diagram.svg": "/path/to/fixed/diagram.svg"
-  }
-}
+$ svg_conform check -d images/ -p metanorma --fix --output-dir=fixed/
 ----
 
-**Manifest File:**
+Replace files in-place (use with caution):
 
-When using `--fix`, a manifest file is automatically created (or can be
-explicitly specified with `--manifest`). The manifest maps original file paths
-to their remediated counterparts:
-
-[source,json]
+[source,bash]
 ----
-{
-  "timestamp": "2025-10-12T15:00:00+08:00",
-  "profile": "metanorma",
-  "mappings": {
-    "/original/path/file1.svg": "/fixed/path/file1.svg",
-    "/original/path/file2.svg": "/fixed/path/file2.svg"
-  }
-}
+$ svg_conform check -d images/ -p metanorma --fix --in-place --force
 ----
 
+==== Batch processing options
 
-=== `svg_conform version`
+Additional options for batch processing:
 
-The `version` command displays the current version of SvgConform.
+* `--quiet` or `-q`: Suppress per-file output, show summary only
+* `--verbose` or `-v`: Show detailed progress
+* `--report-format=FORMAT`: Generate detailed report in `json` or `yaml`
+* `--report-output=FILE`: Save detailed batch report to file
+* `--manifest=FILE`: Generate manifest mapping original to remediated files (default: `manifest.json`)
 
-Syntax:
+Example with detailed reporting:
 
 [source,bash]
 ----
-svg_conform version
+$ svg_conform check -d images/ -p metanorma -f --output-dir=fixed/ \
+  --report-format=json --report-output=batch-report.json \
+  --manifest=file-mapping.json
 ----
 
-[example]
+==== Display version
+
 [source,bash]
 ----
 $ svg_conform version
-SvgConform 0.1.0
 ----
 
+=== Exit codes
 
+* `0`: All files valid or successfully remediated
+* `1`: Validation failures or errors occurred
 
-[[ruby_api_reference]]
-== Ruby API
+=== Common workflows
 
-=== Basic usage
+==== Quality control workflow
 
-[source,ruby]
+Check all SVG files before deployment:
+
+[source,bash]
+----
+$ svg_conform check -d assets/images/ -p metanorma --quiet
 ----
-require 'svg_conform'
 
-# Validate a file
-result = SvgConform.validate_file('diagram.svg', profile: :svg_1_2_rfc)
+==== Batch remediation workflow
 
-# Check validation status
-puts "Valid: #{result.valid?}"
-puts "Errors: #{result.errors.count}"
-puts "Warnings: #{result.warnings.count}"
+Fix all non-conforming files:
 
-# Get detailed error information
-result.errors.each do |error|
-  puts "#{error.rule.id}: #{error.message}"
-  puts "  Element: #{error.element}" if error.element
-  puts "  Location: #{error.location}" if error.location
-end
+[source,bash]
 ----
+# 1. Validate and identify issues
+$ svg_conform check -d images/ -p metanorma --report-format=json \
+  --report-output=pre-fix-report.json
 
-=== Advanced usage
+# 2. Apply fixes
+$ svg_conform check -d images/ -p metanorma --fix --output-dir=fixed/ \
+  --manifest=manifest.json
 
-[source,ruby]
+# 3. Verify fixes
+$ svg_conform check -d fixed/ -p metanorma --report-format=json \
+  --report-output=post-fix-report.json
 ----
-# Create validator instance
-validator = SvgConform::Validator.new
 
-# Validate with custom options
-result = validator.validate_file('diagram.svg',
-  profile: :svg_1_2_rfc,
-  fix: true,
-  strict: false
-)
+==== Integration with CI/CD
 
-# Access fixed document
-if result.fixed?
-  fixed_svg = result.fixed_document.to_xml
-  File.write('diagram_fixed.svg', fixed_svg)
-end
+Validate SVGs in continuous integration:
 
-# Get profile information
-profile_info = validator.profile_info(:svg_1_2_rfc)
-puts "Profile: #{profile_info[:name]}"
-puts "Description: #{profile_info[:description]}"
-puts "Rules: #{profile_info[:rules].map { |r| r[:id] }.join(', ')}"
+[source,bash]
 ----
+$ svg_conform check -d docs/images/ -p metanorma --quiet
 
-=== Working with loaded SVG content
-
-[source,ruby]
+# Exit code 0 = pass, 1 = fail
 ----
-# Parse SVG content
-document = SvgConform::Document.from_content(svg_string)
 
-# Access document elements
-root = document.root
-puts "Root element: #{root.name}"
-puts "Namespace: #{root.namespace}"
+=== Complete reference
 
-# Find elements
-circles = document.find_elements('circle')
-texts = document.find_elements('text')
+See link:docs/cli_guide.adoc[CLI Guide] for comprehensive documentation including:
 
-# Modify document
-fixer = SvgConform::Fixer.new(document)
-fixer.remove_element(some_element)
-fixer.set_attribute(element, 'fill', 'black')
+* All available profiles and their requirements
+* Detailed option descriptions
+* Advanced usage patterns
+* Troubleshooting common issues
+* Integration examples
 
-# Get modified XML
-modified_svg = fixer.to_xml
-----
 
+[[ruby_api_reference]]
+== Ruby API reference
 
-== Configuration
+The SvgConform Ruby API provides programmatic access to SVG validation and remediation.
 
-=== Profile configuration
+=== Basic validation
 
-Profiles can be configured using YAML files in the `config/profiles/` directory:
+==== Using the validator
 
-[source,yaml]
+[source,ruby]
 ----
-# config/profiles/custom.yml
-name: "Custom Profile"
-description: "Custom SVG profile for specific requirements"
-extends: "base"  # Optional: inherit from another profile
+require 'svg_conform'
 
-rules:
-  - id: "namespace"
-    type: "namespace_rule"
-    config:
-      required_namespace: "http://www.w3.org/2000/svg"
+validator = SvgConform::Validator.new
+result = validator.validate(svg_content, profile: :metanorma)
 
-  - id: "allowed_elements"
-    type: "allowed_elements_rule"
-    config:
-      allowed_elements:
-        - "svg"
-        - "g"
-        - "rect"
-        - "circle"
-        - "path"
-        - "text"
+puts "Valid: #{result.valid?}"
+puts "Errors: #{result.errors.count}"
+puts "Warnings: #{result.warnings.count}"
 
-  - id: "color_restrictions"
-    type: "color_restrictions_rule"
-    config:
-      grayscale_only: true
-      allowed_colors:
-        - "black"
-        - "white"
-        - "gray"
+# Access error details
+result.errors.each do |error|
+  puts "#{error.requirement_id}: #{error.message}"
+  puts "  Location: #{error.element}" if error.element
+end
 ----
 
-=== Requirement configuration
-
-TODO.
-
-=== Remediation configuration
-
-TODO.
-
-
-== Extending SvgConform
+==== Loading profiles
 
-=== Custom profiles
+Load a profile by name:
 
-Create a new profile by defining a YAML configuration:
-
-[source,yaml]
+[source,ruby]
+----
+profile = SvgConform::Profiles.get(:svg_1_2_rfc)
 ----
-# config/profiles/my_organization.yml
-profile:
-  name: "My Organization SVG Profile"
-  description: "SVG profile for internal use"
-  import: "base"  # Optional: inherit from another profile
-
-requirements:
-  - id: "namespace"
-    type: "NamespaceRequirement"
-    description: "Ensure proper SVG namespace"
 
-  - id: "custom_requirement"
-    type: "CustomRequirement"
-    description: "Validate custom elements"
-    config:
-      custom_option: "organization_value"
+Available built-in profiles:
 
-  - id: "security_restrictions"
-    type: "NoExternalCssRequirement"
-    description: "Prevent external CSS references"
+* `:base` - Minimal SVG validation
+* `:svg_1_2_rfc` - RFC 7996 compliance (IETF XMLRFC documents)
+* `:svg_1_2_rfc_with_rdf` - RFC 7996 with RDF metadata support
+* `:metanorma` - Metanorma document requirements
+* `:lucid` - Lucid profile
+* `:no_external_css` - Disallow external CSS
 
-remediations:
-  - id: "fix_namespace"
-    type: "NamespaceRemediationAction"
-    description: "Add missing SVG namespace"
-    targets: ["namespace"]
+Load a custom profile from file:
 
-  - id: "fix_custom_elements"
-    type: "CustomRemediationAction"
-    description: "Fix custom element issues"
-    targets: ["custom_requirement"]
-    config:
-      default_value: "organization_default"
+[source,ruby]
+----
+profile = SvgConform::Profile.load_from_file('path/to/profile.yml')
 ----
 
-Then load the profile:
+==== Validating with profiles
 
 [source,ruby]
 ----
-# Load and use the custom profile
-profile = SvgConform::Profile.load_from_file('config/profiles/my_organization.yml')
+profile = SvgConform::Profiles.get(:metanorma)
 document = SvgConform::Document.new(svg_content)
 result = profile.validate(document)
 
-# Apply remediations if needed
-if !result.valid? && profile.remediation_count > 0
-  changes = profile.apply_remediations(document)
-  puts "Applied #{changes.length} remediations"
+if result.valid?
+  puts "SVG is valid!"
+else
+  puts "Found #{result.errors.count} errors"
 end
 ----
 
-[[external_compliance]]
-== External compliance
-
-=== General
+=== Applying remediations
 
-SvgConform supports external compliance validation through compatibility testing
-and comparison with external SVG validation tools.
+==== Basic remediation
 
-SvgConform provides validation report comparison capabilities that enable
-assessment of compatibility with external SVG validation tools. This supports
-migration workflows and quality assurance processes.
-
-=== svgcheck
-
-IETF provides the `svgcheck` tool, a Python-based SVG validator and fixer
-that checks SVG files against the SVG 1.2 RFC profile defined in RFC 7996.
-
-SvgConform supports validation compatibility testing against the IETF Python
-svgcheck tool for SVG 1.2 RFC validation.
-
-SvgConform includes a compatibility analysis feature that compares its
-validation results with those of `svgcheck`, helping users identify any
-discrepancies or issues.
-
-IMPORTANT: As of version 2025-10-12, SvgConform's SVG 1.2 RFC profile provides a
-100% match in check and repair modes of svgcheck for all test files, except for
-the `full-tiny.svg` file, which svgcheck marks as invalid and fails to repair.
-
-
-=== svgcheck testing workflow
-
-The external compliance testing workflow involves generating reference outputs
-from external tools and comparing validation results:
-
-[source,bash]
+[source,ruby]
 ----
-# 1. Generate external tool outputs for reference
-svg_conform svgcheck generate SVGCHECK_REPO_LOCAL_PATH --mode both
-
-# 2. Generate comparison reports
-svg_conform svgcheck compatibility --output comparison_report.json
-----
-
-
-=== svgcheck compatibility architecture
-
-SvgConform provides compatibility with the IETF Python svgcheck tool through a
-sophisticated mapping and comparison system that enables validation against the
-SVG 1.2 RFC profile.
-
-.Architecture of svgcheck compatibility checks
-[source]
-----
-╭────────────────────────────────────────────────────────────────╮
-│                svgcheck Compatibility System                   │
-│           (SvgConform ↔ svgcheck Python tool)                  │
-├────────────────────────────────────────────────────────────────┤
-│                                                                │
-│  ╭─────────────╮    ╭─────────────────────────────────────╮    │
-│  │ svgcheck    │    │        YAML Mapping                 │    │
-│  │ Raw Errors  │───▶│    config/svgcheck_mapping.yml      │    │
-│  │ (Python)    │    │                                     │    │
-│  ╰─────────────╯    │ • Pattern matching with regex       │    │
-│                     │ • Requirement categorization        │    │
-│                     │ • Semantic meaning extraction       │    │
-│                     │ • Unmapped error detection          │    │
-│                     ╰─────────────┬───────────────────────╯    │
-│                                   │                            │
-│  ╭────────────────────────────────▼────────────────────────╮   │
-│  │              SvgcheckParser                             │   │
-│  │                                                         │   │
-│  │ • Applies YAML mapping during parsing                   │   │
-│  │ • Categorizes errors by requirement                     │   │
-│  │ • Marks unmapped errors for RED display                 │   │
-│  │ • Creates properly structured ConformanceReport         │   │
-│  ╰─────────────────────────┬───────────────────────────────╯   │
-│                            │                                   │
-│                            ▼                                   │
-│  ╭─────────────────────────────────────────────────────────╮   │
-│  │              Parallel Processing                        │   │
-│  │                                                         │   │
-│  │ ╭─────────────────────╮   ╭─────────────────────────╮   │   │
-│  │ │   SvgConform        │   │     svgcheck            │   │   │
-│  │ │   Validation        │   │   ConformanceReport     │   │   │
-│  │ │                     │   │   (mapped)              │   │   │
-│  │ │ • Native Ruby       │   │ • Parsed from YAML      │   │   │
-│  │ │ • Direct profile    │   │ • Requirement-mapped    │   │   │
-│  │ │ • ConformanceReport │   │ • Compatible structure  │   │   │
-│  │ ╰─────────────────────╯   ╰─────────────────────────╯   │   │
-│  ╰─────────────┬───────────────────────┬───────────────────╯   │
-│                │                       │                       │
-│                └───────────┬───────────┘                       │
-│                            │                                   │
-│  ╭─────────────────────────▼─────────────────────────╮         │
-│  │              ReportComparator                     │         │
-│  │                                                   │         │
-│  │ • Direct ConformanceReport comparison             │         │
-│  │ • Unified requirement-based display               │         │
-│  │ • Side-by-side error mapping                      │         │
-│  │ • 🚨 RED highlighting for unmapped errors         │         │
-│  │ • Compatibility metrics and analysis              │         │
-│  ╰───────────────────────────────────────────────────╯         │
-│                                                                │
-╰────────────────────────────────────────────────────────────────╯
-----
-
-
-=== svgcheck compatibility commands
-
-==== General
-
-In order to run the compatibility commands, you need to have the `svgcheck` tool
-installed and accessible in your PATH.
-
-NOTE: The `svgcheck` tool can be installed via `pip install svgcheck`.
-
-The commands in this section provide functionality to generate svgcheck outputs
-for test files and perform compatibility analysis between SvgConform and svgcheck
-results.
-
-The test files from svgcheck are included in the SvgConform repository under
-`spec/fixtures/svgcheck` to ensure consistent testing.
-
-The mapping configuration file `config/svgcheck_mapping.yml` defines how
-svgcheck error messages are interpreted and mapped to SvgConform requirements.
-
-The data flow steps for compatibility analysis is as follows:
-
-. svgcheck outputs are generated for test files using the `svgcheck generate` command.
-
-. For each test file, svgcheck outputs are generated in both check-only and
-repair modes through the `svgcheck generate` command, and are then parsed by the
-`Svgcheck::Parser` class into the `ReportGenerator` class.
-
-. SvgConform validates the same test files using the SVG 1.2 RFC profile, which provides
-a `ConformanceReport` object.
-
-. The `ReportComparator` class compares the `ConformanceReport` from SvgConform
-with the svgcheck `ReportGenerator` results. The `ReportComparator` handles
-both check-only and repair mode outputs, and maps svgcheck messages to SvgConform
-requirements and remediations outcomes.
-
-. A detailed comparison report is generated, highlighting matches and discrepancies.
-
-
-
-==== `svg_conform svgcheck compatibility`
-
-The `svgcheck compatibility` command performs a comprehensive compatibility analysis
-between SvgConform validation results and the IETF `svgcheck` tool output.
+profile = SvgConform::Profiles.get(:metanorma)
+document = SvgConform::Document.from_file('input.svg')
 
-[source,bash]
-----
-svg_conform svgcheck compatibility [OPTIONS] [FILE]
+# Apply all remediations defined in the profile
+changes = profile.apply_remediations(document)
 
-Options:
-  -p, --profile PROFILE    Profile to use (default: svg_1_2_rfc)
-  -f, --file FILE          Analyze specific file instead of all test files
-  -o, --output FILE        Output clean report to file (no color codes)
-  -v, --verbose            Verbose output
-----
+puts "Applied #{changes.length} remediations"
 
-[example]
-====
-[source,bash]
+# Save the remediated SVG
+File.write('output.svg', document.to_xml)
 ----
-# Run comprehensive compatibility analysis
-svg_conform svgcheck compatibility
 
-# Analyze specific file
-svg_conform svgcheck compatibility --file example.svg
+==== Using the remediation runner
 
-# Generate clean report for documentation
-svg_conform svgcheck compatibility --output compatibility-report.md
+For more control over the remediation process:
 
-# Analyze specific file and save to file
-svg_conform svgcheck compatibility --file example.svg --output analysis.md
+[source,ruby]
 ----
-====
+profile = SvgConform::Profiles.get(:metanorma)
+runner = SvgConform::RemediationRunner.new(profile: profile)
 
+# Run remediation on a file
+result = runner.run_remediation_file('input.svg')
 
-==== `svg_conform svgcheck generate`
+if result.success?
+  File.write('output.svg', result.remediated_content)
+  puts "Fixed #{result.issues_fixed} issues"
+  puts "Final validation: #{result.final_validation.valid?}"
+else
+  puts "Remediation failed: #{result.error.message}"
+end
+----
 
-The `svgcheck generate` command generates svgcheck outputs for test files to
-facilitate compatibility analysis.
+==== Checking available remediations
 
-These files are generated in a structured output directory, with separate subdirectories
-for check-only and repair modes.
+[source,ruby]
+----
+profile = SvgConform::Profiles.get(:metanorma)
 
+puts "Profile has #{profile.remediation_count} remediations available"
 
-[source,bash]
+profile.remediations.each do |remediation|
+  puts "- #{remediation.class.name}"
+end
 ----
-Usage:
-  svg_conform svgcheck generate SVGCHECK_REPO_PATH
-
-Options:
-  -m, [--mode=MODE]                                  # Generation mode: check, repair, or both
-                                                     # Default: both
-                                                     # Possible values: check, repair, both
-      [--svgcheck-exec=SVGCHECK_EXEC]                # Path to svgcheck executable
-      [--fixtures-path=FIXTURES_PATH]                # Output directory (default: spec/fixtures/svgcheck)
-  -f, [--single-file=SINGLE_FILE]                    # Process single file only
-      [--force]                                      # Overwrite existing outputs
-                                                     # Default: false
-  -v, [--verbose], [--no-verbose], [--skip-verbose]  # Verbose output
-                                                     # Default: false
 
-Description:
-  Generate svgcheck outputs for test files by running svgcheck on them.
+=== Working with documents
 
-  SVGCHECK_REPO_PATH: Path to the svgcheck repository (e.g., svgcheck-reference)
+==== Creating documents
 
-  By default, processes all test files in SVGCHECK_REPO_PATH/svgcheck/Tests/ and generates BOTH check and repair
-  outputs in separate subdirectories.
+From a string:
 
-  Examples: svg_conform svgcheck generate svgcheck-reference svg_conform svgcheck generate svgcheck-reference --mode
-  check svg_conform svgcheck generate svgcheck-reference --single-file example.svg
+[source,ruby]
+----
+document = SvgConform::Document.new(svg_string)
 ----
 
-This command provides a bridge between SvgConform and the Python svgcheck tool,
-enabling comprehensive compatibility testing and analysis. By default, it
-generates both check and repair outputs in separate subdirectories.
-
-The command creates a structured output directory with separate subdirectories
-for different svgcheck modes:
+From a file:
 
-[source]
+[source,ruby]
 ----
-spec/fixtures/svgcheck/
-├── check/          # Check-only outputs (validation without remediation)
-│   ├── file1.svg.out   # Validation messages from svgcheck
-│   ├── file1.svg.err   # Error messages from svgcheck
-│   └── file1.svg.code  # Exit status from svgcheck
-└── repair/         # Repair outputs (validation + remediation)
-    ├── file1.svg.out   # Validation messages from svgcheck
-    ├── file1.svg.err   # Error messages from svgcheck
-    ├── file1.svg.code  # Exit status from svgcheck
-    └── file1.svg.file  # Remediated SVG content
+document = SvgConform::Document.from_file('path/to/file.svg')
 ----
 
-Some svgcheck test files are renamed to indicate their actual type of content,
-which is defined in `svgcheck_generate.rb`:
-
-* svgcheck `full-tiny.xml` is renamed to `full-tiny.svg`
-* svgcheck `rfc-svg.xml` is renamed to `rfc-svg.svg`
-
-The generated outputs are used by the `compatibility` command to perform
-detailed comparisons between SvgConform and svgcheck validation results. The
-structured directory layout enables:
-
-- **Targeted analysis**: Compare check-only vs repair mode behaviors
-- **Comprehensive testing**: Validate against both validation and remediation workflows
-- **Regression testing**: Track changes in svgcheck behavior over time
-- **Profile development**: Use svgcheck outputs as reference for profile refinement
+From a DOM node (Nokogiri or Moxml):
 
+[source,ruby]
+----
+nokogiri_element = Nokogiri::XML(svg_string).root
+document = SvgConform::Document.from_node(nokogiri_element)
+----
 
-There are three modes of operation for generating svgcheck outputs:
+==== Document operations
 
-**Check Mode** (`--mode check`):
+[source,ruby]
+----
+# Access the underlying DOM
+root = document.root
+elements = document.find_all('//svg:rect')
 
-- Runs svgcheck without the `--repair` flag
-- Only validates SVG files and reports errors
-- Generates `.out`, `.err`, and `.code` files
-- No remediated content is produced
+# Check for specific elements
+has_viewbox = document.root.attribute?('viewBox')
 
-**Repair Mode** (`--mode repair`):
+# Modify the document
+document.root.set_attribute('width', '500')
 
-- Runs svgcheck with the `--repair` flag
-- Validates SVG files and generates remediated content
-- Generates `.out`, `.err`, `.code`, and `.file` files
-- The `.file` contains the remediated SVG content
+# Serialize to XML
+xml_string = document.to_xml
+----
 
-**Both Mode** (`--mode both`, default):
+=== Reference manifest
 
-- Runs both check and repair modes for each file
-- Generates complete output sets in both subdirectories
-- Provides comprehensive data for compatibility analysis
+==== Accessing the manifest
 
-[source,bash]
+[source,ruby]
 ----
-# Generate both check and repair outputs for all test files
-svg_conform svgcheck generate /path/to/svgcheck-reference
+result = validator.validate(svg_content, profile: :metanorma)
+manifest = result.reference_manifest
 
-# Generate only check outputs
-svg_conform svgcheck generate /path/to/svgcheck-reference --mode check
-
-# Generate only repair outputs
-svg_conform svgcheck generate /path/to/svgcheck-reference --mode repair
-
-# Process a single file with verbose output
-svg_conform svgcheck generate /path/to/svgcheck-reference --single-file example.svg --verbose
+# Get all defined IDs
+manifest.available_ids.each do |id_def|
+  puts "ID: #{id_def.id_value}"
+  puts "  Element: #{id_def.element_name}"
+  puts "  Line: #{id_def.line_number}"
+end
+----
 
-# Force regeneration of existing outputs
-svg_conform svgcheck generate /path/to/svgcheck-reference --force
+==== Checking references
 
-# Use custom output directory
-svg_conform svgcheck generate /path/to/svgcheck-reference --fixtures-path /path/to/custom/output
+[source,ruby]
 ----
+# Check for unresolved internal references
+if result.has_unresolved_references?
+  puts "Unresolved references found:"
+  result.unresolved_internal_references.each do |ref|
+    puts "  #{ref.value} at line #{ref.line_number}"
+  end
+end
 
+# Check for external references
+if result.has_external_references?
+  puts "External references:"
+  result.external_references.each do |ref|
+    puts "  #{ref.value} (#{ref.reference_type})"
+  end
+end
+----
 
+==== Reference types
 
-==== `svg_conform svgcheck compare`
+The manifest classifies references by type:
 
-The `svgcheck compare` command compares SvgConform validation results with existing
-svgcheck reports to assess compatibility.
+[source,ruby]
+----
+manifest.internal_references.each do |ref|
+  case ref.reference_type
+  when 'url'
+    puts "URL reference: #{ref.value}"
+  when 'fragment'
+    puts "Fragment reference: #{ref.value}"
+  when 'fill'
+    puts "Fill attribute: #{ref.value}"
+  when 'href'
+    puts "Href attribute: #{ref.value}"
+  end
+end
+----
 
-This command is useful for verifying that SvgConform produces equivalent results
-to the IETF svgcheck tool.
+=== Advanced usage
 
-Syntax:
+==== Custom validation context
 
-[source,bash]
+[source,ruby]
 ----
-svg_conform svgcheck compare FILE [OPTIONS]
+context = SvgConform::ValidationContext.new(
+  document: document,
+  profile: profile
+)
 
-Options:
-  -p, --profile PROFILE        Profile to use (default: svg_1_2_rfc)
-      --svgcheck-report FILE   Path to svgcheck report (default: auto-detect)
+# Run specific requirements
+requirement = SvgConform::Requirements::ViewboxRequiredRequirement.new
+errors = requirement.check(context)
 ----
 
-[example]
-====
-[source,bash]
-----
-# Compare with auto-detected svgcheck report
-$ svg_conform svgcheck compare diagram.svg -p svg_1_2_rfc
+==== Batch processing
 
-# Specify svgcheck report explicitly
-$ svg_conform svgcheck compare diagram.svg --svgcheck-report diagram.svg.svgcheck.yaml
+[source,ruby]
 ----
-====
-
+validator = SvgConform::Validator.new
+results = {}
 
+Dir.glob('images/**/*.svg').each do |file|
+  result = validator.validate_file(file, profile: :metanorma)
+  results[file] = result
+end
 
-== Performance
+# Summary
+valid_count = results.count { |_, r| r.valid? }
+puts "#{valid_count}/#{results.size} files are valid"
+----
 
-=== SAX streaming validation
+==== Report generation
 
-SvgConform implements SAX (Simple API for XML) streaming validation for
-high-performance processing of large SVG files.
+[source,ruby]
+----
+# Create a conformance report
+report = SvgConform::ConformanceReport.from_svg_conform_result(
+  "file.svg",
+  result,
+  profile: :metanorma
+)
 
-Performance characteristics:
+# Export as JSON
+json_output = report.to_json
+File.write('report.json', json_output)
 
-* Small files (<1 MB): ~0.5s validation time
-* Medium files (1-5 MB): ~1s validation time (vs 60-80s with DOM)
-* Large files (>5 MB): ~2s validation time (vs minutes-hours with DOM)
+# Export as YAML
+yaml_output = report.to_yaml
+File.write('report.yaml', yaml_output)
+----
 
-Real-world samples results:
+=== API classes
 
-* 5.93 MB file: >` 60s → 1.89s (30x faster)
-* 4.57 MB file: >60s → 1.37s (40x faster)
-* 3.44 MB file: >60s → 0.29s (200x faster)
+==== Core classes
 
-How it works:
+* `SvgConform::Validator` - Main validation interface
+* `SvgConform::Profile` - Profile definition and management
+* `SvgConform::Document` - SVG document wrapper
+* `SvgConform::ValidationResult` - Validation result container
+* `SvgConform::RemediationRunner` - Remediation execution
 
-SAX streaming validation processes XML events without building a full DOM tree
-in memory. This provides:
+==== Requirement classes
 
-* Forward-only processing: Single pass through XML stream
-* Constant memory: No full DOM tree in memory
-* Predictable performance: O(n) complexity guaranteed
-* No object identity issues: Path-based node identification
+Located in `SvgConform::Requirements`:
 
-Mode selection:
+* `AllowedElementsRequirement` - Element whitelist validation
+* `ColorRestrictionsRequirement` - Color format restrictions
+* `FontFamilyRequirement` - Font family restrictions
+* `ForbiddenContentRequirement` - Forbidden element/attribute check
+* `IdReferenceRequirement` - ID reference validation
+* `InvalidIdReferencesRequirement` - Invalid reference detection
+* `LinkValidationRequirement` - Link validation
+* `NamespaceRequirement` - Namespace validation
+* `NamespaceAttributesRequirement` - Namespace attribute check
+* `NoExternalCssRequirement` - External CSS prohibition
+* `NoExternalFontsRequirement` - External font prohibition
+* `NoExternalImagesRequirement` - External image prohibition
+* `StylePromotionRequirement` - Presentation attribute check
+* `StyleRequirement` - Style attribute validation
+* `ViewboxRequiredRequirement` - ViewBox requirement
 
-By default, SAX mode is used for all validation operations. DOM mode is
-automatically used when remediation is requested (`fix: true`).
+==== Remediation classes
 
-[source,ruby]
-----
-# Default: SAX mode (best performance)
-validator = SvgConform::Validator.new
-result = validator.validate_file('large.svg', profile: :metanorma)
+Located in `SvgConform::Remediations`:
 
-# Explicit mode selection
-validator_sax = SvgConform::Validator.new(mode: :sax)  # Force SAX
-validator_dom = SvgConform::Validator.new(mode: :dom)  # Force DOM
-validator_auto = SvgConform::Validator.new(mode: :auto)  # File size based (>1MB uses SAX)
-----
+* `ColorRemediation` - Fix color format issues
+* `FontRemediation` - Fix font family issues
+* `FontEmbeddingRemediation` - Embed external fonts
+* `ImageEmbeddingRemediation` - Embed external images
+* `InvalidIdReferencesRemediation` - Fix invalid references
+* `NamespaceRemediation` - Fix namespace issues
+* `NamespaceAttributeRemediation` - Remove namespace attributes
+* `NoExternalCssRemediation` - Convert external CSS
+* `StylePromotionRemediation` - Promote presentation attributes
+* `ViewboxRemediation` - Add missing ViewBox
 
-Validation parity:
+=== Complete reference
 
-SAX mode produces identical validation results to DOM mode on 18/19 test files
-(94.7% parity). The one exception is `full-tiny.svg`, a comprehensive test file
-with known architectural differences.
+See link:docs/api_reference.adoc[API Reference] for comprehensive documentation including:
 
+* Complete class hierarchy
+* Detailed method signatures
+* Parameter descriptions
+* Return value specifications
+* Integration patterns
+* Advanced examples
 
 
-== Testing
+[[external_compliance]]
+== External compliance
 
-Run the test suite:
+SvgConform provides compatibility with existing SVG validation tools:
 
-[source,bash]
-----
-bundle exec rspec
-----
+* **SVGCheck**: 100% error report matching with Python svgcheck tool
+* Profile compatibility modes for different validation tools
 
-Run specific test categories:
+See link:docs/compatibility.adoc[Compatibility Documentation] for details.
 
-[source,bash]
-----
-# Unit tests
-bundle exec rspec spec/unit/
 
-# Integration tests
-bundle exec rspec spec/integration/
+== Development
 
-# SVGCheck compatibility tests
-bundle exec rspec spec/svgcheck_compatibility_spec.rb
-----
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
 
+To install this gem onto your local machine, run `bundle exec rake install`.
 
-== Changelog
 
-See link:CHANGELOG.md[CHANGELOG.md] for version history and changes.
+== Contributing
 
+Bug reports and pull requests are welcome on GitHub at https://github.com/metanorma/svg_conform.
 
-== Copyright and license
 
-Copyright Ribose.
+== License
 
-This gem is available as open source under the terms of the Ribose 2-clause BSD
-license.
+The gem is available as open source under the terms of the BSD 2-Clause License.