# PyFulmen v0.1.3 Release Notes

**Release Date**: October 20, 2025
**Release Type**: Feature Release - Extension Modules & Documentation Polish
**Milestone**: Pathfinder & ASCII Helpers Complete, All Core Modules Stable

---

## 🎯 Release Overview

PyFulmen v0.1.3 adds two production-ready **extension modules** for filesystem discovery and console formatting, completing the foundation library's essential utilities. This release also establishes **comprehensive ecosystem ADR tracking** to document architectural alignment across the Fulmen ecosystem.

**Key Capabilities**:

- **Pathfinder**: Safe filesystem discovery with glob patterns, path traversal protection, and proper pathlib usage
- **ASCII Helpers**: Unicode-aware box drawing with terminal-specific width overrides and three-layer configuration
- **Config Three-Layer System**: Enhanced ConfigLoader with metadata tracking and vendor/app namespace support
- **Schema Catalog & Validation**: Schema discovery with goneat integration and comprehensive validation CLI
- **Ecosystem ADR Tracking**: Comprehensive adoption status tracking for cross-language architectural decisions
- **Documentation Polish**: Updated module statuses, test counts, and roadmap alignment
- **Enterprise Quality**: 613 tests passing, 90%+ coverage across all modules

This release prioritizes:

- **Developer Experience**: Idiomatic Python filesystem operations with modern pathlib APIs
- **Cross-Language Parity**: 100% behavioral alignment with gofulmen pathfinder and ASCII implementations
- **Architectural Transparency**: Complete tracking of ecosystem ADR adoption status
- **Production Readiness**: All core modules now stable, extension modules tested and documented

---

## ✨ Major Features

### Pathfinder Extension Module

Safe filesystem discovery with glob patterns, designed to avoid the brittleness found in raw doublestar/glob usage.

#### Core Features

**Location**: `src/pyfulmen/pathfinder/`

- **Path Safety Validation**: Traversal attack prevention with proper normalization
- **Glob Pattern Support**: Recursive `**` patterns with proper pathlib integration
- **Flexible Discovery**: Include/exclude patterns, max depth, hidden file handling
- **Streaming Support**: Progress callbacks and error handlers
- **Schema Validation**: Optional input/output validation against Crucible schemas

#### Path Safety

**Location**: `src/pyfulmen/pathfinder/safety.py`

```python
def validate_path(path: str) -> None:
    """
    Validate path safety with traversal attack prevention.

    Checks:
    - Path traversal attempts (.. sequences)
    - Empty/invalid paths
    - Proper normalization using os.path

    Raises:
    - PathTraversalError: Path contains traversal attempts
    - InvalidPathError: Path is empty or invalid
    """
```

**Key Design Decision**: Check for `..` in the ORIGINAL path BEFORE normalization, since `os.path.normpath` resolves `..` and would hide traversal attempts.

#### Finder API

**Location**: `src/pyfulmen/pathfinder/finder.py`

```python
from pyfulmen.pathfinder import Finder, FindQuery

# Create finder
finder = Finder()

# Basic file discovery
query = FindQuery(
    root="/path/to/search",
    include=["**/*.py", "**/*.md"],
    exclude=["**/test_*.py"],
    max_depth=3,
    include_hidden=False
)

results = finder.find_files(query)

for result in results:
    print(f"{result.relative_path} -> {result.source_path}")
```

**Convenience Methods**:

```python
# Find Go files
go_files = finder.find_go_files(root="/path/to/project")

# Find configuration files
config_files = finder.find_config_files(root="/path/to/project")

# Find schema files
schema_files = finder.find_schema_files(root="/path/to/project")

# Find by extension
ts_files = finder.find_by_extension(root="/path/to/project", exts=["ts", "tsx"])
```

#### Proper pathlib Usage

**Critical Implementation Detail**: All path operations use `pathlib.Path` instead of string manipulation to avoid bugs found in the Go implementation.

```python
# Normalize root path using pathlib
root_path = Path(query.root).resolve()

# Use pathlib for glob operations
if "**" in pattern:
    matches = root_path.rglob(pattern.replace("**/", ""))
else:
    matches = root_path.glob(pattern)

# Get relative paths using pathlib
try:
    rel_path = abs_match.relative_to(root_path)
except ValueError:
    continue  # Path not relative to root
```

