uniword 1.0.0 → 1.0.4

data/README.adoc

@@ -4,2183 +4,112 @@ image:https://img.shields.io/gem/v/uniword.svg[Gem Version,link=https://rubygems
 image:https://img.shields.io/github/license/metanorma/uniword.svg[License,link=https://github.com/metanorma/uniword/blob/main/LICENSE.txt]
 image:https://github.com/metanorma/uniword/actions/workflows/rake.yml/badge.svg[Build Status,link=https://github.com/metanorma/uniword/actions/workflows/rake.yml]
 
-== Purpose
+Uniword is a Ruby library for reading and writing Microsoft Word documents in DOCX (Word 2007+) and MHTML (Word 2003+) formats, with 100% OOXML specification coverage (760 elements, 22 namespaces) and perfect round-trip fidelity.
 
-Uniword is a comprehensive Ruby library for reading and writing Microsoft Word documents in both DOCX (Word 2007+) and MHTML (Word 2003+) formats.
+* Documentation: https://metanorma.github.io/uniword[Documentation Site]
+* API Reference: https://www.rubydoc.info/gems/uniword[RubyDoc.info]
 
-== Features
-
-* Full DOCX read/write support (Word 2007+)
-* Full MHTML read/write support (Word 2003+)
-* Format conversion (DOCX ↔ MHTML)
-* Styles (paragraph, character, table)
-* Lists (numbered, bulleted, multi-level)
-* Tables with borders and cell merging
-* Images with positioning
-* Headers and footers
-* Text boxes
-* Footnotes and endnotes
-* Bookmarks and cross-references
-* Math formulas (MathML/AsciiMath)
-* Fluent API and Builder pattern
-* Command-line interface
-* Comprehensive error handling
-
-== Architecture
-
-.High-level architecture of Uniword
-[source]
-----
-┌─────────────────────────────────────────────────────────────┐
-│                      Uniword Gem                            │
-│                   (Public API Layer)                        │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  ┌────────────────┐           ┌──────────────────┐         │
-│  │  Format Layer  │           │  Document Layer  │         │
-│  │                │           │                  │         │
-│  │ - DOCX Handler │◄──────────┤ - Document Model │         │
-│  │   (Read/Write) │           │   (lutaml-model) │         │
-│  │ - MHTML Handler│           │ - Element Models │         │
-│  │   (Read/Write) │           │ - Style Models   │         │
-│  └────────────────┘           └──────────────────┘         │
-│         │                              │                   │
-│         ▼                              ▼                   │
-│  ┌────────────────┐           ┌──────────────────┐         │
-│  │ Serialization  │           │  Component Layer │         │
-│  │     Layer      │           │                  │         │
-│  │                │           │ - Paragraphs     │         │
-│  │ - XML Parser/  │◄──────────┤ - Tables         │         │
-│  │   Serializer   │           │ - Images         │         │
-│  │   (lutaml)     │           │ - Lists          │         │
-│  │ - MIME Handler │           │ - Styles         │         │
-│  │ - ZIP Handler  │           │ - Runs           │         │
-│  └────────────────┘           └──────────────────┘         │
-└─────────────────────────────────────────────────────────────┘
-----
-
-The architecture follows strict object-oriented principles:
-
-* **SOLID principles** - Single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion
-* **MECE (Mutually Exclusive, Collectively Exhaustive)** - Clear separation of concerns with no overlap
-* **Separation of Concerns** - Layered architecture with distinct responsibilities
-* **Design Patterns** - Strategy, Factory, Visitor, Builder, Template Method, Registry, Adapter patterns
-* **Model-Driven Architecture** - Each OOXML part is a separate lutaml-model class
-
-== Schema-Driven Architecture
-
-Uniword uses a schema-driven architecture where document classes are generated from complete OOXML specification coverage.
-
-=== Generated Classes
-
-The core API consists of generated classes from 760 OOXML elements across 22 namespaces, providing 100% specification coverage and perfect round-trip fidelity.
-
-[source,ruby]
-----
-require 'uniword'
-
-# Main document classes
-doc = Uniword::Document.new
-para = doc.add_paragraph("Hello World", bold: true)
-
-# All classes support lutaml-model serialization automatically
-xml = doc.to_xml                          # Automatic XML generation
-doc2 = Uniword::Document.from_xml(xml)    # Automatic deserialization
-----
-
-=== Extension Methods
-
-Generated classes are enhanced with Ruby convenience methods via extension modules, providing a rich, fluent API:
-
-[source,ruby]
-----
-doc = Uniword::Document.new
-
-# Fluent document building
-doc.add_paragraph("Title", bold: true, size: 24)
-   .add_paragraph("Content paragraph", italic: true)
-   
-# Table creation
-table = doc.add_table(3, 4)  # 3 rows, 4 columns
-
-# Theme and StyleSet support
-doc.apply_theme('celestial')
-doc.apply_styleset('distinctive')
-
-# Save and load
-doc.save('output.docx')
-doc2 = Uniword.load('output.docx')
-----
-
-=== Key Benefits
-
-* ✅ **100% OOXML Coverage** - All 760 elements from 22 namespaces modeled
-* ✅ **Zero Hardcoding** - All XML generation handled by lutaml-model
-* ✅ **Type Safety** - Strong typing for all attributes and elements
-* ✅ **Perfect Round-Trip** - Guaranteed by complete modeling
-* ✅ **Extension System** - Ruby convenience methods without modifying generated code
-* ✅ **Maintainability** - Changes to OOXML spec only require YAML schema updates
-
-=== DocxPackage - Core Architecture
-
-Uniword uses a **pure object-oriented approach** where each XML file in the DOCX ZIP package is represented by a dedicated lutaml-model class. This eliminates the serialization/deserialization anti-pattern and provides perfect round-trip fidelity.
-
-.DocxPackage structure
-[source,ruby]
-----
-class DocxPackage < Lutaml::Model::Serializable
-  # Metadata (fully modeled)
-  attribute :core_properties, CoreProperties      # docProps/core.xml
-  attribute :app_properties, AppProperties        # docProps/app.xml
-
-  # Theme (fully modeled)
-  attribute :theme, Theme                         # word/theme/theme1.xml
-
-  # Document content (in progress)
-  attribute :document, Document                   # word/document.xml
-  attribute :styles, StylesConfiguration          # word/styles.xml
-  # ... other parts
-
-  def self.from_file(path)
-    # Load DOCX and deserialize all parts
-  end
-
-  def to_file(path)
-    # Serialize all parts and package as DOCX
-  end
-end
-----
-
-**Benefits of this approach:**
-
-* ✅ **Zero hardcoding** - All XML generation handled by lutaml-model
-* ✅ **Type safety** - Strong typing for all attributes
-* ✅ **Perfect round-trip** - Guaranteed by model serialization
-* ✅ **Easy testing** - Each model class is independently testable
-* ✅ **Maintainability** - Changes isolated to model definitions
-
-=== Namespace Handling
-
-Uniword uses **native namespace support** via lutaml-model v0.7+ XmlNamespace classes:
-
-.Namespace definition example
-[source,ruby]
-----
-module Namespaces
-  class WordProcessingML < Lutaml::Model::XmlNamespace
-    uri 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
-    prefix_default 'w'
-    element_form_default :qualified
-  end
-end
-----
-
-.Using namespace in models
-[source,ruby]
-----
-class Document < Lutaml::Model::Serializable
-  xml do
-    root 'document'
-    namespace Namespaces::WordProcessingML
-
-    map_element 'body', to: :body
-  end
-
-  attribute :body, Body
-end
-----
-
-**Supported namespaces:**
-
-* `w:` - WordProcessingML (main document elements) - ✅ **100 elements (v2.0)**
-* `m:` - Office Math Markup Language (equations) - ✅ **65 elements (v2.0)**
-* `a:` - DrawingML Main (graphics, effects, colors) - ✅ **92 elements (v2.0)**
-* `pic:` - Picture (embedded images) - ✅ **10 elements (v2.0)**
-* `r:` - Relationships (document part relationships) - ✅ **5 elements (v2.0)**
-* `wp:` - DrawingML WordProcessing Drawing (positioning) - ✅ **27 elements (v2.0)**
-* `ct:` - Content Types (MIME type definitions) - ✅ **3 elements (v2.0)**
-* `v:` - VML (legacy compatibility) - ✅ **15 elements (v2.0)**
-* `o:` - Office (shared properties) - ✅ **40 elements (v2.0)**
-* `v:o:` - VML Office extensions - ✅ **25 elements (v2.0)**
-* `dp:` - Document Properties (core/app metadata) - ✅ **20 elements (v2.0)**
-* `w14:` - Word 2010 Extended (enhanced controls, text effects) - ✅ **25 elements (v2.0)**
-* `w15:` - Word 2013 Extended (collaboration, comments) - ✅ **20 elements (v2.0)**
-* `w16:` - Word 2016 Extended (accessibility, modern formatting) - ✅ **15 elements (v2.0)**
-* `xls:` - SpreadsheetML (Excel integration) - ✅ **83 elements (v2.0)**
-* `c:` - Chart (charts and graphs) - ✅ **70 elements (v2.0)**
-* `p:` - PresentationML (PowerPoint integration) - ✅ **50 elements (v2.0)**
-* `cxml:` - Custom XML (structured data integration) - ✅ **29 elements (v2.0)**
-* `b:` - Bibliography (citation management) - ✅ **24 elements (v2.0)**
-* `g:` - Glossary (building blocks, AutoText) - ✅ **19 elements (v2.0)**
-* `st:` - Shared Types (common type definitions) - ✅ **15 elements (v2.0)**
-* `dv:` - Document Variables (variable substitution) - ✅ **10 elements (v2.0)**
-* **Total**: **760/760 elements complete (100.0%)** - 🎉 **PHASE 2 COMPLETE!** 🎉
-
-=== Critical Implementation Pattern: lutaml-model Attributes
-
-**🚨 THE MOST IMPORTANT RULE FOR CONTRIBUTORS:**
-
-When creating or modifying lutaml-model classes, **attributes MUST be declared BEFORE xml mappings**:
-
-[source,ruby]
-----
-# ✅ CORRECT - Attributes FIRST
-class MyClass < Lutaml::Model::Serializable
-  attribute :my_attr, MyType  # Declare attribute first
-  
-  xml do
-    element 'myElem'
-    namespace Namespaces::WordProcessingML
-    map_element 'elem', to: :my_attr  # Map after
-  end
-end
-
-# ❌ WRONG - Will NOT serialize
-class MyClass < Lutaml::Model::Serializable
-  xml do
-    map_element 'elem', to: :my_attr  # Mapping before attribute
-  end
-  
-  attribute :my_attr, MyType  # Too late! Framework doesn't know it exists
-end
-----
-
-**Why this matters:**
-
-* Lutaml-model builds its internal schema by reading attribute declarations sequentially
-* If xml mappings come first, the framework processes them before knowing attributes exist
-* Result: Serialization produces empty XML, deserialization fails silently
-* This was the root cause of complete document serialization failure in v1.1.0 development
-
-**Additional rules:**
-
-* Use `mixed_content` for elements with nested content
-* Only ONE namespace declaration per element level
-* Use `render_default: true` for optional elements that must always appear
-* In `initialize`, use `||=` not `=` to preserve lutaml-model parsed values
-
-=== v2.0 Architecture: Schema-Driven Generation
-
-**Uniword v2.0** introduces a radical architectural improvement: **100% schema-driven OOXML modeling** with ZERO raw XML storage.
-
-==== Core Principle
-
-NO RAW XML STORAGE - EVER. Every OOXML element is a proper lutaml-model class generated from YAML schemas.
-
-==== Schema System
-
-.Schema definition example
-[source,yaml]
-----
-# config/ooxml/schemas/wordprocessingml.yml
-namespace:
-  uri: 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
-  prefix: 'w'
-
-elements:
-  p:
-    class_name: Paragraph
-    description: 'Paragraph - block-level text element'
-    attributes:
-      - name: properties
-        type: ParagraphProperties
-        xml_name: pPr
-      - name: runs
-        type: Run
-        collection: true
-        xml_name: r
-----
-
-==== Model Generation
-
-Classes are automatically generated from schemas:
-
-[source,ruby]
-----
-require 'uniword/schema/model_generator'
-
-generator = Uniword::Schema::ModelGenerator.new('wordprocessingml')
-generator.generate_all
-# => Generates 200+ lutaml-model classes from YAML schema
-----
-
-**Generated classes** enforce Pattern 0 (attributes before xml blocks) automatically and provide complete type safety.
-
-==== Benefits
-
-* ✅ **100% ISO 29500 coverage** - All 600+ OOXML elements modeled
-* ✅ **Zero hardcoding** - All structure defined in YAML
-* ✅ **Perfect round-trip** - Guaranteed by complete modeling
-* ✅ **Easy extensibility** - Add elements by editing YAML
-* ✅ **Community contributions** - Schema editing simpler than code
-
-=== Round-Trip Fidelity
-
-Uniword achieves **100% round-trip fidelity** for DOCX documents through complete OOXML modeling:
-
-* ✅ **Perfect content preservation** - All text, formatting, and structure maintained
-* ✅ **Complete element coverage** - All OOXML elements properly modeled (v2.0)
-* ✅ **Namespace compliance** - All required OOXML namespaces supported
-* ✅ **UTF-8 encoding** - Proper character encoding throughout
-* ✅ **Tested with complex documents** - ISO 8601 scientific documents, MHTML conversion
-* ✅ **Model-driven architecture** - All XML structures represented as Ruby objects
-
-.Round-trip example
-[source,ruby]
-----
-# Load document
-original = Uniword::Document.open('complex.docx')
-
-# Modify it
-original.add_paragraph("New content")
-
-# Save back - EVERYTHING preserved
-original.save('modified.docx')
-
-# Verify: modified.docx has ALL original content + new paragraph
-----
-
-**Test results:**
-
-* ISO 8601 DOCX (295KB): ✅ 100% fidelity
-* MHTML documents: ✅ Content preserved
-* Math equations: ✅ Preserved via m: namespace
-* Bookmarks: ✅ Native support with ID preservation
-* Complex documents: ✅ Perfect round-trip with schema-driven architecture (v2.0)
-
-== Installation
-
-Add this line to your application's Gemfile:
-
-[source,ruby]
-----
-gem 'uniword'
-----
-
-And then execute:
-
-[source,shell]
-----
-bundle install
-----
-
-Or install it yourself as:
-
-[source,shell]
-----
-gem install uniword
-----
-
-== Architecture: Autoload Strategy
-
-Uniword uses Ruby's `autoload` mechanism for lazy loading of most classes, achieving 90% autoload coverage for improved startup performance and maintainability.
-
-=== Autoload Coverage
-
-* **95 autoload statements**: Classes loaded on-demand when first accessed
-* **10 require_relative statements**: Well-documented exceptions for architectural necessities
-
-=== Architectural Exceptions
-
-The following 10 files MUST use `require_relative` (not `autoload`):
-
-**Base Requirements (2)**::
-  * `uniword/version` - Version constants needed by gem metadata
-  * `uniword/ooxml/namespaces` - Namespace constants referenced by generated classes
-
-**Namespace Modules (6)**::
-  * Core namespaces (wordprocessingml, wp_drawing, drawingml, vml, math, shared_types)
-  * Required due to deep cross-dependencies with format handlers
-  * Constant assignments require immediate class resolution
-
-**Format Handlers (2)**::
-  * `formats/docx_handler` and `formats/mhtml_handler`
-  * Self-registration side effects require eager loading
-
-[NOTE]
-====
-These exceptions are architectural necessities, not technical debt. Attempting to autoload these modules would cause NameError or break core functionality.
-====
-
-=== Performance Benefits
-
-* **Faster startup**: Only essential classes loaded initially
-* **Lower memory footprint**: Unused features don't consume memory
-* **Better maintainability**: Clear separation between eager and lazy loading
-
-== Quick start
-
-=== Creating documents
-
-[source,ruby]
-----
-require 'uniword'
-
-# Simple document
-doc = Uniword::Document.new
-para = Uniword::Paragraph.new
-para.add_text("Hello World", bold: true)
-doc.add_element(para)
-doc.save('output.docx')
-----
-
-=== Reading documents
-
-[source,ruby]
-----
-doc = Uniword::DocumentFactory.from_file('input.docx')
-puts doc.text
-doc.paragraphs.each { |p| puts p.text }
-----
-
-== Usage guide
-
-=== Text formatting
-
-==== Basic text formatting
-
-[source,ruby]
-----
-para = Uniword::Paragraph.new
-para.add_text("Bold", bold: true)
-para.add_text(" Italic", italic: true)
-para.add_text(" Underline", underline: 'single')
-para.add_text(" Red text", color: 'FF0000')
-para.add_text(" Large text", size: 24)
-para.add_text(" Custom font", font: 'Arial')
-----
-
-==== Combined formatting
-
-[source,ruby]
-----
-para = Uniword::Paragraph.new
-para.add_text("Bold italic red",
-  bold: true,
-  italic: true,
-  color: 'FF0000',
-  size: 18
-)
-=== Enhanced properties
-
-==== Paragraph borders
-
-Uniword supports all paragraph border positions with detailed styling options:
-
-[source,ruby]
-----
-para = Uniword::Paragraph.new
-para.add_text("Text with borders")
-
-# Simple borders (just color)
-para.set_borders(top: "FF0000", bottom: "0000FF")
-
-# Detailed borders with style, size, and color
-para.set_borders(
-  top: { style: 'single', size: 4, color: 'FF0000' },
-  bottom: { style: 'double', size: 6, color: '0000FF' },
-  left: { style: 'dashed', size: 4, color: '00FF00' },
-  right: { style: 'dotted', size: 4, color: 'FFFF00' }
-)
-
-# All border positions available:
-# top, bottom, left, right, between (for consecutive paragraphs), bar
-----
-
-**Border styles:** `single`, `double`, `dashed`, `dotted`, `thick`, `thin`, `none`
-
-==== Paragraph shading
-
-Add background colors and patterns to paragraphs:
-
-[source,ruby]
-----
-para = Uniword::Paragraph.new
-para.add_text("Highlighted text")
-
-# Simple solid fill
-para.set_shading(fill: "FFFF00")
-
-# With pattern and foreground color
-para.set_shading(
-  fill: "FFFF00",      # Background color
-  color: "000000",     # Foreground (pattern) color
-  pattern: "pct10"     # Pattern type
-)
-----
-
-**Pattern types:** `clear`, `solid`, `pct5`, `pct10`, `pct15`, `pct20`, `pct25`, `pct30`, `pct35`, `pct40`, `pct45`, `pct50`, `pct55`, `pct60`, `pct65`, `pct70`, `pct75`, `pct80`, `pct85`, `pct90`, `pct95`
-
-==== Tab stops
-
-Add custom tab stops with alignment and leader characters:
-
-[source,ruby]
-----
-para = Uniword::Paragraph.new
-para.add_text("Column 1\tColumn 2\tColumn 3")
-
-# Add tab stops
-para.add_tab_stop(position: 1440, alignment: "left")    # 1 inch
-para.add_tab_stop(position: 2880, alignment: "center")  # 2 inches
-para.add_tab_stop(position: 4320, alignment: "right", leader: "dot")  # 3 inches
-
-# Multiple tab stops
-para.add_tab_stop(position: 720)   # Default left alignment
-para.add_tab_stop(position: 1440, alignment: "center")
-para.add_tab_stop(position: 2160, alignment: "decimal", leader: "dot")
-----
-
-**Alignment options:** `left`, `center`, `right`, `decimal`, `bar`
-
-**Leader options:** `none`, `dot`, `hyphen`, `underscore`, `heavy`, `middleDot`
-
-**Position units:** Twips (1/20th of a point, 1440 twips = 1 inch)
-
-==== Character spacing and text effects
-
-Enhanced text formatting options for fine-grained control:
-
-[source,ruby]
-----
-run = Uniword::Run.new(text: "Enhanced text")
-
-# Character spacing (expand or condense)
-run.character_spacing = 20   # Expand by 20 twips (1 point)
-run.character_spacing = -10  # Condense by 10 twips (0.5 point)
-
-# Kerning (font kerning threshold)
-run.kerning = 24  # Enable kerning at 24 half-points (12pt)
-
-# Raised/lowered position (superscript/subscript effect)
-run.position = 5   # Raise by 5 half-points
-run.position = -5  # Lower by 5 half-points
-
-# Text expansion/compression percentage
-run.text_expansion = 120  # 120% width (expanded)
-run.text_expansion = 80   # 80% width (condensed)
-
-# Text effects
-run.outline = true   # Outline text
-run.shadow = true    # Shadow effect
-run.emboss = true    # Embossed (raised) effect
-run.imprint = true   # Imprinted (depressed) effect
-
-# Emphasis marks (Asian typography)
-run.emphasis_mark = "dot"      # Dot above/below text
-run.emphasis_mark = "comma"    # Comma mark
-run.emphasis_mark = "circle"   # Circle mark
-run.emphasis_mark = "underDot" # Dot below text
-
-# Language settings
-run.language = "en-US"  # Set text language for spell-checking
-----
-
-==== Run shading
-
-Apply background colors to character runs:
-
-[source,ruby]
-----
-run = Uniword::Run.new(text: "Highlighted")
-
-# Simple shading
-run.set_shading(fill: "FFFF00", pattern: "solid")
-
-# With foreground color and pattern
-run.set_shading(
-  fill: "FFFF00",     # Background
-  color: "000000",    # Foreground
-  pattern: "pct10"    # 10% pattern
-)
-----
-
-==== Complex combinations
-
-All enhanced properties can be combined freely:
-
-[source,ruby]
-----
-# Paragraph with borders, shading, and tabs
-para = Uniword::Paragraph.new
-para.add_text("Professional formatting")
-para.set_borders(top: "000000", bottom: "000000")
-para.set_shading(fill: "F0F0F0", pattern: "solid")
-para.add_tab_stop(position: 1440, alignment: "center")
-
-# Run with multiple effects
-run = para.runs.first
-run.character_spacing = 20
-run.kerning = 24
-run.position = 5
-run.outline = true
-run.shadow = true
-run.set_shading(fill: "FFFF00")
-----
-
-=== Styles
-
-==== Using built-in styles
-
-[source,ruby]
-----
-# Heading styles
-heading = Uniword::Paragraph.new
-heading.set_style('Heading1')
-heading.add_text("Chapter 1")
-
-# Normal style
-para = Uniword::Paragraph.new
-para.set_style('Normal')
-para.add_text("Body text")
-----
-
-==== Creating custom styles
-
-[source,ruby]
-----
-# Create custom paragraph style
-doc.styles_configuration.create_paragraph_style(
-  'CustomStyle',
-  'My Custom Style',
-  paragraph_properties: Uniword::Properties::ParagraphProperties.new(
-    alignment: 'center',
-    spacing_before: 240,
-    spacing_after: 120
-  ),
-  run_properties: Uniword::Properties::RunProperties.new(
-    bold: true,
-    color: '0000FF',
-    size: 24
-  )
-)
-
-# Use custom style
-para = Uniword::Paragraph.new
-para.set_style('CustomStyle')
-para.add_text("Styled text")
-----
-
-=== StyleSets
-
-==== What are StyleSets
-
-StyleSets are collections of professionally designed style definitions provided by Microsoft Office.
-They work alongside themes to create beautifully formatted documents with consistent styling.
-
-A StyleSet (.dotx file) contains:
-
-* Style definitions for headings, body text, quotes, etc.
-* Paragraph formatting (spacing, indentation, alignment)
-* Character formatting (fonts, colors, sizes)
-* Table styles
-
-==== Loading StyleSets from .dotx files
-
-[source,ruby]
-----
-# Load StyleSet from .dotx file
-styleset = Uniword::StyleSet.from_dotx('path/to/Distinctive.dotx')
-
-puts styleset.name
-# => "Distinctive"
-
-puts styleset.styles.count
-# => 42
-
-# Apply to document
-doc = Uniword::Document.new
-styleset.apply_to(doc)
-
-# Now document has all Distinctive styles
-doc.add_paragraph("Heading", heading: :heading_1)
-doc.save('output.docx')
-----
-
-==== Using bundled StyleSets
-
-Uniword includes all Office StyleSets as bundled YAML files for fast loading:
-
-[source,ruby]
-----
-# Load bundled StyleSet by name
-styleset = Uniword::StyleSet.load('distinctive')
-
-# Apply to document
-doc = Uniword::Document.new
-styleset.apply_to(doc)
-
-# Or use shorthand method
-doc.apply_styleset('distinctive')
-
-# List available bundled StyleSets
-available = Uniword::StyleSet.available_stylesets
-# => ["distinctive", "elegant", "fancy", "formal", ...]
-----
-
-==== Combining themes and StyleSets
-
-Themes define colors and fonts, while StyleSets define style formatting.
-Use them together for professional documents:
-
-[source,ruby]
-----
-doc = Uniword::Document.new
-
-# Apply theme (colors and fonts)
-doc.apply_theme('celestial')
-
-# Apply StyleSet (style definitions)
-doc.apply_styleset('distinctive')
-
-# Use the styled content
-doc.add_paragraph('Document Title', heading: :heading_1)
-doc.add_paragraph('Introduction paragraph with consistent styling.')
-
-doc.save('professional_document.docx')
-----
-
-==== StyleSet conflict resolution strategies
-
-When applying a StyleSet, you can control how conflicts with existing styles are handled:
-
-[source,ruby]
-----
-# Keep existing styles, add only new ones (default)
-styleset.apply_to(doc, strategy: :keep_existing)
-
-# Replace existing styles with StyleSet styles
-styleset.apply_to(doc, strategy: :replace)
-
-# Keep both, rename imported styles
-styleset.apply_to(doc, strategy: :rename)
-----
-
-==== StyleSet implementation status
-
-✅ **Phase 3 Session 5 COMPLETE (November 30, 2024)** - ALL 25 PROPERTIES IMPLEMENTED! 🎉
-
-* **24 StyleSets supported** - 12 style-sets + 12 quick-styles from `.dotx` files
-* **168/168 tests passing** - Perfect serialization and round-trip preservation (100% success rate)
-* **25/25 properties implemented** - 100% property coverage achieved!
-  * 20 simple properties ✅
-  * 5 complex properties ✅
-* **Correct architecture** - Uses lutaml-model v0.7+ with namespaced custom types, no backward compatibility cruft
-* **Week 1 complete** - Finished 2 days ahead of schedule!
-
-**Simple properties preserved in round-trip (20/20 complete):**
-
-_Paragraph Properties:_
-* ✅ Paragraph alignment (left, center, right, both, distribute)
-* ✅ Style references (paragraph and run styles)
-* ✅ Outline levels (0-9 for table of contents)
-* ✅ Numbering ID (list reference) - link:lib/uniword/properties/numbering_id.rb[numbering_id.rb]
-* ✅ Numbering level (0-8 nesting) - link:lib/uniword/properties/numbering_level.rb[numbering_level.rb]
-* ✅ Keep with next paragraph (boolean)
-* ✅ Keep lines together (boolean)
-* ✅ Page break before (boolean)
-* ✅ Widow/orphan control (boolean, default on)
-* ✅ Contextual spacing (boolean)
-
-_Run Properties:_
-* ✅ Font sizes (regular and complex script) in half-points
-* ✅ Font colors (RGB hex values)
-* ✅ Underline styles (single, double, dashed, etc.) - link:lib/uniword/properties/underline.rb[underline.rb]
-* ✅ Highlight colors (yellow, green, cyan, etc.) - link:lib/uniword/properties/highlight.rb[highlight.rb]
-* ✅ Vertical alignment (superscript, subscript, baseline) - link:lib/uniword/properties/vertical_align.rb[vertical_align.rb]
-* ✅ Position (raised/lowered text in half-points) - link:lib/uniword/properties/position.rb[position.rb]
-* ✅ Character spacing (expand/condense in twips) - link:lib/uniword/properties/character_spacing.rb[character_spacing.rb]
-* ✅ Kerning (threshold in half-points) - link:lib/uniword/properties/kerning.rb[kerning.rb]
-* ✅ Width scale (percentage 50-600) - link:lib/uniword/properties/width_scale.rb[width_scale.rb]
-* ✅ Emphasis marks (dot, comma, circle, etc.) - link:lib/uniword/properties/emphasis_mark.rb[emphasis_mark.rb]
-
-_Complex Properties (5/5 complete):_
-* ✅ Spacing (before, after, line spacing with complex object)
-* ✅ Indentation (left, right, first-line, hanging with complex object)
-* ✅ Font families (ASCII, East Asian, complex script with RunFonts object)
-* ✅ Borders (top/bottom/left/right with style, size, color) - link:lib/uniword/properties/borders.rb[borders.rb], link:lib/uniword/properties/border.rb[border.rb]
-* ✅ Tabs (tab stop collection with alignment, position, leader) - link:lib/uniword/properties/tabs.rb[tabs.rb], link:lib/uniword/properties/tab_stop.rb[tab_stop.rb]
-* ✅ Shading (background fill with pattern, color, fill) - link:lib/uniword/properties/shading.rb[shading.rb]
-* ✅ Language (language settings for val/eastAsia/bidi scripts) - link:lib/uniword/properties/language.rb[language.rb]
-* ✅ TextEffects (text fill and outline - basic solid color support) - link:lib/uniword/properties/text_fill.rb[text_fill.rb], link:lib/uniword/properties/text_outline.rb[text_outline.rb]
-
-_Boolean Flags:_
-* ✅ Bold, italic, small caps, caps, hidden, strike-through
-
-**Implementation details:**
-* Pattern documented in link:old-docs/CORRECTED_PROPERTY_SERIALIZATION_PATTERN.md[CORRECTED_PROPERTY_SERIALIZATION_PATTERN.md] (archived)
-* Uses namespaced custom types (e.g., `AlignmentValue < Lutaml::Model::Type::String`)
-* Proper element syntax (`element 'jc'` not obsolete `root`)
-* Namespace class references (not inline strings)
-* Single clean attributes (no dual attributes or _obj suffixes)
-* Attributes declared BEFORE xml mappings (Pattern 0 - CRITICAL)
-
-**Phase 3 Week 1 COMPLETE!** ✅ Week 2 (Theme Round-Trip) next - See link:PHASE3_WEEK2_CONTINUATION_PROMPT.md[Phase 3 Week 2 Plan]
-
-==== Available Office StyleSets
-
-Uniword bundles the following Office StyleSets:
-
-* **Basic (Word 2010)** - Simple, clean formatting
-* **Distinctive** - Bold headings with color accents
-* **Elegant** - Refined, professional appearance
-* **Fancy** - Decorative, attention-grabbing
-* **Formal** - Traditional business document styling
-* **Manuscript** - Book-style formatting
-* **Modern** - Contemporary, minimalist design
-* **Newsprint** - Newspaper-style columns and headers
-* **Perspective** - Dynamic, angled headings
-* **Simple** - Minimal, unobtrusive formatting
-* **Thatch** - Textured, organic appearance
-* **Traditional** - Classic document styling
-
-=== Themes
-
-==== What are Themes
-
-Themes are color and font scheme definitions provided by Microsoft Office that control the visual appearance of documents. They work alongside StyleSets to create beautifully formatted documents with consistent colors and typography.
-
-A theme (.thmx file) contains:
-
-* Color scheme (12 theme colors: 2 dark, 2 light, 6 accents, 2 hyperlinks)
-* Font scheme (major fonts for headings, minor fonts for body text)
-* Effect scheme (3D effects, shadows, reflections)
-
-==== Loading themes from .thmx files
-
-[source,ruby]
-----
-# Load theme from .thmx file
-theme = Uniword::Theme.from_thmx('path/to/Celestial.thmx')
-
-puts theme.name
-# => "Celestial"
-
-# Apply to document
-doc = Uniword::Document.new
-doc.theme = theme
-
-# Theme colors and fonts now available
-doc.save('output.docx')
-----
-
-==== Using bundled themes
-
-Uniword includes all 28 Office themes as bundled YAML files for fast loading:
-
-[source,ruby]
-----
-# Load bundled theme by name
-theme = Uniword::Theme.load('celestial')
-
-# Apply to document
-doc = Uniword::Document.new
-doc.theme = theme
-
-# Or use shorthand method
-doc.apply_theme('celestial')
-
-# List available bundled themes
-available = Uniword::Theme.available_themes
-# => ["atlas", "badge", "berlin", "celestial", ...]
-----
-
-==== Combining themes and StyleSets
-
-Themes and StyleSets work together for professional documents:
-
-[source,ruby]
-----
-doc = Uniword::Document.new
-
-# Apply theme (colors and fonts)
-doc.apply_theme('celestial')
-
-# Apply StyleSet (style definitions)
-doc.apply_styleset('distinctive')
-
-# Content uses theme colors and StyleSet formatting
-doc.add_paragraph('Title', heading: :heading_1)
-doc.add_paragraph('Body text in theme colors.')
-
-doc.save('professional_document.docx')
-----
-
-==== Theme implementation status
-
-✅ **Phase 3 Session 5 COMPLETE (December 1, 2024)** - ALL 29 THEMES 100% ROUND-TRIP! 🎉
-
-* **29 Office themes supported** - All themes from Office 2007-2024
-* **174/174 tests passing** - Perfect serialization and round-trip preservation (100% success rate)
-* **Complete DrawingML support** - All 92 DrawingML elements modeled
-* **Correct architecture** - Pure lutaml-model, no raw XML storage
-* **Phase 3 Week 2 complete** - Achieved 100% fidelity!
-
-**Theme components implemented:**
-
-_Color System (12 theme colors):_
-* ✅ SchemeColor with 10 color modifiers (alpha, tint, shade, etc.)
-* ✅ SrgbColor with 10 color modifiers
-* ✅ Color scheme (dk1, lt1, dk2, lt2, accent1-6, hlink, folHlink)
-
-_Font System:_
-* ✅ Font scheme (major/minor fonts with latin, eastAsian, complex script variants)
-* ✅ Font substitution table for compatibility
-* ✅ Empty attribute preservation (typeface="" cases)
-
-_Effects System:_
-* ✅ Format scheme (line styles, fill styles, effect styles, background fills)
-* ✅ EffectList (glow, inner/outer shadow, reflection, soft edge)
-* ✅ 3D effects (Scene3D, Shape3D, Camera, LightRig, Rotation, BevelTop)
-
-_Graphics:_
-* ✅ Gradient fills (linear, path, rotWithShape)
-* ✅ Solid fills with scheme/RGB colors
-* ✅ BlipFill for background images
-* ✅ Line properties (solid, gradient, pattern fills)
-* ✅ Duotone effects
-
-_Object Defaults:_
-* ✅ Line defaults with style references
-* ✅ Style matrix (line/fill/effect/font references)
-* ✅ Shape and body properties
-
-**Critical fixes that achieved 100%:**
-* ✅ Blip namespace fix (r:embed attribute) - Fixed 10 themes!
-* ✅ SoftEdge integration to EffectList - Fixed 1 theme (Wood Type)
-* ✅ ObjectDefaults architecture - Fixed 1 theme (Office Theme)
-* ✅ Transform2D bug fix (false→:off)
-
-**Round-trip guarantee:**
-All 29 themes achieve perfect round-trip fidelity - load a .thmx file, serialize it back, and the XML is semantically equivalent (verified with Canon gem).
-
-**Test results:**
-```
-Theme Round-Trip: 174 examples, 0 failures (100%) ✅
-StyleSet Round-Trip: 168 examples, 0 failures (100%) ✅
-Total: 342/342 (100%) ✅
-```
-
-==== Available Office Themes
-
-Uniword bundles the following Office themes:
-
-* **Atlas** - Modern, professional blue-gray palette
-* **Badge** - Bold, attention-grabbing design
-* **Berlin** - Cool, contemporary color scheme
-* **Celestial** - Cosmic, purple-blue gradients
-* **Crop** - Nature-inspired green tones
-* **Depth** - Rich, layered colors
-* **Droplet** - Fresh, water-inspired blues
-* **Facet** - Geometric, modern design
-* **Feathered** - Soft, elegant colors
-* **Gallery** - Artistic, creative palette
-* **Headlines** - Bold, newspaper-style
-* **Integral** - Integrated, balanced colors
-* **Ion** - Electric, energetic design
-* **Ion Boardroom** - Professional Ion variant
-* **Madison** - Classic, refined styling
-* **Main Event** - Celebratory, vibrant
-* **Mesh** - Interconnected, network design
-* **Office 2013-2022 Theme** - Default Office theme
-* **Office Theme** - Classic Office styling
-* **Organic** - Natural, earthy tones
-* **Parallax** - Layered, depth effect
-* **Parcel** - Packaged, contained design
-* **Retrospect** - Nostalgic, vintage colors
-* **Savon** - Clean, soap-inspired palette
-* **Slice** - Sharp, geometric cuts
-* **Vapor Trail** - Ethereal, flowing design
-* **View** - Perspective, architectural
-* **Wisp** - Delicate, light colors
-* **Wood Type** - Woodgrain, natural textures
-
-=== Building Blocks (Glossary)
-
-==== What are Building Blocks
-
-Building Blocks are reusable content pieces provided by Microsoft Word, also known as Glossary documents. They allow users to insert pre-formatted content like headers, footers, cover pages, tables of contents, equations, and custom text blocks into documents.
-
-A Building Block (.dotx template) contains:
-
-* **Document Parts** - Individual building block entries
-* **Properties** - Name, category, gallery, behaviors, description, style, GUID
-* **Content** - Paragraphs, tables, and structured document tags (SDTs)
-
-==== Understanding Building Block Structure
-
-.Building Block hierarchy
-[source]
-----
-GlossaryDocument (root)
-  └── DocParts (collection container)
-       └── DocPart (individual building block)
-            ├── DocPartProperties (metadata)
-            │    ├── DocPartName (display name)
-            │    ├── StyleId (associated paragraph style)
-            │    ├── DocPartCategory
-            │    │    ├── CategoryName (e.g., "General")
-            │    │    └── DocPartGallery (e.g., "hdrs", "ftrs", "coverPg")
-            │    ├── DocPartBehaviors (insertion behavior)
-            │    │    └── DocPartBehavior (e.g., "content", "page", "para")
-            │    ├── DocPartDescription (help text)
-            │    └── DocPartId (unique GUID)
-            └── DocPartBody (actual content)
-                 ├── Paragraphs (formatted text)
-                 ├── Tables (structured data)
-                 └── StructuredDocumentTags (fields)
-----
-
-==== Loading Building Blocks
-
-[source,ruby]
-----
-require 'uniword'
-
-# Load a .dotx template with building blocks
-doc = Uniword::Document.open('template.dotx')
-glossary = doc.glossary_document
-
-# Access building blocks
-glossary.doc_parts.doc_part.each do |part|
-  props = part.doc_part_pr
-  
-  puts "Name: #{props.name.val}"
-  puts "Gallery: #{props.category.gallery.val}"
-  puts "Category: #{props.category.name.val}"
-  puts "Description: #{props.description&.val}"
-  puts "Style: #{props.style&.val}"
-  puts "GUID: #{props.guid.val}"
-  
-  # Access content
-  part.doc_part_body.paragraphs.each do |para|
-    puts "  - #{para.text}"
-  end
-end
-----
-
-==== Creating Building Blocks
-
-[source,ruby]
-----
-require 'uniword'
-
-# Create new glossary document
-glossary = Uniword::Glossary::GlossaryDocument.new
-glossary.doc_parts = Uniword::Glossary::DocParts.new
-
-# Create a custom building block
-part = Uniword::Glossary::DocPart.new
-
-# Set properties
-part.doc_part_pr = Uniword::Glossary::DocPartProperties.new
-
-# Name (required)
-part.doc_part_pr.name = Uniword::Glossary::DocPartName.new(
-  val: 'Company Header'
-)
-
-# Style reference (optional)
-part.doc_part_pr.style = Uniword::Glossary::StyleId.new(
-  val: 'Heading 1'
-)
-
-# Unique identifier (required)
-part.doc_part_pr.guid = Uniword::Glossary::DocPartId.new(
-  val: '{12345678-1234-1234-1234-123456789012}'
-)
-
-# Category and gallery (required)
-part.doc_part_pr.category = Uniword::Glossary::DocPartCategory.new
-part.doc_part_pr.category.name = Uniword::Glossary::CategoryName.new(
-  val: 'General'
-)
-part.doc_part_pr.category.gallery = Uniword::Glossary::DocPartGallery.new(
-  val: 'hdrs'  # Headers gallery
-)
-
-# Behaviors (optional)
-part.doc_part_pr.behaviors = Uniword::Glossary::DocPartBehaviors.new
-behavior = Uniword::Glossary::DocPartBehavior.new(val: 'content')
-part.doc_part_pr.behaviors.behavior << behavior
-
-# Description (optional)
-part.doc_part_pr.description = Uniword::Glossary::DocPartDescription.new(
-  val: 'Standard company header with logo and contact info'
-)
-
-# Create content
-part.doc_part_body = Uniword::Glossary::DocPartBody.new
-
-# Add paragraphs
-para = Uniword::Paragraph.new
-para.add_text('Company Name')
-para.properties = Uniword::Properties::ParagraphProperties.new
-para.properties.alignment = Uniword::Properties::Alignment.new(value: 'center')
-part.doc_part_body.paragraphs << para
-
-# Add to glossary
-glossary.doc_parts.doc_part << part
-
-# Save to document
-doc = Uniword::Document.new
-doc.glossary_document = glossary
-doc.save('template.dotx')
-----
-
-==== Building Block Galleries
-
-Word organizes building blocks into galleries for easy access:
-
-* `hdrs` - Headers
-* `ftrs` - Footers
-* `coverPg` - Cover Pages
-* `eq` - Equations
-* `toc` - Tables of Contents
-* `bib` - Bibliographies
-* `watermarks` - Watermarks
-* `placeholder` - Custom placeholder blocks
-* `autoText` - AutoText entries
-* `textBox` - Text boxes
-
-==== Building Block Behaviors
-
-Control how building blocks are inserted into documents:
-
-* `content` - Insert as inline content at cursor
-* `page` - Insert as a new page
-* `para` - Insert as a new paragraph
-
-[source,ruby]
-----
-# Insert as new page (typical for cover pages)
-behavior = Uniword::Glossary::DocPartBehavior.new(val: 'page')
-
-# Insert as inline content (typical for headers/footers)
-behavior = Uniword::Glossary::DocPartBehavior.new(val: 'content')
-
-# Insert as new paragraph (typical for text blocks)
-behavior = Uniword::Glossary::DocPartBehavior.new(val: 'para')
-----
-
-==== Working with Complex Building Blocks
-
-Building blocks can contain tables, structured document tags (SDTs), and formatted text:
-
-[source,ruby]
-----
-part = Uniword::Glossary::DocPart.new
-part.doc_part_pr = Uniword::Glossary::DocPartProperties.new
-part.doc_part_pr.name = Uniword::Glossary::DocPartName.new(
-  val: 'Table of Contents'
-)
-part.doc_part_pr.category = Uniword::Glossary::DocPartCategory.new
-part.doc_part_pr.category.gallery = Uniword::Glossary::DocPartGallery.new(
-  val: 'toc'
-)
-
-part.doc_part_body = Uniword::Glossary::DocPartBody.new
-
-# Add structured document tag for TOC
-sdt = Uniword::StructuredDocumentTag.new
-sdt.properties = Uniword::SDTProperties.new
-# Configure SDT for table of contents...
-part.doc_part_body.elements << sdt
-
-# Add table
-table = Uniword::Table.new
-# Configure table...
-part.doc_part_body.elements << table
-
-# Add to glossary
-glossary.doc_parts.doc_part << part
-----
-
-==== Architecture
-
-Uniword's Glossary support follows a pure model-driven architecture using lutaml-model:
-
-* ✅ **Complete structure modeling** - All 19 Glossary elements implemented
-* ✅ **WordProcessingML integration** - Glossary uses `w:` namespace, not separate `g:` namespace
-* ✅ **Type safety** - Strongly typed properties with proper wrapper classes
-* ✅ **Pattern 0 compliance** - All attributes declared before xml mappings
-* ✅ **MECE architecture** - Clear separation between Glossary structure and content
-
-**Implementation status:**
-
-* GlossaryDocument structure: ✅ COMPLETE (Session 2, December 1, 2024)
-* Property serialization: ✅ COMPLETE (12/19 classes, 63%)
-* Content serialization: ✅ WORKING (paragraphs, tables, SDTs appear)
-* Ignorable attribute: ✅ ADDED (Session 3, December 1, 2024)
-
-**Key architectural decisions:**
-
-1. **Namespace choice**: Glossary elements use WordProcessingML namespace (`w:`), not separate Glossary namespace
-2. **Wrapper classes**: Properties like `style` and `guid` use dedicated wrapper classes (`StyleId`, `DocPartId`)
-3. **Content integration**: DocPartBody contains standard WordProcessingML elements (paragraphs, tables)
-4. **No raw XML**: Every element is a proper lutaml-model class
-
-==== Building Block Examples
-
-===== Example 1: Simple Header
-
-[source,ruby]
-----
-part = Uniword::Glossary::DocPart.new
-part.doc_part_pr = Uniword::Glossary::DocPartProperties.new
-
-part.doc_part_pr.name = Uniword::Glossary::DocPartName.new(
-  val: 'Simple Header'
-)
-part.doc_part_pr.category = Uniword::Glossary::DocPartCategory.new
-part.doc_part_pr.category.gallery = Uniword::Glossary::DocPartGallery.new(
-  val: 'hdrs'
-)
-part.doc_part_pr.guid = Uniword::Glossary::DocPartId.new(
-  val: SecureRandom.uuid
-)
-
-part.doc_part_body = Uniword::Glossary::DocPartBody.new
-para = Uniword::Paragraph.new
-para.add_text('Company Name', bold: true, size: 14)
-part.doc_part_body.paragraphs << para
-----
-
-===== Example 2: Cover Page with Table
-
-[source,ruby]
-----
-part = Uniword::Glossary::DocPart.new
-part.doc_part_pr = Uniword::Glossary::DocPartProperties.new
-
-part.doc_part_pr.name = Uniword::Glossary::DocPartName.new(
-  val: 'Professional Cover Page'
-)
-part.doc_part_pr.category = Uniword::Glossary::DocPartCategory.new
-part.doc_part_pr.category.gallery = Uniword::Glossary::DocPartGallery.new(
-  val: 'coverPg'
-)
-part.doc_part_pr.behaviors = Uniword::Glossary::DocPartBehaviors.new
-part.doc_part_pr.behaviors.behavior << Uniword::Glossary::DocPartBehavior.new(
-  val: 'page'
-)
-
-part.doc_part_body = Uniword::Glossary::DocPartBody.new
-
-# Add title
-title = Uniword::Paragraph.new
-title.add_text('Document Title', bold: true, size: 24)
-title.properties.alignment = Uniword::Properties::Alignment.new(value: 'center')
-part.doc_part_body.paragraphs << title
-
-# Add info table
-table = Uniword::Table.new
-# Configure table with author, date, etc...
-part.doc_part_body.elements << table
-----
-
-===== Example 3: Equation Building Block
-
-[source,ruby]
-----
-part = Uniword::Glossary::DocPart.new
-part.doc_part_pr = Uniword::Glossary::DocPartProperties.new
-
-part.doc_part_pr.name = Uniword::Glossary::DocPartName.new(
-  val: 'Quadratic Formula'
-)
-part.doc_part_pr.category = Uniword::Glossary::DocPartCategory.new
-part.doc_part_pr.category.gallery = Uniword::Glossary::DocPartGallery.new(
-  val: 'eq'
-)
-part.doc_part_pr.description = Uniword::Glossary::DocPartDescription.new(
-  val: 'Quadratic equation solution formula'
-)
-
-part.doc_part_body = Uniword::Glossary::DocPartBody.new
-para = Uniword::Paragraph.new
-# Add Office Math Markup Language (OMML) equation
-para.add_math('<math><mrow><mi>x</mi><mo>=</mo>...')
-part.doc_part_body.paragraphs << para
-----
-
-==== Implementation Status and Known Limitations
-
-✅ **Phase 3 Week 3 Session 3 COMPLETE (December 1, 2024)** - Glossary Infrastructure COMPLETE!
-
-**What works:**
-
-* ✅ Complete Glossary structure modeling (GlossaryDocument → DocParts → DocPart → DocPartProperties + DocPartBody)
-* ✅ All 12 core Glossary classes implemented and verified
-* ✅ Property serialization (name, style, guid, category, gallery, behaviors, description)
-* ✅ Content serialization (paragraphs, tables appear in docPartBody)
-* ✅ Ignorable attribute handling for forward compatibility
-* ✅ Perfect architectural compliance (Pattern 0, MECE, Model-driven)
-
-**Known limitations:**
-
-The 8 Glossary round-trip test failures are **NOT** due to Glossary structure issues. They are caused by incomplete **Wordprocessingml property implementations** that affect ALL document types:
-
-* Missing table properties (`tblPr` content: tblW, shd, tblCellMar, tblLook)
-* Missing cell properties (`tcPr` content: tcW, vAlign)
-* Missing paragraph rsid attributes (`rsidR`, `rsidRDefault`, `rsidP`)
-* Incomplete run properties (`rPr` content: caps, noProof, etc.)
-* Incomplete SDT properties (`sdtPr` content: id, alias, tag, showingPlcHdr, etc.)
-
-**These limitations are addressed in Phase 4 (Wordprocessingml Properties) and affect StyleSets, Themes, and regular documents as well, not just Glossary documents.**
-
-**Test results:**
-
-```
-Baseline: 342/342 passing (100%) ✅ (StyleSets + Themes)
-Content Types: 8/8 passing (100%) ✅
-Glossary Structure: WORKING ✅ (serializes correctly)
-Glossary Round-Trip: 0/8 (0%) - Wordprocessingml property gaps
-```
-=== Structured Document Tags (SDT)
-
-==== What are Structured Document Tags
-
-Structured Document Tags (SDTs) are Word's modern content control system that allows documents to contain interactive fields, data-bound content, and dynamic elements. SDTs are the foundation for features like:
-
-* **Text fields** - User input boxes
-* **Date pickers** - Calendar selection controls
-* **Drop-down lists** - Selection menus
-* **Bibliography** - Citation management
-* **Document part references** - Reusable content blocks
-* **Data-bound content** - XML-mapped fields
-
-==== SDT Properties Supported
-
-✅ **Phase 4 COMPLETE (December 2, 2024)** - ALL 13 SDT PROPERTIES IMPLEMENTED! 🎉
-
-Uniw provides complete support for all discovered SDT property types:
-
-**Identity & Display (7 properties)**:
-
-* `id` - Unique integer identifier for the SDT
-* `alias` - User-friendly Display name
-* `tag` - Developer-assigned tag (can be empty string)
-* `text` - Text control flag (empty element)
-* `showingPlcHdr` - Show placeholder when content is empty
-* `appearance` - Visual style: `hidden`, `tags`, or `boundingBox`
-* `temporary` - Remove SDT wrapper when content is first edited
-
-**Data & References (3 properties)**:
-
-* `dataBinding` - XML data binding with xpath, storeItemID, and prefixMappings
-* `placeholder` - Reference to placeholder docPart content
-* `docPartObj` - Document part gallery reference (gallery, category, unique flag)
-
-**Special Controls (3 properties)**:
-
-* `date` - Date picker with format, language, calendar, and fullDate attribute
-* `bibliography` - Bibliography content control flag
-* `rPr` - Run properties for SDT content formatting
-
-==== Loading Documents with SDTs
-
-[source,ruby]
-----
-require 'uniword'
-
-# Load document with SDTs
-doc = Uniword::Document.open('template.dotx')
-
-# Access SDT properties from glossary document
-doc.glossary_document&.doc_parts&.each do |part|
-  part.doc_part_body.sdts.each do |sdt|
-    props = sdt.properties
-    
-    # Identity properties
-    puts "SDT ID: #{props.id&.value}"
-    puts "Alias: #{props.alias_name&.value}"
-    puts "Tag: #{props.tag&.value}"
-    
-    # Display properties
-    puts "Text Control: #{!props.text.nil?}"
-    puts "Show Placeholder: #{!props.showing_placeholder_header.nil?}"
-    puts "Appearance: #{props.appearance&.value}"
-    puts "Temporary: #{!props.temporary.nil?}"
-    
-    # Data binding
-    if props.data_binding
-      puts "XPath: #{props.data_binding.xpath}"
-      puts "Store Item ID: #{props.data_binding.store_item_id}"
-    end
-    
-    # Date control
-    if props.date
-      puts "Date Format: #{props.date.date_format&.value}"
-      puts "Full Date: #{props.date.full_date}"
-      puts "Calendar: #{props.date.calendar&.value}"
-      puts "Language: #{props.date.lid&.value}"
-    end
-    
-    # Document part reference
-    if props.doc_part_obj
-      puts "Gallery: #{props.doc_part_obj.doc_part_gallery&.value}"
-      puts "Category: #{props.doc_part_obj.doc_part_category&.value}"
-      puts "Unique: #{!props.doc_part_obj.doc_part_unique.nil?}"
-    end
-    
-    # Special controls
-    puts "Bibliography: #{!props.bibliography.nil?}"
-  end
-end
-----
-
-==== Creating SDTs
-
-[source,ruby]
-----
-require 'uniword'
-
-# Create a new structured document tag
-sdt = Uniword::Wordprocessingml::StructuredDocumentTag.new
-
-# Create SDT properties
-sdt.properties = Uniword::StructuredDocumentTagProperties.new
-
-# Set identity
-sdt.properties.id = Uniword::Sdt::Id.new(value: 123456)
-sdt.properties.alias_name = Uniword::Sdt::Alias.new(value: "User Name Field")
-sdt.properties.tag = Uniword::Sdt::Tag.new(value: "user_name")
-
-# Mark as text control
-sdt.properties.text = Uniword::Sdt::Text.new
-
-# Show placeholder when empty
-sdt.properties.showing_placeholder_header = Uniword::Sdt::ShowingPlaceholderHeader.new
-
-# Set appearance
-sdt.properties.appearance = Uniword::Sdt::Appearance.new(value: "boundingBox")
-
-# Add placeholder reference
-sdt.properties.placeholder = Uniword::Sdt::Placeholder.new
-sdt.properties.placeholder.doc_part_reference = Uniword::Sdt::DocPartReference.new(
-  value: "{12345678-1234-1234-1234-123456789012}"
-)
-
-# Create SDT content
-sdt.content = Uniword::Wordprocessingml::SdtContent.new
-
-# Add paragraph to content
-para = Uniword::Paragraph.new
-para.add_text("Enter your name here")
-sdt.content.paragraphs << para
-
-# Add to document's glossary
-doc.glossary_document.doc_parts.doc_part.first.doc_part_body.sdts << sdt
-----
-
-==== Date Picker SDTs
-
-[source,ruby]
-----
-# Create date picker control
-sdt = Uniword::Wordprocessingml::StructuredDocumentTag.new
-sdt.properties = Uniword::StructuredDocumentTagProperties.new
-
-# Basic identity
-sdt.properties.id = Uniword::Sdt::Id.new(value: 789012)
-sdt.properties.alias_name = Uniword::Sdt::Alias.new(value: "Document Date")
-
-# Configure date control
-sdt.properties.date = Uniword::Sdt::Date.new
-
-# Set date format
-sdt.properties.date.date_format = Uniword::Sdt::DateFormat.new(value: "M/d/yyyy")
-
-# Set language
-sdt.properties.date.lid = Uniword::Sdt::Lid.new(value: "en-US")
-
-# Set calendar type
-sdt.properties.date.calendar = Uniword::Sdt::Calendar.new(value: "gregorian")
-
-# Set storage format
-sdt.properties.date.store_mapped_data_as = Uniword::Sdt::StoreMappedDataAs.new(
-  value: "dateTime"
-)
-
-# Optional: Set current date
-sdt.properties.date.full_date = "2024-12-02T00:00:00Z"
-
-# Add content paragraph
-sdt.content = Uniword::Wordprocessingml::SdtContent.new
-para = Uniword::Paragraph.new
-para.add_text("12/2/2024")
-sdt.content.paragraphs << para
-----
-
-==== Data-Bound SDTs
-
-[source,ruby]
-----
-# Create data-bound SDT
-sdt = Uniword::Wordprocessingml::StructuredDocumentTag.new
-sdt.properties = Uniword::StructuredDocumentTagProperties.new
-
-# Basic identity
-sdt.properties.id = Uniword::Sdt::Id.new(value: 345678)
-sdt.properties.alias_name = Uniword::Sdt::Alias.new(value: "Customer Name")
-sdt.properties.tag = Uniword::Sdt::Tag.new(value: "customer_name")
-
-# Configure data binding
-sdt.properties.data_binding = Uniword::Sdt::DataBinding.new
-
-# XPath to XML data
-sdt.properties.data_binding.xpath = "/root/customer/name"
-
-# Custom XML part ID
-sdt.properties.data_binding.store_item_id = "{ABCDEFGH-1234-5678-90AB-CDEF12345678}"
-
-# Namespace prefix mappings (optional)
-sdt.properties.data_binding.prefix_mappings = 'xmlns:ns="http://example.com/schema"'
-
-# Text control
-sdt.properties.text = Uniword::Sdt::Text.new
-
-# Add content
-sdt.content = Uniword::Wordprocessingml::SdtContent.new
-para = Uniword::Paragraph.new
-para.add_text("John Doe")
-sdt.content.paragraphs << para
-----
-
-==== Bibliography SDTs
-
-[source,ruby]
-----
-# Create bibliography control
-sdt = Uniword::Wordprocessingml::StructuredDocumentTag.new
-sdt.properties = Uniword::StructuredDocumentTagProperties.new
-
-# Identity
-sdt.properties.id = Uniword::Sdt::Id.new(value: 234567)
-sdt.properties.alias_name = Uniword::Sdt::Alias.new(value: "Bibliography")
-
-# Mark as bibliography control
-sdt.properties.bibliography = Uniword::Sdt::Bibliography.new
-
-# Add bibliography content
-sdt.content = Uniword::Wordprocessingml::SdtContent.new
-# Bibliography content typically contains citation paragraphs
-----
-
-==== Document Part Reference SDTs
-
-[source,ruby]
-----
-# Create SDT that references a document part
-sdt = Uniword::Wordprocessingml::StructuredDocumentTag.new
-sdt.properties = Uniword::StructuredDocumentTagProperties.new
-
-# Identity
-sdt.properties.id = Uniword::Sdt::Id.new(value: 456789)
-sdt.properties.alias_name = Uniword::Sdt::Alias.new(value: "Cover Page")
-
-# Reference document part gallery
-sdt.properties.doc_part_obj = Uniword::Sdt::DocPartObj.new
-
-# Specify gallery (where user selects from)
-sdt.properties.doc_part_obj.doc_part_gallery = Uniword::Sdt::DocPartGallery.new(
-  value: "Cover Pages"
-)
-
-# Specify category (optional)
-sdt.properties.doc_part_obj.doc_part_category = Uniword::Sdt::DocPartCategory.new(
-  value: "General"
-)
-
-# Mark as unique (only one instance allowed)
-sdt.properties.doc_part_obj.doc_part_unique = Uniword::Sdt::DocPartUnique.new
-----
-
-==== Implementation Status
-
-✅ **Phase 4 Complete (December 2, 2024)** - ALL SDT PROPERTIES IMPLEMENTED
-
-**Test Results**:
-
-```
-Property Coverage:  27/27 (100%) ✅
-SDT Properties:     13/13 (100%) ✅
-Baseline Tests:     342/342 (100%) ✅
-Pattern 0:          27/27 (100%) ✅
-Architecture:       MECE, Model-driven, Zero raw XML ✅
-```
-
-**Property Categories Implemented**:
-
-[cols="2,1,4"]
-|===
-| Category | Count | Properties
-
-| Table Properties
-| 5/5
-| width, shading, margins, borders, look
-
-| Cell Properties
-| 3/3
-| width, vertical alignment, margins
-
-| Paragraph Properties
-| 4/4
-| alignment, spacing, indentation, rsid
-
-| Run Properties
-| 4/4
-| fonts, color, size, noProof, themeColor
-
-| *SDT Properties*
-| *13/13*
-| *id, alias, tag, text, showingPlcHdr, appearance, temporary, placeholder, dataBinding, bibliography, docPartObj, date, rPr*
-
-| **Total**
-| **27/27**
-| **100% of discovered properties**
-|===
-
-**Architecture Quality**:
-
-* ✅ 100% Pattern 0 compliance (attributes before xml mappings)
-* ✅ MECE design (clear separation of concerns)
-* ✅ Model-driven (zero raw XML storage)
-* ✅ Extensible (open/closed principle maintained)
-* ✅ Zero regressions (342/342 baseline tests maintained)
-
-**Implementation Time**: 6 sessions, 5.5 hours total (37% faster than estimated)
-
-
-=== Tables
-
-==== Basic table creation
-
-[source,ruby]
-----
-table = Uniword::Table.new
-row = Uniword::TableRow.new
-
-cell1 = Uniword::TableCell.new
-cell1.add_paragraph("Cell 1")
-row.add_cell(cell1)
-
-cell2 = Uniword::TableCell.new
-cell2.add_paragraph("Cell 2")
-row.add_cell(cell2)
-
-table.add_row(row)
-doc.add_element(table)
-----
-
-==== Table with borders
-
-[source,ruby]
-----
-table = Uniword::Table.new
-
-# Set table borders
-table.properties = Uniword::Properties::TableProperties.new
-table.properties.borders = {
-  top: Uniword::TableBorder.new(style: 'single', size: 4, color: '000000'),
-  bottom: Uniword::TableBorder.new(style: 'single', size: 4, color: '000000'),
-  left: Uniword::TableBorder.new(style: 'single', size: 4, color: '000000'),
-  right: Uniword::TableBorder.new(style: 'single', size: 4, color: '000000'),
-  insideH: Uniword::TableBorder.new(style: 'single', size: 4, color: '000000'),
-  insideV: Uniword::TableBorder.new(style: 'single', size: 4, color: '000000')
-}
-
-# Add rows and cells
-row = Uniword::TableRow.new
-row.add_cell(Uniword::TableCell.new.tap { |c| c.add_paragraph("A1") })
-row.add_cell(Uniword::TableCell.new.tap { |c| c.add_paragraph("B1") })
-table.add_row(row)
-----
-
-==== Using Builder for tables
-
-[source,ruby]
-----
-doc = Uniword::Builder.new
-  .add_table do
-    row do
-      cell 'Header 1', bold: true
-      cell 'Header 2', bold: true
-    end
-    row do
-      cell 'Data 1'
-      cell 'Data 2'
-    end
-  end
-  .build
-----
-
-=== Lists
-
-==== Numbered lists
-
-[source,ruby]
-----
-# Create numbered list
-3.times do |i|
-  para = Uniword::Paragraph.new
-  para.set_numbering(1, 0)  # numbering_id=1, level=0
-  para.add_text("Item #{i+1}")
-  doc.add_element(para)
-end
-----
-
-==== Bulleted lists
-
-[source,ruby]
-----
-# Create bulleted list
-['Apple', 'Banana', 'Cherry'].each do |item|
-  para = Uniword::Paragraph.new
-  para.set_numbering(2, 0)  # numbering_id=2 for bullets
-  para.add_text(item)
-  doc.add_element(para)
-end
-----
-
-==== Multi-level lists
-
-[source,ruby]
-----
-# Level 0 item
-para1 = Uniword::Paragraph.new
-para1.set_numbering(1, 0)
-para1.add_text("Level 0 item")
-doc.add_element(para1)
-
-# Level 1 item (indented)
-para2 = Uniword::Paragraph.new
-para2.set_numbering(1, 1)
-para2.add_text("Level 1 item")
-doc.add_element(para2)
-
-# Level 2 item (more indented)
-para3 = Uniword::Paragraph.new
-para3.set_numbering(1, 2)
-para3.add_text("Level 2 item")
-doc.add_element(para3)
-----
-
-=== Images
-
-==== Adding images
-
-[source,ruby]
-----
-# Add image from file
-image = Uniword::Image.new(
-  path: 'path/to/image.png',
-  width: 300,
-  height: 200
-)
-doc.add_element(image)
-----
-
-==== Image positioning
-
-[source,ruby]
-----
-# Add positioned image
-image = Uniword::Image.new(
-  path: 'logo.png',
-  width: 100,
-  height: 100,
-  position: {
-    horizontal: 'center',
-    vertical: 'top'
-  }
-)
-----
-
-=== Headers and footers
-
-==== Adding headers
-
-[source,ruby]
-----
-section = doc.current_section
-header = Uniword::Header.new(type: 'default')
-
-para = Uniword::Paragraph.new
-para.add_text("Page Header", bold: true)
-para.align('center')
-header.add_element(para)
-
-section.default_header = header
-----
-
-==== Adding footers
-
-[source,ruby]
-----
-footer = Uniword::Footer.new(type: 'default')
-
-para = Uniword::Paragraph.new
-para.add_text("Page ")
-# Add page number field
-para.add_text("1", field_type: 'page_number')
-para.align('center')
-footer.add_element(para)
-
-section.default_footer = footer
-----
-
-==== Different headers for first page
-
-[source,ruby]
-----
-# First page header
-first_header = Uniword::Header.new(type: 'first')
-para = Uniword::Paragraph.new
-para.add_text("First Page Header")
-first_header.add_element(para)
-section.first_header = first_header
-
-# Default header for other pages
-default_header = Uniword::Header.new(type: 'default')
-para = Uniword::Paragraph.new
-para.add_text("Default Header")
-default_header.add_element(para)
-section.default_header = default_header
-----
-
-=== Text boxes
-
-==== Creating text boxes
-
-[source,ruby]
-----
-text_box = Uniword::TextBox.new(
-  width: 200,
-  height: 100,
-  position: { x: 100, y: 100 }
-)
-
-para = Uniword::Paragraph.new
-para.add_text("Text inside box")
-text_box.add_element(para)
-
-doc.add_element(text_box)
-----
-
-=== Footnotes and endnotes
-
-==== Adding footnotes
-
-[source,ruby]
-----
-# Add text with footnote reference
-para = Uniword::Paragraph.new
-para.add_text("This text has a footnote")
-para.add_text("1", footnote_ref: true)
-
-# Create footnote
-footnote = Uniword::Footnote.new(id: 1)
-footnote_para = Uniword::Paragraph.new
-footnote_para.add_text("This is the footnote text")
-footnote.add_element(footnote_para)
-
-doc.footnotes << footnote
-doc.add_element(para)
-----
-
-==== Adding endnotes
-
-[source,ruby]
-----
-# Add text with endnote reference
-para = Uniword::Paragraph.new
-para.add_text("This text has an endnote")
-para.add_text("i", endnote_ref: true)
-
-# Create endnote
-endnote = Uniword::Endnote.new(id: 1)
-endnote_para = Uniword::Paragraph.new
-endnote_para.add_text("This is the endnote text")
-endnote.add_element(endnote_para)
-
-doc.endnotes << endnote
-doc.add_element(para)
-----
-
-=== Bookmarks and cross-references
-
-==== Creating bookmarks
-
-[source,ruby]
-----
-# Create bookmark
-bookmark = Uniword::Bookmark.new(
-  id: 1,
-  name: 'Section1'
-)
-
-para = Uniword::Paragraph.new
-para.add_text("Bookmarked section")
-para.add_bookmark_start(bookmark)
-para.add_bookmark_end(bookmark.id)
-
-doc.bookmarks << bookmark
-doc.add_element(para)
-----
-
-==== Adding cross-references
-
-[source,ruby]
-----
-# Reference to bookmark
-para = Uniword::Paragraph.new
-para.add_text("See ")
-para.add_text("Section 1", hyperlink: '#Section1')
-doc.add_element(para)
-----
-
-=== Math formulas
-
-==== MathML formulas
-
-[source,ruby]
-----
-# Add MathML formula
-para = Uniword::Paragraph.new
-para.add_math('<math><mrow><mi>x</mi><mo>=</mo><mfrac><mrow><mo>-</mo><mi>b</mi></mrow><mrow><mn>2</mn><mi>a</mi></mrow></mfrac></mrow></math>')
-doc.add_element(para)
-----
-
-==== AsciiMath formulas
-
-[source,ruby]
-----
-# Add AsciiMath formula (converted to MathML)
-para = Uniword::Paragraph.new
-para.add_math('x = (-b)/(2a)', format: :asciimath)
-doc.add_element(para)
-----
-
-== Format conversion
+== Installation
 
