chore: fragments multiple paths and fix md errors

2025-12-26 23:24:53 +00:00 · 2025-12-26 23:24:53 +00:00 · f490760395
commit f490760395
parent 960e36aaf5
9 changed files with 514 additions and 31 deletions
--- a/.markdownlint-cli2.jsonc
+++ b/.markdownlint-cli2.jsonc
@ -4,6 +4,7 @@
    "MD013": false,
    "MD033": false,
    "MD041": false,
-    "MD036": false
+    "MD036": false,
+    "MD060": false
  }
 }
--- a/docs/agent/installation.md
+++ b/docs/agent/installation.md
@ -18,12 +18,14 @@ Complete installation guide for TypeDialog Agents system.
 ### System Requirements

 **Minimum:**
+
 - CPU: 2 cores
 - RAM: 4 GB
 - Disk: 1 GB free space
 - OS: Linux, macOS, or Windows (WSL2)

 **Recommended:**
+
 - CPU: 4+ cores
 - RAM: 8 GB
 - Disk: 5 GB free space (for cache and builds)
@ -32,6 +34,7 @@ Complete installation guide for TypeDialog Agents system.
 ### Software Requirements

 1. **Rust** (1.75.0 or later)
+
   ```bash
   # Install Rust via rustup
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
@ -42,6 +45,7 @@ Complete installation guide for TypeDialog Agents system.
   ```

 2. **Git**
+
   ```bash
   # Ubuntu/Debian
   sudo apt-get install git
@ -56,23 +60,27 @@ Complete installation guide for TypeDialog Agents system.
 3. **Build Tools**

   **Ubuntu/Debian:**
+
   ```bash
   sudo apt-get update
   sudo apt-get install build-essential pkg-config libssl-dev
   ```

   **macOS:**
+
   ```bash
   xcode-select --install
   ```

   **Fedora/RHEL:**
+
   ```bash
   sudo dnf groupinstall "Development Tools"
   sudo dnf install openssl-devel
   ```

 4. **Optional: Docker** (for containerized deployment)
+
   ```bash
   # Ubuntu/Debian
   curl -fsSL https://get.docker.com -o get-docker.sh
@ -170,6 +178,7 @@ ls -lh target/release/typedialog-ag*
 #### System-Wide Installation (Recommended)

 **Linux/macOS:**
+
 ```bash
 # Copy to /usr/local/bin
 sudo cp target/release/typedialog-ag /usr/local/bin/
@ -180,6 +189,7 @@ typedialog-ag --version
 ```

 **macOS (Homebrew style):**
+
 ```bash
 # Copy to Homebrew cellar
 sudo cp target/release/typedialog-ag /opt/homebrew/bin/
@ -339,7 +349,8 @@ typedialog-ag cache stats
 ```

 Expected output:
-```
+
+```text
 ✓ MDX syntax valid
 ✓ Transpilation successful
 ✓ Type checking passed
@ -355,11 +366,13 @@ Agent Summary:
 ### Test HTTP Server

 Terminal 1 - Start server:
+
 ```bash
 typedialog-ag serve --port 8765
 ```

 Terminal 2 - Test endpoints:
+
 ```bash
 # Health check
 curl http://localhost:8765/health
@ -391,6 +404,7 @@ If successful, you'll see a response from Claude.
 ### Build Errors

 **Error: `linker 'cc' not found`**
+
 ```bash
 # Ubuntu/Debian
 sudo apt-get install build-essential
@ -400,6 +414,7 @@ xcode-select --install
 ```

 **Error: `could not find openssl`**
+
 ```bash
 # Ubuntu/Debian
 sudo apt-get install libssl-dev pkg-config
@ -410,6 +425,7 @@ export PKG_CONFIG_PATH="/opt/homebrew/opt/openssl/lib/pkgconfig"
 ```

 **Error: Out of memory during build**
+
 ```bash
 # Reduce parallel jobs
 cargo build --release -j 2
@ -418,6 +434,7 @@ cargo build --release -j 2
 ### Runtime Errors

 **Error: `command not found: typedialog-ag`**
+
 ```bash
 # Check installation
 which typedialog-ag
@ -430,6 +447,7 @@ sudo cp target/release/typedialog-ag /usr/local/bin/
 ```

 **Error: `ANTHROPIC_API_KEY not set`**
+
 ```bash
 # Set environment variable
 export ANTHROPIC_API_KEY=sk-ant-your-key-here
@ -440,6 +458,7 @@ source ~/.bashrc
 ```

 **Error: `Permission denied`**
+
 ```bash
 # Fix permissions
 chmod +x /usr/local/bin/typedialog-ag
@ -449,6 +468,7 @@ chmod +x /usr/local/bin/typedialog-ag
 ```

 **Error: `Address already in use (port 8765)`**