**Rationale**: Python's `pathlib` provides robust path operations that handle edge cases, platform differences, and normalization correctly. This addresses brittleness found in Go's string-based path manipulation.

#### Configuration & Models

**Location**: `src/pyfulmen/pathfinder/models.py`

- `FindQuery`: Search parameters (inherits from `FulmenDataModel`)
- `PathResult`: Discovery results (inherits from `FulmenDataModel`)
- `FinderConfig`: Finder configuration (inherits from `FulmenConfigModel`)

**Foundation Model Integration**: All models use Fulmen foundation models for consistent Pydantic configuration and validation.

#### Testing

**Coverage**: 47 comprehensive tests, 90%+ coverage

- Path safety validation tests (10 tests)
- Finder discovery tests (25 tests)
- Convenience method tests (8 tests)
- Edge case tests (4 tests)

**Location**: `tests/unit/pathfinder/`

**Parity**: 100% gofulmen pathfinder behavioral compliance

### ASCII Helpers Extension Module

Unicode-aware console formatting with terminal-specific width overrides and three-layer configuration.

#### Core Features

**Location**: `src/pyfulmen/ascii/`

- **Unicode Width Calculation**: wcwidth-based display width calculation
- **Terminal Override Support**: Per-terminal character width adjustments
- **Box Drawing**: Full box character support with proper width handling
- **Three-Layer Configuration**: Defaults → User overrides → BYOC
- **Auto-Detection**: Automatic terminal type detection via `TERM_PROGRAM`

#### String Width Calculation

**Location**: `src/pyfulmen/ascii/ascii.py`

```python
from pyfulmen.ascii import string_width

# Calculate display width (handles Unicode, emojis, CJK)
width = string_width("Hello 世界")  # Returns actual terminal width
width = string_width("Box: ┌─┐")    # Accounts for box drawing characters

# Pad to width
padded = pad_right("Hello", 10)    # "Hello     "
padded = pad_left("Hello", 10)     # "     Hello"
padded = pad_center("Hello", 10)   # "  Hello   "

# Truncate to width
truncated = truncate("Very long string", 10, ellipsis="...")
```

**wcwidth Integration**: Uses the `wcwidth` library for accurate Unicode width calculation, with terminal-specific overrides applied on top.

#### Terminal Configuration

**Location**: `src/pyfulmen/ascii/terminal.py`

**Three-Layer Pattern**:

1. **Layer 1 (Defaults)**: Embedded terminal overrides from Crucible SSOT
2. **Layer 2 (User Overrides)**: `~/.config/fulmen/terminal-overrides.yaml`
3. **Layer 3 (BYOC)**: Runtime configuration via API (future)

**Auto-Detection**:

```python
# Automatically detects terminal from TERM_PROGRAM environment variable
terminal_config = get_terminal_config()  # Returns config for current terminal

# Supported terminals:
# - vscode (Visual Studio Code)
# - Apple_Terminal (macOS Terminal.app)
# - iTerm.app (iTerm2)
# - Generic fallback for unsupported terminals
```

**Terminal Override Example**:

```yaml
# ~/.config/fulmen/terminal-overrides.yaml
profiles:
  - terminalType: "vscode"
    terminalName: "Visual Studio Code"
    overrides:
      "─": 1 # Horizontal line should be width 1
      "│": 1 # Vertical line should be width 1
      "┌": 1 # Top-left corner
      "└": 1 # Bottom-left corner
```

**Rationale**: Different terminals render box-drawing characters with different widths. VSCode, for example, may render some characters as width-2 when they should be width-1, causing alignment issues. Terminal-specific overrides fix this.

#### Box Drawing

**Location**: `src/pyfulmen/ascii/ascii.py`

```python
from pyfulmen.ascii import draw_box, BoxStyle

# Draw a simple box
box = draw_box(width=20, height=5, style=BoxStyle.SINGLE)
print(box)
# Output:
# ┌──────────────────┐
# │                  │
# │                  │
# │                  │
# └──────────────────┘

# Draw box with content
box = draw_box(
    width=30,
    height=7,
    style=BoxStyle.DOUBLE,
    title="Status",
    content=["Line 1", "Line 2", "Line 3"]
)
```

**Box Styles**:

- `SINGLE`: Single-line box drawing (┌─┐│└┘)
- `DOUBLE`: Double-line box drawing (╔═╗║╚╝)
- `ROUNDED`: Rounded corners (╭─╮│╰╯)
- `BOLD`: Bold/heavy lines (┏━┓┃┗┛)

#### Testing

**Coverage**: 48 comprehensive tests, 90%+ coverage

- String width calculation tests (15 tests)
- Padding/truncation tests (12 tests)
- Box drawing tests (10 tests)
- Terminal configuration tests (11 tests)

**Location**: `tests/unit/ascii/`

**Parity**: 100% gofulmen ASCII implementation alignment

### Config Three-Layer System

Enhanced configuration loading with comprehensive metadata tracking and vendor/app namespace support.

#### Core Features

**Location**: `src/pyfulmen/config/`

- **Metadata Tracking**: Full visibility into which layers provide which configuration values
- **Vendor/App Namespacing**: Support for application-specific config directories
- **Three-Layer Merge**: Crucible defaults → User overrides → Application config
- **Environment Overrides**: `FULMEN_CONFIG_DIR` and `APP_CONFIG_DIR` support
- **Schema Validation**: Optional validation against Crucible schemas

#### ConfigLoader API

**Location**: `src/pyfulmen/config/loader.py`

```python
from pyfulmen.config import ConfigLoader

# Create loader
loader = ConfigLoader()

# Load with metadata tracking
result = loader.load_with_metadata(
    crucible_path="ascii/v1.0.0/terminal-overrides-defaults",
    app_config={"terminals": {"myterm": {"name": "Custom"}}}
)

# Inspect metadata
print(f"Layers applied: {len(result.sources)}")
for source in result.sources:
    print(f"  Layer {source.layer}: {source.source} (applied={source.applied})")

# Access merged config
config = result.config
```

**ConfigLoadResult Model**:

```python
class ConfigLoadResult(FulmenDataModel):
    """Result of configuration loading with metadata."""
    config: dict[str, Any]  # Final merged configuration
    sources: list[ConfigSource]  # Metadata about each layer

class ConfigSource(FulmenDataModel):
    """Metadata about a configuration layer."""
    layer: str  # "defaults", "user", "app"
    source: str  # Path or description
    applied: bool  # Whether layer contributed values
```

#### Vendor/App Namespace Support

**Location**: `src/pyfulmen/config/paths.py`

```python
from pyfulmen.config.paths import get_app_config_dir, get_fulmen_config_dir

# Get Fulmen config directory
fulmen_dir = get_fulmen_config_dir()
# Returns: ~/.config/fulmen (or $FULMEN_CONFIG_DIR override)

# Get application-specific config directory
app_dir = get_app_config_dir(vendor="acme", app="rocket")
# Returns: ~/.config/acme/rocket (or $APP_CONFIG_DIR override)

# Directory creation
from pyfulmen.config.paths import ensure_dir
config_path = ensure_dir(app_dir) / "settings.yaml"
```

**Environment Variable Overrides**:

- `FULMEN_CONFIG_DIR`: Override default `~/.config/fulmen`
- `APP_CONFIG_DIR`: Override default `~/.config/{vendor}/{app}`

#### Testing

**Coverage**: 30+ comprehensive tests, 93%+ coverage

- Three-layer merge tests (8 tests)
- Metadata tracking tests (6 tests)
- Namespace/path tests (10 tests)
- Environment override tests (6 tests)

**Location**: `tests/unit/config/`

### Schema Catalog & Validation

Comprehensive schema discovery and validation with goneat integration.

#### Core Features

**Location**: `src/pyfulmen/schema/`

- **Schema Catalog**: Automatic discovery of all Crucible schemas
- **Metadata Tracking**: SchemaInfo with id, category, version, name, path, description
- **Goneat Integration**: Prefer goneat validation, fallback to jsonschema
- **Rich Diagnostics**: Detailed error reporting with line/column information
- **CLI Tools**: Command-line schema validation with multiple output formats

#### Schema Catalog

**Location**: `src/pyfulmen/schema/catalog.py`