-=== DOCX to MHTML
+Add to your Gemfile:
 
 [source,ruby]
 ----
-# Read DOCX
-doc = Uniword::DocumentFactory.from_file('input.docx')
-
-# Save as MHTML
-doc.save('output.doc')
+gem 'uniword'
 ----
 
-=== MHTML to DOCX
+Or install directly:
 
-[source,ruby]
+[source,shell]
 ----
-# Read MHTML
-doc = Uniword::DocumentFactory.from_file('input.doc')
-
-# Save as DOCX
-doc.save('output.docx')
+gem install uniword
 ----
 
-=== Auto-detect format
+== Quick Start
 
 [source,ruby]
 ----
-# Format is auto-detected from file extension
-doc = Uniword::DocumentFactory.from_file('document.docx')
-doc.save('output.mht')  # Auto-converts to MHTML
-----
-
-== Builder pattern
-
-The Builder pattern provides a fluent, declarative way to create documents:
+require 'uniword'
 
-[source,ruby]
-----
+# Create a document
 doc = Uniword::Builder.new
   .add_heading('My Document', level: 1)
-  .add_paragraph('Introduction paragraph')
-  .add_blank_line
-  .add_heading('Section 1', level: 2)
-  .add_paragraph('Section content', bold: true)
-  .add_table do
-    row do
-      cell 'Header 1', bold: true
-      cell 'Header 2', bold: true
-    end
-    row do
-      cell 'Data 1'
-      cell 'Data 2'
-    end
-  end
-  .add_paragraph('Conclusion')
+  .add_paragraph('Hello World', bold: true)
   .build