+
 ```bash
 # Find process using port
 lsof -i :8765
@ -463,6 +483,7 @@ typedialog-ag serve --port 9000
 ### Cache Issues

 **Cache not working:**
+
 ```bash
 # Clear cache
 typedialog-ag cache clear
@ -475,6 +496,7 @@ ls -la ~/.typeagent/cache/
 ```

 **Cache directory permissions:**
+
 ```bash
 # Fix permissions
 chmod 700 ~/.typeagent
@ -484,16 +506,19 @@ chmod 700 ~/.typeagent/cache
 ### Agent Validation Errors

 **Error: `Failed to parse MDX`**
+
 - Check YAML frontmatter syntax
 - Ensure `---` delimiters are correct
 - Validate directive syntax (`@agent`, `@input`, etc.)

 **Error: `Failed to transpile`**
+
 - Verify agent directive has valid fields
 - Check for typos in field names
 - Ensure proper quoting in YAML

 **Error: `Type checking failed`**
+
 - Usually indicates Nickel evaluation issue
 - Run with verbose logging: `RUST_LOG=debug typedialog-ag validate ...`

@ -563,12 +588,14 @@ rm -rf ~/path/to/typedialog
 ### Remove Environment Variables

 Edit `~/.bashrc` or `~/.zshrc` and remove:
+
 ```bash
 export ANTHROPIC_API_KEY=...
 export PATH="$HOME/.local/bin:$PATH"  # If added for typeagent
 ```

 Then reload:
+
 ```bash
 source ~/.bashrc  # or ~/.zshrc
 ```
--- a/docs/ci/README.md
+++ b/docs/ci/README.md
@ -4,15 +4,15 @@ TypeDialog uses **dual CI/CD setup** to support both GitHub and Gitea/Forgejo pl

 ## Quick Reference

-| Platform | Files | Documentation |
-|----------|-------|---------------|
-| **GitHub Actions** | `.github/workflows/*.yml` | Auto-configured |
-| **Woodpecker CI** | `.woodpecker/*.yml` | See `.woodpecker/README.md` |
+| Platform           | Files                        | Documentation                |
+| ------------------ | ---------------------------- | ---------------------------- |
+| **GitHub Actions** | `.github/workflows/*.yml`    | Auto-configured              |
+| **Woodpecker CI**  | `.woodpecker/*.yml`          | See `.woodpecker/README.md`  |

 ## Platform Comparison

-| Feature | GitHub Actions | Woodpecker Basic | Woodpecker Advanced/Docker |
-|---------|---------------|------------------|---------------------------|
+| Feature         | GitHub Actions             | Woodpecker Basic           | Woodpecker Advanced/Docker |
+| --------------- | -------------------------- | -------------------------- | -------------------------- |
 | **Multi-OS** | ✅ Linux, macOS, Windows | ❌ Linux only | ✅ 5 targets* |
 | **Linting** | ✅ 5 languages (parallel) | ✅ 5 languages (parallel) | ✅ 5 languages (parallel) |
 | **Testing** | ✅ Matrix (3 OS) | ✅ Linux | ✅ Multi-OS** |
@ -32,6 +32,7 @@ TypeDialog uses **dual CI/CD setup** to support both GitHub and Gitea/Forgejo pl
 **Triggers**: Push to `main`/`develop`, Pull Requests

 **Stages**:
+
 1. **Linting** (parallel):
   - Rust (clippy)
   - Bash (shellcheck)
@ -44,6 +45,7 @@ TypeDialog uses **dual CI/CD setup** to support both GitHub and Gitea/Forgejo pl
 5. **Compliance**: `cargo deny check licenses`

 **Duration**:
+
 - GitHub Actions: ~20-25 min
 - Woodpecker CI: ~15-20 min (with custom image), ~25-30 min (without)

@ -54,11 +56,13 @@ TypeDialog uses **dual CI/CD setup** to support both GitHub and Gitea/Forgejo pl
 **GitHub Actions**: 6 targets, auto-upload, auto-publish to crates.io

 **Woodpecker CI**: 3 pipeline options
+
 - **Basic** (`release.yml`) - Linux x86_64 only, manual upload
 - **Advanced** (`release-advanced.yml`) - 5 targets, Gitea API auto-upload
 - **Docker-based** (`release-docker.yml`) - 5 targets, uses .woodpecker/Dockerfile.cross, Gitea API

 **Artifacts**:
+
 - Release binaries (GitHub: 6 targets, Woodpecker: 1-5 depending on pipeline)
 - SHA256 checksums
 - SBOM (SPDX + CycloneDX formats)