```python
from pyfulmen.schema.catalog import list_schemas, get_schema, parse_schema_id

# List all available schemas
schemas = list_schemas()
for schema in schemas:
    print(f"{schema.id}: {schema.description}")

# Get specific schema
schema_info = get_schema("ascii/v1.0.0/box-chars")
print(f"Schema: {schema_info.name}")
print(f"Path: {schema_info.path}")

# Parse schema ID
parts = parse_schema_id("ascii/v1.0.0/box-chars")
# Returns: ("ascii", "v1.0.0", "box-chars")
```

**SchemaInfo Model**:

```python
class SchemaInfo(FulmenDataModel):
    """Metadata about a discovered schema."""
    id: str  # "category/version/name"
    category: str  # "ascii", "config", "logging", etc.
    version: str  # "v1.0.0"
    name: str  # "box-chars"
    path: Path  # Absolute path to schema file
    description: str  # From schema $comment or title
```

#### Validation API

**Location**: `src/pyfulmen/schema/validator.py`

```python
from pyfulmen.schema.validator import validate_data, validate_file

# Validate data against schema
result = validate_data(
    schema_id="ascii/v1.0.0/box-chars",
    data={"style": "single", "chars": {...}},
    use_goneat=True  # Prefer goneat, fallback to jsonschema
)

if result.is_valid:
    print("✅ Validation passed")
else:
    for diag in result.diagnostics:
        print(f"❌ {diag.severity}: {diag.message}")
        print(f"   at {diag.path} (line {diag.line})")

# Validate file
result = validate_file(
    schema_id="config/v1.0.0/finder-config",
    file_path="config.json"
)
```

**ValidationResult Model**:

```python
class ValidationResult(FulmenDataModel):
    """Result of schema validation."""
    schema: SchemaInfo  # Schema metadata
    is_valid: bool  # Whether validation passed
    diagnostics: list[Diagnostic]  # Errors/warnings
    source: str  # "goneat" or "jsonschema"

class Diagnostic(FulmenDataModel):
    """Validation error or warning."""
    severity: str  # "error" or "warning"
    message: str  # Human-readable message
    path: str  # JSON path to error location
    line: int | None  # Line number if available
    column: int | None  # Column number if available
```

#### CLI Validation

**Location**: `src/pyfulmen/schema/cli/validate.py`

```bash
# Validate with goneat integration
uv run python -m pyfulmen.schema.cli.validate \
  --schema-id ascii/v1.0.0/box-chars \
  --file data.json

# Force jsonschema (no goneat)
uv run python -m pyfulmen.schema.cli.validate \
  --schema-id ascii/v1.0.0/box-chars \
  --file data.json \
  --no-goneat

# Output formats: text (default), json
uv run python -m pyfulmen.schema.cli.validate \
  --schema-id ascii/v1.0.0/box-chars \
  --file data.json \
  --format json
```

**Helper Script**: `scripts/validate-schema.sh`

```bash
# Prefers goneat if available, falls back to PyFulmen CLI
./scripts/validate-schema.sh ascii/v1.0.0/box-chars data.json

# Configure via environment variable
PYFULMEN_SCHEMA_HELPER=python-only ./scripts/validate-schema.sh ...
```

#### Testing

**Coverage**: 15+ comprehensive tests, 90%+ coverage

- Catalog discovery tests (5 tests)
- Validation tests (6 tests)
- CLI integration tests (4 tests)

**Location**: `tests/unit/schema/`, `tests/fixtures/schema/`

### Ecosystem ADR Adoption Tracking

Comprehensive tracking of PyFulmen's implementation status for ecosystem-wide architectural decisions.

#### Adoption Status Document

**Location**: `docs/development/adr/ecosystem-adoption-status.md`

**Adoption Status Levels**:

- **not-applicable** (0): Does not apply to this library
- **deferred** (5): Postponed with documented rationale
- **planned** (10): Implementation planned but not started
- **in-progress** (20): Active implementation underway
- **implemented** (30): Fully implemented, ready for validation
- **verified** (40): Implemented and validated through tests/production use

**Tracked Ecosystem ADRs**:

| Ecosystem ADR | Title                             | Status               | Test Evidence                                  |
| ------------- | --------------------------------- | -------------------- | ---------------------------------------------- |
| ADR-0001      | Two-Tier ADR System               | **verified** (40)    | 4 local + 5 ecosystem ADRs tracked             |
| ADR-0002      | Triple-Index Catalog Strategy     | **verified** (40)    | 227 foundry tests, gofulmen parity verified    |
| ADR-0003      | Progressive Logging Profiles      | **verified** (40)    | 200+ logging tests, all 4 profiles implemented |
| ADR-0004      | Schema-Driven Config Hydration    | **implemented** (30) | Layer 1 & 2 complete, Layer 3 partial          |
| ADR-0005      | CamelCase to Language Conventions | **verified** (40)    | Field aliases working throughout               |