-
 doc.save('output.docx')
-----
-
-== CLI usage
-
-=== Convert between formats
-
-[source,shell]
-----
-# Convert DOCX to MHTML
-uniword convert input.docx output.doc
-
-# Convert MHTML to DOCX
-uniword convert input.doc output.docx --verbose
-
-# Specify formats explicitly
-uniword convert input.mht output.docx --from mhtml --to docx
-----
-
-=== Document information
-
-[source,shell]
-----
-# Show basic information
-uniword info document.docx
-
-# Show detailed information
-uniword info document.docx --verbose
-----
-
-=== Validate document
-
-[source,shell]
-----
-# Validate document structure
-uniword validate document.docx
-
-# Show detailed validation results
-uniword validate document.docx --verbose
-----
-
-=== Export Word resources
-
-Export raw Word resources (themes, stylesets, document elements) from your local Microsoft Word installation:
-
-[source,shell]
-----
-# Export all resources to a directory
-uniword resources export output-dir --word-app "/Applications/Microsoft Word.app"
-
-# Export with verbose output
-uniword resources export ~/my-word-resources --word-app "/Applications/Microsoft Word.app" --verbose
-----
-
-The command exports:
-
-* `office-themes/` - Theme files (.thmx) from Word's Office Themes folder
-* `quick-styles/` - StyleSet files (.dotx) from Word's QuickStyles folder
-* `document-elements/` - Document element templates (.dotx) from all language .lproj folders
-* `citation-styles/` - Citation style files (.xsl) from Word's Style folder
-* `theme-colors/` - Theme color scheme files (.xml) from Word's Theme Colors folder
-* `theme-fonts/` - Theme font scheme files (.xml) from Word's Theme Fonts folder
-
-These resources can be used for testing, building bundled StyleSets/Themes, or customizing document templates.
-
-[NOTE]
-====
-The `--word-app` option is required and must point to your Microsoft Word.app location.
-On macOS, this is typically `/Applications/Microsoft Word.app`.
-====
-
-=== Show version
-
-[source,shell]
-----
-uniword version
-----
-
-== API reference
-
-Full API documentation is available at https://www.rubydoc.info/gems/uniword[RubyDoc.info].
-
-Key classes:
-
-* `Uniword::Document` - Main document class
-* `Uniword::DocumentFactory` - Factory for reading documents
-* `Uniword::DocumentWriter` - Writer for saving documents
-* `Uniword::Builder` - Fluent document builder
-* `Uniword::Paragraph` - Paragraph element
-* `Uniword::Run` - Text run with formatting
-* `Uniword::Table` - Table element
-* `Uniword::Image` - Image element
-* `Uniword::CLI` - Command-line interface
-
-== Error handling
-
-Uniword provides comprehensive error handling:
 
