feat: Refactor and polish xml-lib for production readiness

This comprehensive refactoring makes xml-lib feel like a complete, polished
Python library with significantly improved robustness, testability, and
developer experience.

## Public API Improvements

- **Define clear public API**: Added explicit `__all__` exports to xml_lib/__init__.py
- **Comprehensive API documentation**: Created docs/api.md with detailed function
  signatures, parameters, return types, examples, and usage patterns
- **Unified type definitions**: Made validator.ValidationResult the canonical type,
  improved ValidationError documentation, removed duplication

## Testing Enhancements

- **API tests**: New tests/test_api.py with comprehensive coverage of public API
  functions (quick_validate, validate_xml, create_validator, lint_xml, publish_html)
- **CLI integration tests**: New tests/test_cli_integration.py using CliRunner to
  test validate, publish, lint, diff, roundtrip, render-pptx, and phpify commands
- **Streaming equivalence tests**: New tests/test_streaming_equivalence.py ensuring
  streaming and non-streaming modes produce identical ValidationResult
- **Property-based tests**: Expanded Hypothesis tests for cross-file ID uniqueness,
  temporal/phase ordering invariants, schema validation, and guardrail policies
- **Type stability tests**: Added tests ensuring public API types remain stable

## Testing Infrastructure

- **Pytest markers**: Added 'property' marker to pytest.ini (aligned with README_NEW.md)
- **Test markers**: Applied pytest.mark.property and pytest.mark.integration markers
  to appropriate test modules for better test organization
- **Mutation testing**: Added .mutmut_config.py for mutation testing of core modules
  (validator.py, sanitize.py, linter.py, publisher.py, schema.py)

## Exception Hierarchy

- **Coherent exceptions**: New xml_lib/exceptions.py with XMLLibError base class
- **Specific exception types**: XMLConfigurationError, XMLFileNotFoundError,
  XMLParseError, XMLValidationError, XMLPublishingError, XMLTelemetryError
- **Clear error handling**: Exceptions for "cannot start" conditions, result
  objects (ValidationResult, LintResult) for per-file issues
- **Exported exceptions**: Added exceptions to xml_lib.__all__ for public use

## Documentation & Developer Experience

- **CONTRIBUTING.md**: Comprehensive contributor guide with development setup,
  quality gates, testing guidelines, code style, and PR process
- **Issue templates**: GitHub issue templates (bug_report.yml, feature_request.yml)
  with structured fields for better issue reporting
- **API stability**: Documentation and tests ensuring types remain stable across versions

## Code Quality

- **Enhanced docstrings**: Improved documentation for ValidationResult, ValidationError
- **Type annotations**: Maintained strict typing discipline throughout
- **Import organization**: Clean exports and re-exports for better API surface

This refactoring addresses all requested improvements while maintaining backward
compatibility and existing code style. The library now feels stable, predictable,
and ready for production use.

Resolves: #[issue-number-if-any]

Author: claude

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,76 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the information below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of the bug
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Run command '...'
+        2. With input file '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+      placeholder: Expected output or behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened?
+      placeholder: Actual output or error message
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Please provide information about your environment
+      value: |
+        - OS: [e.g., Ubuntu 22.04, macOS 13, Windows 11]
+        - Python version: [e.g., 3.11.5]
+        - xml-lib version: [e.g., 0.1.0]
+        - Installation method: [e.g., pip, poetry]
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs
+      description: Please paste any relevant log output
+      render: shell
+      placeholder: Paste logs here
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem
+      placeholder: Screenshots, sample files, etc.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question or Discussion
+    url: https://github.com/farukalpay/xml-lib/discussions
+    about: Ask questions or discuss ideas with the community
+  - name: Documentation
+    url: https://github.com/farukalpay/xml-lib/blob/main/README.md
+    about: Read the documentation

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,75 @@
+name: Feature Request
+description: Suggest a new feature or enhancement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please provide details below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: Is your feature request related to a problem? Please describe.
+      placeholder: I'm frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like
+      placeholder: I would like xml-lib to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Describe any alternative solutions or features you've considered
+      placeholder: Alternative approaches...
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: Describe your use case for this feature
+      placeholder: |
+        I need this feature because...
+        Example workflow:
+        1. ...
+        2. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Example Usage
+      description: Show how you would use this feature
+      render: python
+      placeholder: |
+        from xml_lib import new_feature
+
+        result = new_feature(...)
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Would you like to contribute this feature?
+      description: Are you willing to submit a PR for this feature?
+      options:
+        - label: Yes, I'm willing to contribute this feature
+        - label: I need help implementing this
+        - label: I'm suggesting this for someone else to implement
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Add any other context, screenshots, or examples
+      placeholder: Links to similar features in other libraries, etc.

.mutmut_config.py

@@ -0,0 +1,65 @@
+"""Configuration for mutmut mutation testing.
+
+Run mutation tests with:
+    mutmut run --paths-to-mutate=xml_lib/
+
+View results with:
+    mutmut results
+    mutmut html
+
+Apply a specific mutation to see what changed:
+    mutmut apply <id>
+"""
+
+
+def pre_mutation(context):
+    """Filter which files and lines to mutate.
+
+    Args:
+        context: Mutation context with line, filename, etc.
+
+    Returns:
+        True to allow mutation, False to skip
+    """
+    # Skip test files
+    if "test_" in context.filename or "/tests/" in context.filename:
+        return False
+
+    # Skip __init__.py files (mostly imports)
+    if context.filename.endswith("__init__.py"):
+        return False
+
+    # Skip CLI files (hard to mutation test CLIs effectively)
+    if "cli.py" in context.filename or "cli_new.py" in context.filename:
+        return False
+
+    # Skip generated or vendored code
+    if "/vendor/" in context.filename or "/generated/" in context.filename:
+        return False
+
+    # Allow mutation for core modules
+    return True
+
+
+# Paths to mutate (can also specify on command line)
+paths_to_mutate = [
+    "xml_lib/validator.py",
+    "xml_lib/sanitize.py",
+    "xml_lib/linter.py",
+    "xml_lib/publisher.py",
+    "xml_lib/schema.py",
+    "xml_lib/lifecycle.py",
+    "xml_lib/guardrails.py",
+]
+
+# Test command (pytest)
+runner = "pytest -x --tb=short -q"
+
+# Directories to exclude
+exclude_patterns = [
+    "tests/",
+    "docs/",
+    ".venv/",
+    "build/",
+    "dist/",
+]