#### Module Maturity Tracking

**Coverage Summary**:

| Module | Core/Extension | Test Count | Coverage | Ecosystem ADRs | Status |
|--------|---------------|------------|----------|----------------|---------| | Foundry | Core | 227 | 95% | ADR-0002, ADR-0005 | ✅ Stable |
| Logging | Core | 200+ | 96-100% | ADR-0003 | ✅ Stable |
| Config | Core | 30+ | 93%+ | ADR-0004, ADR-0005 | ✅ Stable |
| Crucible Shim | Core | 20+ | 95%+ | ADR-0001 | ✅ Stable |
| Schema | Core | 15+ | 90%+ | ADR-0004 | ✅ Stable |
| Pathfinder | Extension | 47 | 90%+ | - | ✅ Stable |
| ASCII | Extension | 48 | 90%+ | ADR-0004 | ✅ Stable |

**Total Tests**: 613 passing (up from 520 in v0.1.2)

#### Documentation Updates

**Updated Documents**:

- `docs/pyfulmen_overview.md`: Module statuses, test counts, roadmap
- `docs/development/adr/README.md`: Ecosystem ADR adoption status levels
- `docs/development/adr/ecosystem-adoption-status.md`: Comprehensive tracking (new)

---

## 🎬 Logging Demo Script

Comprehensive interactive demonstration of PyFulmen's progressive logging capabilities.

### Overview

**Location**: `scripts/demos/logging_demo.py`

A complete, executable demo script showcasing all progressive logging features with real-world examples and clear section-by-section demonstrations.

### Features Demonstrated

**Progressive Profiles**:

- **SIMPLE Profile**: Zero-config console logging for CLI tools
- **STRUCTURED Profile**: JSON output for services and background jobs
- **ENTERPRISE Profile**: Full correlation IDs, middleware, and policy enforcement

**Severity Levels**:

- TRACE → DEBUG → INFO → WARN → ERROR → FATAL
- Complete coverage of all severity levels with practical examples

**Advanced Features**:

- Context propagation across log events
- Correlation IDs with UUIDv7 for distributed tracing
- Error handling with exception details
- Profile comparison showing same event across profiles
- Nested context with batch processing examples

### Usage

```bash
# Direct invocation (recommended - uses shebang)
./scripts/demos/logging_demo.py

# Or with uv run (works from any directory in repo)
uv run python scripts/demos/logging_demo.py

# Or with activated virtual environment
source .venv/bin/activate
python scripts/demos/logging_demo.py
```

### Demo Sections

1. **SIMPLE Profile Demo**: CLI tool logging with human-readable output
2. **STRUCTURED Profile Demo**: API gateway JSON logging
3. **ENTERPRISE Profile Demo**: Payment processor with correlation
4. **Severity Levels Demo**: All levels from TRACE to FATAL
5. **Error Logging Demo**: Exception handling with stack traces
6. **Contextual Logging Demo**: Batch processing with nested context
7. **Profile Comparison Demo**: Same log event across all profiles

### Design Highlights

**Output Separation**:

- Section headers written to stdout (above)
- Log events written to stderr (below)
- Clean separation for demonstration clarity

**Path Manipulation**:

```python
# Adds src/ to path for development environment
repo_root = Path(__file__).parent.parent.parent
sys.path.insert(0, str(repo_root / "src"))
```

**Timing Controls**: Built-in delays between sections for readability during live demos

### Development Integration

**Makefile Integration**:

- Demo scripts now included in `make fmt` and `make lint` targets
- Ensures demo code follows project quality standards

**Ruff Configuration**:

```toml
# ruff.toml
[lint.per-file-ignores]
"scripts/demos/*.py" = ["E402"]  # Allow imports after path manipulation
```

### Example Output