-[source,ruby]
-----
-require 'uniword'
-
-begin
-  doc = Uniword::DocumentFactory.from_file('document.docx')
-rescue Uniword::FileNotFoundError => e
-  puts "File not found: #{e.path}"
-rescue Uniword::CorruptedFileError => e
-  puts "Corrupted file: #{e.reason}"
-rescue Uniword::InvalidFormatError => e
-  puts "Invalid format: #{e.message}"
-rescue Uniword::Error => e
-  puts "Error: #{e.message}"
+# Read and modify
+doc = Uniword::DocumentFactory.from_file('input.docx')
+puts doc.text
+doc.save('modified.docx')
+
+# Apply theme and styleset
+doc = Uniword::Wordprocessingml::DocumentRoot.new
+doc.apply_theme('meridian')
+doc.apply_styleset('signature')
+doc.save('styled.docx')
+
+# Compare two documents (content-level)
+old_doc = Uniword.load("v1.docx")
+new_doc = Uniword.load("v2.docx")
+result = old_doc.diff(new_doc)
+puts result.summary
+
+# Compare two DOCX packages (structural, with Canon semantic diff)
+differ = Uniword::Diff::PackageDiffer.new("old.docx", "new.docx", canon: true)
+pkg_result = differ.diff
+pkg_result.modified_parts.each do |part|
+  status = part.canon_equivalent ? "equivalent" : "DIFFERENT"
+  puts "#{part.name}: canon #{status}"
 end
 ----
 