@ -81,12 +85,14 @@ just ci::deny          # License check
 ### GitHub Actions (Auto-configured)

 Secrets required:
+
 - `CODECOV_TOKEN` - For coverage reports
 - `CARGO_REGISTRY_TOKEN` - For crates.io publishing

 ### Woodpecker CI (Manual)

 See [`.woodpecker/README.md`](../../.woodpecker/README.md) for:
+
 - Activation steps
 - Custom Docker image (optional, faster CI)
 - Secrets configuration
@ -119,10 +125,12 @@ git push origin v0.1.0
 **Woodpecker Pipeline Selection**:

 Choose which release pipeline to use by renaming in `.woodpecker/`:
+
 - Keep only one `release.yml` active
 - Rename others to `.release-*.yml.disabled`

 Example (use Docker-based):
+
 ```bash
 mv .woodpecker/release.yml .woodpecker/.release-basic.yml.disabled
 mv .woodpecker/release-advanced.yml .woodpecker/.release-advanced.yml.disabled
--- a/docs/configuration.md
+++ b/docs/configuration.md
@ -270,6 +270,9 @@ export TYPEDIALOG_FRAGMENT_PATH="/usr/local/share/typedialog/fragments:$HOME/.ty
 typedialog form.toml
 ```

+**For complete documentation on fragment search paths, see:**
+[Fragment Search Paths](./fragment-search-paths.md) - Cascading search, use cases, troubleshooting
+
 ## CLI Backend Configuration Details

 ```toml
--- a/docs/deployment.md
+++ b/docs/deployment.md
@ -43,6 +43,7 @@ cargo run --release --package typedialog-ag -- serve --port 8765
 ### Environment Setup

 Create `.env` file:
+
 ```bash
 # .env
 ANTHROPIC_API_KEY=sk-ant-your-key-here
@ -52,6 +53,7 @@ TYPEAGENT_CACHE_DIR=/tmp/typeagent-cache
 ```

 Load environment:
+
 ```bash
 source .env
 typedialog-ag serve --port 8765
@ -349,6 +351,7 @@ volumes:
 ```

 Usage:
+
 ```bash
 cd docker

@ -514,6 +517,7 @@ spec:
 ```

 Deploy:
+
 ```bash
 # Apply manifests
 kubectl apply -f k8s/deployment.yaml