```
================================================================================
  SIMPLE Profile
  Zero-config console logging for CLI tools and scripts
================================================================================

>>> Logging at different severity levels:

[2025-10-20T12:30:15.123456Z] INFO  [cli-tool] Application started
[2025-10-20T12:30:15.345678Z] INFO  [cli-tool] Processing user request
[2025-10-20T12:30:15.567890Z] WARN  [cli-tool] Slow response detected
[2025-10-20T12:30:15.789012Z] ERROR [cli-tool] Failed to connect to external API

================================================================================
  STRUCTURED Profile
  Structured JSON logging for services and background jobs
================================================================================

>>> JSON-formatted log events:

{"timestamp":"2025-10-20T12:30:16.123456Z","severity":"DEBUG","message":"Request received",...}
{"timestamp":"2025-10-20T12:30:16.345678Z","severity":"INFO","message":"User authenticated",...}
```

### Target Audience

- **Developers**: Learning PyFulmen logging capabilities
- **Architects**: Understanding progressive logging patterns
- **Operations**: Seeing real-world logging output formats
- **Demo Presenters**: Live demonstrations of PyFulmen features

---

## 🔧 Implementation Fixes

### Test File Name Collision Fix

**Fixed**: Renamed pathfinder test file to avoid pytest collection errors

**Issue**: `tests/unit/pathfinder/test_models.py` collided with `tests/unit/foundry/test_models.py`, causing pytest to fail with "imported module 'test_models' has this **file** attribute" error.

**Location**: `tests/unit/pathfinder/`

**Before**: `test_models.py`
**After**: `test_pathfinder_models.py`

**Impact**: Clean test collection, no ambiguity in test module naming

### Version Test Update

**Updated**: Basic version test to reflect v0.1.3

**Location**: `tests/test_basic.py`

**Before**: `assert pyfulmen.__version__ == "0.1.2"`
**After**: `assert pyfulmen.__version__ == "0.1.3"`

---

## 📊 Quality Metrics

### Test Coverage

- **Pathfinder Tests**: 47 tests, all passing
- **ASCII Tests**: 48 tests, all passing
- **Config Tests**: 30+ tests, all passing
- **Schema Tests**: 15+ tests, all passing
- **Total Tests**: 613 tests, all passing (+93 tests from v0.1.2)
- **Coverage**: 90%+ maintained across all modules

### Code Quality

- ✅ Ruff linting: All checks passing
- ✅ Ruff formatting: Code formatted consistently
- ✅ Type hints: Full type coverage maintained
- ✅ Documentation: Complete and validated

### Cross-Language Parity

- ✅ Pathfinder API: 100% gofulmen pathfinder parity
- ✅ ASCII API: 100% gofulmen ASCII implementation alignment
- ✅ Foundation Models: Consistent Pydantic patterns

---

## 🚀 Getting Started

### Pathfinder Usage

```python
from pyfulmen.pathfinder import Finder, FindQuery

# Create finder with default configuration
finder = Finder()

# Find Python files excluding tests
query = FindQuery(
    root="/path/to/project",
    include=["**/*.py"],
    exclude=["**/test_*.py", "**/__pycache__/**"],
    max_depth=5,
    include_hidden=False
)

results = finder.find_files(query)

for result in results:
    print(f"Found: {result.relative_path}")
    print(f"  Source: {result.source_path}")
    print(f"  Logical: {result.logical_path}")

# Convenience methods
go_files = finder.find_go_files(root="/path/to/project")
config_files = finder.find_config_files(root="/path/to/project")
schema_files = finder.find_schema_files(root="/path/to/project")
```

### ASCII Helpers Usage

```python
from pyfulmen.ascii import (
    string_width,
    pad_right,
    pad_left,
    pad_center,
    truncate,
    draw_box,
    BoxStyle,
    get_terminal_config
)

# Calculate Unicode-aware width
width = string_width("Hello 世界")  # Accounts for double-width characters
width = string_width("Box: ┌─┐")    # Accounts for box drawing

# Padding operations
padded = pad_right("Hello", 20)    # "Hello               "
padded = pad_left("World", 20)     # "               World"
padded = pad_center("Title", 20)   # "       Title        "

# Truncation with ellipsis
text = truncate("Very long text here", max_width=15, ellipsis="...")
# Output: "Very long te..."

# Box drawing
box = draw_box(
    width=40,
    height=10,
    style=BoxStyle.SINGLE,
    title="Status Report",
    content=[
        "System: OK",
        "Database: Connected",
        "API: Running"
    ]
)
print(box)

# Terminal detection
terminal_config = get_terminal_config()
if terminal_config:
    print(f"Terminal: {terminal_config.terminal_name}")
    print(f"Overrides: {len(terminal_config.overrides)} characters")
```