-Available exceptions:
-
-* `Uniword::FileNotFoundError` - File does not exist
-* `Uniword::CorruptedFileError` - File is corrupted or invalid
-* `Uniword::InvalidFormatError` - Unsupported format
-* `Uniword::ValidationError` - Document validation failed
-* `Uniword::ConversionError` - Format conversion failed
-
-== Examples
-
-Complete examples are available in the link:examples/[`examples/`] directory:
-
-* link:examples/basic_usage.rb[`basic_usage.rb`] - Basic document creation
-* link:examples/styles_example.rb[`styles_example.rb`] - Text formatting and styles
-* link:examples/advanced_example.rb[`advanced_example.rb`] - Complex document
-* link:examples/conversion_example.rb[`conversion_example.rb`] - Format conversion
-
-Run any example:
+== CLI
 
 [source,shell]
 ----
-ruby examples/basic_usage.rb
+uniword convert input.docx output.doc        # DOCX to MHTML
+uniword info document.docx                   # Document info
+uniword validate document.docx               # Schema validation
+uniword verify document.docx                 # Full 3-layer verification
+uniword diff compare old.docx new.docx       # Document-level diff (content, styles)
+uniword diff package old.docx new.docx --canon  # Package-level diff (ZIP, XML, OPC)
+uniword theme apply doc.docx out.docx -n meridian  # Apply theme
+uniword theme auto ms.docx uniword.docx      # Auto MS->Uniword transition
 ----
 