@ -619,6 +623,7 @@ server {
 ```

 Enable and test:
+
 ```bash
 # Test configuration
 sudo nginx -t
@ -640,6 +645,7 @@ sudo systemctl status nginx
 ### Prometheus Metrics

 Add metrics endpoint (future enhancement):
+
 ```rust
 // In main.rs
 Router::new()
@ -690,11 +696,13 @@ chmod +x health-check.sh
 ### API Key Management

 **DO NOT:**
+
 - Commit API keys to Git
 - Hardcode keys in configuration files
 - Share keys in plain text

 **DO:**
+
 - Use environment variables
 - Use secrets management (Vault, AWS Secrets Manager)
 - Rotate keys regularly
@ -735,7 +743,8 @@ sudo certbot renew --dry-run
 ### System Limits

 Edit `/etc/security/limits.conf`:
-```
+
+```text
 typeagent soft nofile 65536
 typeagent hard nofile 65536
 typeagent soft nproc 4096
@ -755,6 +764,7 @@ cache:
 ### Rust Performance

 Build with optimizations:
+
 ```toml
 # Cargo.toml
 [profile.release]
--- a/docs/features.md
+++ b/docs/features.md
@ -11,12 +11,14 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 ## Architecture & Backends

 ### Multi-Backend Factory Pattern
+
 - ✅ Unified trait-based backend architecture
 - ✅ Runtime backend selection (CLI, TUI, Web, AI, Agent, Prov-gen)
 - ✅ Trait-based backend abstraction for extensibility
 - ✅ Feature-gated backend compilation

 ### CLI Backend (inquire)
+
 - ✅ Interactive terminal prompts for scripting and automation
 - ✅ Inquire integration with custom styling
 - ✅ Prompt sequences with state management
@ -24,6 +26,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Support for 8 prompt types

 ### TUI Backend (ratatui)
+
 - ✅ Full terminal UI with keyboard navigation
 - ✅ Mouse support for interactive dialogs
 - ✅ Complex multi-field form rendering
@ -31,6 +34,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Terminal color and styling support

 ### Web Backend (axum)
+
 - ✅ Axum-based HTTP server with forms
 - ✅ HTML/CSS form rendering
 - ✅ Browser-based interactive forms
@ -38,6 +42,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ JSON request/response handling

 ### AI Backend (typedialog-ai)
+
 - ✅ Retrieval-Augmented Generation (RAG) system
 - ✅ Semantic search with embeddings
 - ✅ Knowledge system integration
@ -45,6 +50,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ LLM provider abstraction

 ### Agent Backend (typedialog-agent)
+
 - ✅ LLM-based agent execution
 - ✅ MDX markdown support for rich content
 - ✅ Agent workflow orchestration
@ -52,6 +58,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ State management for agent sessions

 ### Provisioning Generator (typedialog-prov-gen)
+
 - ✅ IaC (Infrastructure as Code) generation
 - ✅ Configuration generation from forms
 - ✅ Nickel-based provisioning templates
@ -63,6 +70,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 ## Configuration & Forms

 ### TOML-Based Form Definitions
+
 - ✅ Declarative form configuration in TOML
 - ✅ Fragment composition and reuse
 - ✅ Form inheritance and composition patterns
@ -70,6 +78,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Conditional form layouts

 ### Field Types Support
+
 - ✅ **8 Prompt Types**: text, confirm, select, multi-select, password, custom, editor, date
 - ✅ Text fields with placeholders and hints
 - ✅ Select/dropdown with option lists
@ -80,6 +89,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Editor fields for multi-line content

 ### Validation & Constraints
+
 - ✅ Field-level validation rules
 - ✅ Regex pattern matching validation
 - ✅ Length constraints (min/max)
@ -88,6 +98,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Contract-based constraints

 ### Dynamic Logic
+
 - ✅ Conditional field rendering
 - ✅ Smart defaults with expressions
 - ✅ Real-time validation feedback
@ -97,6 +108,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Expression evaluation

 ### Repeating Groups
+
 - ✅ Dynamic array/group field handling
 - ✅ Add/remove items at runtime
 - ✅ Duplicate detection and prevention
@ -108,6 +120,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 ## Internationalization (i18n)

 ### Multi-Language Support
+
 - ✅ Fluent (.ftl) translation support
 - ✅ Automatic locale detection
 - ✅ Multi-language form rendering
@ -117,6 +130,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Unicode and RTL support

 ### Fluent Integration
+
 - ✅ Fluent bundle loading and caching
 - ✅ Message formatting and placeholders
 - ✅ Plural form support
@ -128,6 +142,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 ## Advanced Features

 ### Type-Safe Schemas (Nickel)
+
 - ✅ Bidirectional Nickel integration
 - ✅ Schema validation using Nickel
 - ✅ Type-safe form definitions
@ -137,6 +152,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Schema evolution support

 ### Field-Level Encryption
+
 - ✅ External encryption service integration
 - ✅ Per-field encryption handling
 - ✅ Encrypted field visibility controls
@ -145,6 +161,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Secure credential storage

 ### Roundtrip Serialization
+
 - ✅ Form → JSON serialization
 - ✅ Form → YAML serialization
 - ✅ Form → TOML serialization
@ -154,6 +171,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Back-and-forth conversion support

 ### Output Format Support
+
 - ✅ JSON output with custom formatting
 - ✅ YAML output with proper indentation
 - ✅ TOML output with sections
@ -163,6 +181,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Format auto-detection

 ### Contract-Based Constraints
+
 - ✅ Pre-condition checking
 - ✅ Post-condition validation
 - ✅ Invariant enforcement
@ -175,6 +194,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 ## Provider Integrations

 ### AI Providers
+
 - ✅ **Gemini**: Google Generative AI integration
 - ✅ **OpenAI**: GPT integration with API support
 - ✅ **Ollama**: Local LLM model support
@ -183,6 +203,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Request/response normalization

 ### Provider Features
+
 - ✅ Async/await support
 - ✅ Streaming response handling
 - ✅ Token counting and limits
@ -195,6 +216,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 ## Infrastructure & DevOps

 ### CI/CD Pipeline
+
 - ✅ GitHub Actions workflow automation
 - ✅ Woodpecker CI integration
 - ✅ Cross-platform testing (Linux, macOS, Windows)
@ -204,6 +226,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Code coverage tracking

 ### Release Automation
+
 - ✅ Semantic versioning support
 - ✅ Automated release notes generation
 - ✅ Binary artifact building
@ -212,6 +235,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Version bumping automation

 ### Code Quality Gates
+
 - ✅ Clippy linting with strict warnings
 - ✅ Format checking (rustfmt)
 - ✅ Test coverage requirements
@ -220,6 +244,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Documentation build verification

 ### Docker Support
+
 - ✅ Multi-stage Docker builds
 - ✅ Minimal container images
 - ✅ Alpine Linux optimization
@ -229,6 +254,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Volume management

 ### Cross-Compilation
+
 - ✅ Cross-compilation for multiple targets
 - ✅ macOS binary generation
 - ✅ Linux binary generation
@ -236,6 +262,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Architecture-specific builds (x86_64, ARM64)

 ### Build System
+
 - ✅ Just recipes for common tasks
 - ✅ Modular justfiles for organization
 - ✅ Feature-gated compilation
@ -244,6 +271,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Incremental builds

 ### Package Management
+
 - ✅ Cargo workspace configuration
 - ✅ Dependency management
 - ✅ Feature flags for optional functionality
@ -251,6 +279,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Workspace member coordination

 ### Documentation & Testing
+
 - ✅ Zero runtime dependencies (core library)
 - ✅ Feature-specific dependencies
 - ✅ Minimal binary size
@ -264,6 +293,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 ## Core Library Capabilities

 ### Library Design
+
 - ✅ Modular architecture with feature gates
 - ✅ Zero runtime dependencies for core
 - ✅ Optional feature-based extensions
@ -272,6 +302,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Plugin-like backend system

 ### Form Processing Pipeline
+
 - ✅ TOML parsing → Form struct conversion
 - ✅ Validation before rendering
 - ✅ Backend-agnostic form execution
@ -279,6 +310,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Error handling and recovery

 ### Testing Infrastructure
+
 - ✅ 3,818+ passing tests
 - ✅ Unit tests per module
 - ✅ Integration tests across backends
@ -287,6 +319,7 @@ Comprehensive breakdown of all implemented features across subsystems and backen
 - ✅ Continuous testing in CI

 ### Feature Combination Testing
+
 - ✅ CLI backend with all features
 - ✅ TUI backend with all features
 - ✅ Web backend with all features
--- a/docs/fragment-search-paths.md
+++ b/docs/fragment-search-paths.md
@ -0,0 +1,375 @@
+# Fragment Search Paths
+
+TypeDialog supports loading form fragments from multiple directories using the `TYPEDIALOG_FRAGMENT_PATH` environment variable.
+
+## Overview
+
+**Fragment search paths** enable:
+
+- ✅ Centralized fragment libraries shared across projects
+- ✅ Local overrides for project-specific customizations
+- ✅ Zero duplication when using standard fragments
+- ✅ Automatic updates when central library is updated
+
+## Environment Variable
+
+### TYPEDIALOG_FRAGMENT_PATH
+
+Colon-separated list (semicolon on Windows) of directories to search for fragment files.
+
+**Unix/Linux/macOS:**
+
+```bash
+export TYPEDIALOG_FRAGMENT_PATH="/path/to/fragments:/another/path"
+```
+
+**Windows:**
+
+```cmd
+set TYPEDIALOG_FRAGMENT_PATH=C:\fragments;D:\other\fragments
+```
+
+## Search Order
+
+When a fragment is referenced (e.g., `includes = ["fragments/user-fields.toml"]`), TypeDialog searches in this order:
+
+1. **Absolute path** → Use directly if provided
+2. **Form's directory** (`base_dir`) → Backward compatible behavior
+3. **Directories in TYPEDIALOG_FRAGMENT_PATH** → Search left to right
+4. **First match wins** → Subsequent directories are not checked
+
+### Example
+
+```bash
+export TYPEDIALOG_FRAGMENT_PATH=".typedialog/ci/fragments:/usr/local/share/typedialog/fragments"
+```
+
+**Fragment reference:** `includes = ["user-auth.toml"]`
+
+**Search order:**
+
+```text
+1. ./user-auth.toml (form's directory)
+2. .typedialog/ci/fragments/user-auth.toml (local)
+3. /usr/local/share/typedialog/fragments/user-auth.toml (system)
+```
+
+**Result:** First existing file is loaded.
+
+## Use Cases
+
+### Case 1: Centralized Fragment Library
+
+Organization maintains a shared library of standard fragments.
+
+**Setup:**
+
+```bash
+# System-wide fragments
+export TYPEDIALOG_FRAGMENT_PATH="/opt/company/typedialog/fragments"
+```
+
+**Directory structure:**
+
+```text
+/opt/company/typedialog/fragments/
+├── user-auth.toml
+├── database-config.toml
+├── api-settings.toml
+└── logging.toml
+```
+
+**Form reference:**
+
+```toml
+[[item]]
+type = "group"
+includes = ["user-auth.toml", "database-config.toml"]
+```
+
+**Benefit:** All projects use same fragments → consistency across organization.
+
+### Case 2: Local Overrides
+
+Project needs custom version of standard fragment.
+
+**Setup:**
+
+```bash
+export TYPEDIALOG_FRAGMENT_PATH=".typedialog/fragments:/opt/company/typedialog/fragments"
+```
+
+**Directory structure:**
+
+```text
+project/
+├── .typedialog/
+│   └── fragments/
+│       └── user-auth.toml  # ← Custom version
+└── form.toml
+```
+
+**Form reference:**
+
+```toml
+[[item]]
+type = "group"
+includes = ["user-auth.toml"]  # Uses local version
+```
+
+**Result:**
+
+- `user-auth.toml` → loads from `.typedialog/fragments/` (local override)
+- `database-config.toml` → loads from `/opt/company/...` (standard)
+
+**Benefit:** Override only what you need, rest stays synchronized.
+
+### Case 3: Multiple Fragment Sources
+
+Combine fragments from different sources: company library, team library, local.
+
+**Setup:**
+
+```bash
+export TYPEDIALOG_FRAGMENT_PATH=".typedialog/fragments:~/team-fragments:/opt/company/fragments"
+```
+
+**Search priority:**
+
+1. Project-specific (`.typedialog/fragments/`)
+2. Team-shared (`~/team-fragments/`)
+3. Company-wide (`/opt/company/fragments/`)
+
+**Benefit:** Flexible hierarchy for different scopes.
+
+## Configuration
+
+### direnv Integration
+
+Automatically load `TYPEDIALOG_FRAGMENT_PATH` when entering project directory.
+
+**Setup:**
+
+```bash
+# Install direnv
+brew install direnv  # macOS
+# Or: apt install direnv  # Linux
+
+# Add to shell rc file (~/.bashrc, ~/.zshrc)
+eval "$(direnv hook bash)"  # or zsh, fish, etc.
+
+# Create .envrc in project root
+cat > .envrc <<EOF
+export TYPEDIALOG_FRAGMENT_PATH=".typedialog/fragments:\$HOME/typedialog/fragments"
+EOF
+
+# Allow direnv to load .envrc
+direnv allow
+```
+
+**Result:** `TYPEDIALOG_FRAGMENT_PATH` is automatically set when you `cd` into project.
+
+### Shell Profile
+
+Set globally for all projects.
+
+**~/.bashrc or ~/.zshrc:**
+
+```bash
+export TYPEDIALOG_FRAGMENT_PATH="$HOME/.typedialog/fragments:/usr/local/share/typedialog/fragments"
+```
+
+### Per-Command
+
+Override for single invocation.
+
+```bash
+TYPEDIALOG_FRAGMENT_PATH="/custom/path" typedialog form schema.toml
+```
+
+## Implementation Details
+
+### Code Location
+
+`crates/typedialog-core/src/form_parser/parser.rs`
+
+**Functions:**
+
+- `get_fragment_search_paths()` - Parse environment variable
+- `resolve_fragment_path()` - Search directories in order
+
+**Logic:**
+
+```rust
+fn resolve_fragment_path(path: &str, base_dir: &Path) -> PathBuf {
+    // 1. Absolute path → use directly
+    if Path::new(path).is_absolute() {
+        return PathBuf::from(path);
+    }
+
+    // 2. Try base_dir (backward compatible)
+    let base_path = base_dir.join(path);
+    if base_path.exists() {
+        return base_path;
+    }
+
+    // 3. Try each search path
+    for search_dir in get_fragment_search_paths() {
+        let candidate = search_dir.join(path);
+        if candidate.exists() {
+            return candidate;
+        }
+    }
+
+    // 4. Return base_path for error reporting
+    base_path
+}
+```
+
+### Separator Detection
+
+**Unix/Linux/macOS:** `:` (colon)
+
+```rust
+#[cfg(unix)]
+let separator = ':';
+```
+
+**Windows:** `;` (semicolon)
+
+```rust
+#[cfg(windows)]
+let separator = ';';
+```
+
+### Backward Compatibility
+
+- ✅ If `TYPEDIALOG_FRAGMENT_PATH` not set → works as before (uses `base_dir`)
+- ✅ Absolute paths → always work regardless of search paths
+- ✅ Existing forms → no changes required
+
+## Best Practices
+
+### ✅ DO
+
+- **Use relative paths** in form definitions (`includes = ["fragment.toml"]`)
+- **Put local overrides first** in search path (`.typedialog/fragments:/system/fragments`)
+- **Document custom fragments** with comments explaining why local version exists
+- **Keep standard structure** when overriding (match original fragment structure)
+- **Version control .envrc** if project-specific paths are important
+
+### ❌ DON'T
+
+- **Don't hardcode absolute paths** in forms (defeats portability)
+- **Don't mix path separators** (use `:` on Unix, `;` on Windows)
+- **Don't create deep hierarchies** (2-3 levels max: local, team, system)
+- **Don't override without reason** (consider if change should be upstream)
+
+## Troubleshooting
+
+### Fragment not found
+
+**Error:**
+
+```text
+Error: Failed to load fragment 'user-fields.toml': No such file or directory
+```
+
+**Check:**
+
+```bash
+# 1. Verify environment variable is set
+echo $TYPEDIALOG_FRAGMENT_PATH
+
+# 2. Check if file exists in any search path
+ls .typedialog/fragments/user-fields.toml
+ls /usr/local/share/typedialog/fragments/user-fields.toml
+
+# 3. Check search order (add debug output)
+export TYPEDIALOG_DEBUG=1  # If supported
+```
+
+### Wrong version loaded
+
+**Symptom:** Expected local override, but system version is used.
+
+**Check search order:**
+
+```bash
+# Verify local path is FIRST
+echo $TYPEDIALOG_FRAGMENT_PATH
+# Should be: .typedialog/fragments:...
+
+# Verify local file exists
+ls -la .typedialog/fragments/fragment.toml
+```
+
+### Windows path issues
+
+**Problem:** Paths with spaces or special characters.
+
+**Solution:** Use quotes in environment variable:
+
+```cmd
+set TYPEDIALOG_FRAGMENT_PATH="C:\Program Files\TypeDialog\fragments;D:\Custom Fragments"
+```
+
+## Examples
+
+### Example 1: Standard Setup
+
+**Project structure:**
+
+```text
+project/
+├── form.toml
+├── .envrc
+└── .typedialog/
+    └── fragments/
+        └── custom-field.toml
+```
+
+**.envrc:**
+
+```bash
+export TYPEDIALOG_FRAGMENT_PATH=".typedialog/fragments:/usr/local/share/typedialog/fragments"
+```
+
+**form.toml:**
+
+```toml
+[[item]]
+type = "group"
+includes = [
+    "custom-field.toml",     # Loads from .typedialog/fragments/
+    "standard-fields.toml"   # Loads from /usr/local/share/.../
+]
+```
+
+### Example 2: Multi-Environment
+
+**Development:**
+
+```bash
+export TYPEDIALOG_FRAGMENT_PATH=".typedialog/fragments:$HOME/dev-fragments:/opt/fragments"
+```
+
+**Production:**
+
+```bash
+export TYPEDIALOG_FRAGMENT_PATH="/opt/company/fragments"
+```
+
+**Result:** Development has local overrides, production uses only approved fragments.
+
+## See Also
+
+- [Configuration Guide](./configuration.md) - Full TypeDialog configuration
+- [Fragment System](./fragments.md) - How to write fragments
+- [Environment Variables](./configuration.md#environment-variables) - All TypeDialog env vars
+
+---
+
+**Last Updated:** 2025-12-26
+**Feature:** TYPEDIALOG_FRAGMENT_PATH
+**Status:** ✅ Implemented in TypeDialog v0.1.0
--- a/docs/history.md
+++ b/docs/history.md
@ -7,6 +7,7 @@
 Prompts, forms, schemas definition, use backends (CLI, TUI, Web, AI). Extended with LLM agents, IaC generation, and Nickel validation.

 **Development Overview**:
+
 - **85 session tasks** completed
 - **3818 tests** implemented and passing
 - **16 git commits** to repository
@ -31,6 +32,7 @@ Prompts, forms, schemas definition, use backends (CLI, TUI, Web, AI). Extended w
 ## Project Subsystems

 ### Core Library
+
 - **typedialog-core**: Central library with trait-based backend architecture
  - Multi-backend support (CLI, TUI, Web)
  - Configuration management (TOML parsing)
@ -38,11 +40,13 @@ Prompts, forms, schemas definition, use backends (CLI, TUI, Web, AI). Extended w
  - Template engine (Tera integration)

 ### Binary Applications
+
 - **typedialog**: CLI binary (inquire backend)
 - **typedialog-tui**: Terminal UI (ratatui backend)  
 - **typedialog-web**: HTTP server (axum backend)

 ### New Subsystems (2025)
+
 - **typedialog-ai**: AI providers integration with RAG and knowledge systems
 - **typedialog-agent**: LLM and agent system with MDX support
 - **typedialog-prov-gen**: Configuration generation and provisioning utilities
@ -132,6 +136,7 @@ See [Features breakdown](./features.md) for detailed implementation details.
 ## Project Timeline

 **Major Phases**:
+
 1. ✅ **Foundation** - Multi-backend architecture and core library
 2. ✅ **Backends** - CLI (inquire), TUI (ratatui), Web (axum)
 3. ✅ **Features** - i18n, Nickel, Encryption, Templates
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@ -12,6 +12,7 @@ The binary will be at: `./target/release/typedialog-ag`
 ## Setup

 Configure your API key:
+
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-your-key-here
 ```
@ -78,12 +79,14 @@ echo '{"name":"Bob"}' | ./target/release/typedialog-ag agents/greeting.agent.mdx
 ### 4. HTTP Server Mode

 Start the server:
+
 ```bash
 ./target/release/typedialog-ag serve --port 8765
 ```

 Output:
-```
+
+```text
 🚀 Starting TypeAgent HTTP Server

 ⚙️  Configuration:
@ -115,7 +118,8 @@ Press Ctrl+C to stop the server

 ### 5. HTTP API Examples

-#### Execute greeting agent:
+#### Execute greeting agent
+
 ```bash
 curl -X POST http://localhost:8765/agents/greeting/execute \
  -H "Content-Type: application/json" \
@ -125,6 +129,7 @@ curl -X POST http://localhost:8765/agents/greeting/execute \
 ```

 Response:
+
 ```json
 {
  "output": "Hello Alice! I hope you're having a wonderful day...",
@ -138,7 +143,8 @@ Response:
 }
 ```

-#### Code Review:
+#### Code Review
+
 ```bash
 curl -X POST http://localhost:8765/agents/code-reviewer/execute \
  -H "Content-Type: application/json" \
@ -149,11 +155,13 @@ curl -X POST http://localhost:8765/agents/code-reviewer/execute \
 ```

 Response includes structured review with sections:
- ## Review
- ## Suggestions
- ## Security Considerations

-#### Architecture Design:
+- **Review**
+- **Suggestions**
+- **Security Considerations**
+
+### Architecture Design
+
 ```bash
 curl -X POST http://localhost:8765/agents/architect/execute \
  -H "Content-Type: application/json" \
@ -164,13 +172,15 @@ curl -X POST http://localhost:8765/agents/architect/execute \
 ```

 Response includes:
- ## Architecture
- ## Components
- ## Data Flow
- ## Technical Considerations
- ## Implementation Strategy

-#### Generate Tests:
+- **Architecture**
+- **Components**
+- **Data Flow**
+- **Technical Considerations**
+- **Implementation Strategy**
+
+### Generate Tests
+
 ```bash
 curl -X POST http://localhost:8765/agents/test-generator/execute \
  -H "Content-Type: application/json" \
@ -180,7 +190,8 @@ curl -X POST http://localhost:8765/agents/test-generator/execute \
  }'
 ```

-#### Debug Code:
+#### Debug Code
+
 ```bash
 curl -X POST http://localhost:8765/agents/debugger/execute \
  -H "Content-Type: application/json" \
@ -192,12 +203,14 @@ curl -X POST http://localhost:8765/agents/debugger/execute \
 ```

 Response includes:
- ## Root Cause
- ## Fix
- ## Prevention
- ## Testing

-#### Refactor Code:
+- **Root Cause**
+- **Fix**
+- **Prevention**
+- **Testing**
+
+### Refactor Code
+
 ```bash
 curl -X POST http://localhost:8765/agents/refactor/execute \
  -H "Content-Type: application/json" \
@ -247,6 +260,7 @@ Agents support optional inputs with `?` suffix:
 ```

 Usage:
+
 ```bash
 # With optional input
 curl -X POST http://localhost:8765/agents/architect/execute \
@ -285,7 +299,8 @@ Agents enforce quality with validation rules:
 ## Performance

 ### First Run (Cold Start)
-```
+
+```text
 Parse MDX:       ~5ms
 Transpile:      ~10ms
 Evaluate:       ~15ms
@ -294,7 +309,8 @@ Total:          ~2030ms
 ```

 ### Subsequent Runs (Cached)
-```
+
+```text
 Cache Hit:       ~0ms (instant)
 Evaluate:       ~15ms
 LLM Execution:  ~2000ms
@ -302,6 +318,7 @@ Total:          ~2015ms (15ms faster)
 ```

 ### Speedup
+
 - **~2x faster** for agent loading
 - Cache persists across restarts
 - Automatic invalidation on file changes (mtime-based)
@ -315,7 +332,8 @@ Run the comprehensive test suite:
 ```

 Output:
-```
+
+```text
 === TypeDialog Agent System Tests ===

 Test 1: Validating all agents...
@ -403,6 +421,7 @@ curl -X POST http://localhost:8765/agents/my-agent/execute \
 ## Troubleshooting

 ### Agent won't execute
+
 ```bash
 # Check validation
 typedialog-ag validate agents/your-agent.agent.mdx
@ -414,12 +433,14 @@ typedialog-ag validate agents/your-agent.agent.mdx
 ```

 ### Cache issues
+
 ```bash
 # Clear cache and retry
 typedialog-ag cache clear
 ```

 ### Server won't start
+
 ```bash
 # Check if port is in use
 lsof -i :8765