### Terminal Override Configuration

```bash
# Create user terminal overrides (optional)
mkdir -p ~/.config/fulmen
cat > ~/.config/fulmen/terminal-overrides.yaml <<EOF
profiles:
  - terminalType: "vscode"
    terminalName: "Visual Studio Code - Custom"
    overrides:
      "─": 1
      "│": 1
      "┌": 1
      "┐": 1
      "└": 1
      "┘": 1
EOF
```

---

## 📝 Known Limitations

### Pathfinder

- **Context Support**: No context cancellation support yet (Python context managers for async/cancel not yet implemented)
- **Caching**: Cache functionality disabled by default (performance sufficient without it)

### ASCII Helpers

- **BYOC Layer**: Layer 3 (Bring Your Own Config) runtime API not yet exposed
- **Additional Formatters**: Tables and progress bars not yet implemented (box drawing only)

### General

- **Windows Testing**: Best-effort Windows support, primarily tested on macOS/Linux
- **Performance Benchmarks**: Baseline performance metrics not yet established

---

## 🔄 Migration Guide

### From v0.1.2 to v0.1.3

**No breaking changes** - this release is fully backward compatible.

### New Features

1. **Pathfinder Module**: New extension module for filesystem discovery

   ```python
   # New functionality in v0.1.3
   from pyfulmen.pathfinder import Finder, FindQuery

   finder = Finder()
   results = finder.find_files(FindQuery(
       root="/path/to/search",
       include=["**/*.py"]
   ))
   ```

2. **ASCII Helpers Module**: New extension module for console formatting

   ```python
   # New functionality in v0.1.3
   from pyfulmen.ascii import string_width, draw_box, BoxStyle

   width = string_width("Hello 世界")
   box = draw_box(width=30, height=5, style=BoxStyle.SINGLE)
   ```

3. **Ecosystem ADR Tracking**: New documentation for architectural alignment
   - See `docs/development/adr/ecosystem-adoption-status.md`
   - All ecosystem ADRs now tracked with adoption status levels

### Dependencies

**New Dependencies**:

- `wcwidth>=0.2.0` - Unicode width calculation for ASCII helpers
- `click>=8.1.0` - CLI framework for schema validation tools

```bash
# If installing from source, dependencies are included automatically
pip install pyfulmen

# Or update existing installation
pip install --upgrade pyfulmen
```

---

## 🤝 Contributors

**Generated by**: PyFulmen Architect (@pyfulmen-architect) using [Claude Code](https://claude.ai/code)
**Supervised by**: @3leapsdave (Dave Thompson)
**Agentic Attribution**: All commits follow FulmenHQ agentic attribution standards

---

## 📚 Additional Resources

- **Repository**: [pyfulmen](https://github.com/fulmenhq/pyfulmen) (internal)
- **Pathfinder Documentation**: `src/pyfulmen/pathfinder/README.md`
- **ASCII Documentation**: `src/pyfulmen/ascii/README.md`
- **ADR Adoption Status**: `docs/development/adr/ecosystem-adoption-status.md`
- **ADR Index**: `docs/development/adr/README.md`
- **Standards**: `docs/crucible-py/standards/` for FulmenHQ ecosystem standards
- **Maintainers**: See `MAINTAINERS.md` for project governance

---

## 🎯 Next Steps

### v0.2.0 (Planned - Q1 2026)

Enterprise observability and performance:

- Enhanced correlation ID propagation (HTTP headers, gRPC metadata)
- Tracing integration (OpenTelemetry compatibility)
- External sink support (HTTP/HTTPS log shipping)
- Performance optimizations for high-throughput logging
- Async logging support for high-throughput services

### v0.3.0+ (Future)

Extended ecosystem utilities:

- Cloud storage helpers (S3/GCS/Azure)
- Metrics and tracing modules (full observability stack)
- Enhanced CLI tooling integration
- Performance benchmarks and optimization
- Additional ASCII formatters (tables, progress bars)

---

**Release**: v0.1.3
**Date**: October 20, 2025
**Status**: ✅ Released