-== Performance
-
-Uniword is optimized for performance with large documents:
-
-* Lazy loading for memory efficiency
-* Streaming parsers for large files
-* Efficient XML serialization with lutaml-model
-* Optimized ZIP handling
+== Features
 
-See link:PERFORMANCE.md[PERFORMANCE.md] for benchmarks and optimization details.
+* Full DOCX and MHTML read/write with format conversion
+* 29 bundled themes, 12 stylesets, 23 color schemes, 25 font schemes
+* 30-locale document elements (240 templates)
+* MS font to open-source substitution (Calibri->Carlito, Arial->Liberation Sans)
+* Auto theme transition: detect MS themes by color fingerprint
+* DOCX diffing: document-level (content/formatting) and package-level (ZIP/XML/OPC with Canon semantic comparison)
+* DOCX validation: 3-layer pipeline (OPC + XSD + semantic rules)
+* Prevention layer: auto-fix footnote/endnote cross-part invariants
+* Tables, lists, images, headers/footers, footnotes, bookmarks, math
+* Fluent Builder API and CLI interface
+
+== Documentation
+
+Full documentation is at https://metanorma.github.io/uniword[metanorma.github.io/uniword].
+
+* link:docs/_getting-started/[Getting Started] -- Installation and first document
+* link:docs/_interfaces/[Interfaces] -- Ruby API and CLI reference
+* link:docs/_guides/[Guides] -- Step-by-step guides for every feature
+* link:docs/_understanding/[Understanding] -- Architecture and design
+* link:docs/_features/[Features] -- Theme and styleset catalogs
+* link:docs/_verification/[Verification] -- DOCX validation and verification
+* link:docs/_development/[Development] -- Contributing and code patterns
 
 == Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/metanorma/uniword.
-
-Please see link:CONTRIBUTING.md[CONTRIBUTING.md] for development guidelines.
+See link:CONTRIBUTING.md[CONTRIBUTING.md] for development guidelines.
+Bug reports and pull requests are welcome at https://github.com/metanorma/uniword.
 
 == License
 
 The gem is available as open source under the terms of the https://opensource.org/licenses/BSD-2-Clause[BSD 2-Clause License].
 
-== Copyright
-
-Copyright (c) 2024 Ribose Inc.
+Copyright (c) 2024 Ribose Inc.