ostruct-cli 0.8.8__tar.gz → 1.0.0__tar.gz

{ostruct_cli-0.8.8 → ostruct_cli-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ostruct-cli
-Version: 0.8.8
+Version: 1.0.0
 Summary: CLI for OpenAI Structured Output with Multi-Tool Integration
 Author: Yaniv Golan
 Author-email: yaniv@golan.name
@@ -10,55 +10,32 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Provides-Extra: dev
 Provides-Extra: docs
 Provides-Extra: examples
-Requires-Dist: anyio[trio] (==3.7.1) ; extra == "dev"
 Requires-Dist: asyncio-throttle (>=1.0.2,<2.0) ; extra == "examples"
-Requires-Dist: black (==24.8.0) ; extra == "dev"
-Requires-Dist: build (>=1.2.2.post1,<2.0) ; extra == "dev"
+Requires-Dist: bleach (>=6.0.0,<7.0)
 Requires-Dist: cachetools (>=5.3.2,<6.0)
 Requires-Dist: chardet (>=5.0.0,<6.0)
 Requires-Dist: click (>=8.1.7,<9.0)
-Requires-Dist: flake8 (>=6.0,<7.0) ; extra == "dev"
-Requires-Dist: flake8-pyproject (>=1.2.3,<2.0) ; extra == "dev"
-Requires-Dist: hypothesis (>=6.0.0,<7.0) ; extra == "dev"
 Requires-Dist: ijson (>=3.2.3,<4.0)
 Requires-Dist: jinja2 (>=3.1.2,<4.0)
 Requires-Dist: jsonschema (>=4.23.0,<5.0)
-Requires-Dist: mypy (>=1.0,<2.0) ; extra == "dev"
-Requires-Dist: myst-parser (>=2.0.0,<3.0) ; extra == "docs"
+Requires-Dist: myst-parser (>=4.0.1,<5.0) ; extra == "docs"
 Requires-Dist: openai (==1.81.0)
 Requires-Dist: openai-model-registry (>=0.7.0,<1.0)
-Requires-Dist: pre-commit (>=4.1.0,<5.0) ; extra == "dev"
-Requires-Dist: psutil (>=7.0.0,<8.0) ; extra == "dev"
 Requires-Dist: pydantic (>=2.6.3,<3.0)
-Requires-Dist: pyfakefs (>=5.7.4,<6.0) ; extra == "dev"
 Requires-Dist: pygments (>=2.15.0,<3.0)
-Requires-Dist: pytest (>=8.3.4,<9.0) ; extra == "dev"
-Requires-Dist: pytest-asyncio (>=0.25.2,<1.0) ; extra == "dev"
-Requires-Dist: pytest-mock (>=3.14.0,<4.0) ; extra == "dev"
-Requires-Dist: pytest-rerunfailures (>=12.0,<13.0) ; extra == "dev"
 Requires-Dist: python-dotenv (>=1.0.1,<2.0)
-Requires-Dist: python-dotenv (>=1.0.1,<2.0) ; extra == "dev"
 Requires-Dist: pyyaml (>=6.0.2,<7.0)
-Requires-Dist: sphinx (>=7.0,<8.0) ; extra == "dev"
-Requires-Dist: sphinx (>=7.0,<8.0) ; extra == "docs"
-Requires-Dist: sphinx-design (>=0.5.0,<1.0) ; extra == "docs"
-Requires-Dist: sphinx-rtd-theme (>=1.0,<2.0) ; extra == "docs"
+Requires-Dist: rich (>=13.0.0,<14.0.0)
+Requires-Dist: rich-click (>=1.8.9,<2.0.0)
+Requires-Dist: sphinx (>=7.0.0,<8.0) ; extra == "docs"
+Requires-Dist: sphinx-design (>=0.4.1,<1.0) ; extra == "docs"
+Requires-Dist: sphinx-rtd-theme (>=2.0,<3.0) ; extra == "docs"
 Requires-Dist: tenacity (>=8.2.3,<9.0) ; extra == "examples"
 Requires-Dist: tiktoken (==0.9.0)
 Requires-Dist: tomli (>=2.0.1,<3.0) ; (python_version < "3.11") and (extra == "docs")
-Requires-Dist: tomli (>=2.0.1,<3.0) ; extra == "dev"
 Requires-Dist: tomli (>=2.0.1,<3.0) ; python_version < "3.11"
-Requires-Dist: twine (>=6.0.1,<7.0) ; extra == "dev"
-Requires-Dist: types-cachetools (>=5.5.0.20240820) ; extra == "dev"
-Requires-Dist: types-chardet (>=5.0.4.6) ; extra == "dev"
-Requires-Dist: types-click (>=7.1.8,<8.0) ; extra == "dev"
-Requires-Dist: types-jsonschema (>=4.23.0.20241208) ; extra == "dev"
-Requires-Dist: types-pygments (>=2.19.0.20250107) ; extra == "dev"
-Requires-Dist: types-pyyaml (>=6.0.12.20241230) ; extra == "dev"
-Requires-Dist: types-requests (>=2.32.0.20241016) ; extra == "dev"
 Requires-Dist: typing-extensions (>=4.9.0,<5.0)
 Requires-Dist: werkzeug (>=3.1.3,<4.0)
 Description-Content-Type: text/markdown
@@ -95,7 +72,7 @@ ostruct processes unstructured data (text files, code, CSVs, etc.), input variab
 
 <div align="center">
 
-![How ostruct works](src/assets/ostrict-hl-diagram.png)
+![How ostruct works](src/assets/ostruct-hl-diagram.png)
 
 </div>
 
@@ -116,11 +93,11 @@ ostruct can be used for various scenarios, including:
 ### Automated Code Review with Multi-Tool Analysis
 
 ```bash
-# Traditional pattern matching
-ostruct run prompts/task.j2 schemas/code_review.json -p source "examples/security/*.py"
+# Template-only analysis (fast, cost-effective)
+ostruct run prompts/task.j2 schemas/code_review.json --collect source @file-list.txt
 
 # Enhanced with Code Interpreter for deeper analysis
-ostruct run prompts/task.j2 schemas/code_review.json -fc examples/security/ -fs documentation/
+ostruct run prompts/task.j2 schemas/code_review.json --file ci:code examples/security/ --file fs:docs documentation/
 ```
 
 Analyze code for security vulnerabilities, style issues, and performance problems. The enhanced version uses Code Interpreter for execution analysis and File Search for documentation context.
@@ -130,15 +107,15 @@ Analyze code for security vulnerabilities, style issues, and performance problem
 ```bash
 # Budget-friendly static analysis (recommended for most projects)
 ostruct run prompts/static_analysis.j2 schemas/scan_result.json \
-  -d code examples -R --sys-file prompts/system.txt
+  --dir code examples --pattern "*.py" --sys-file prompts/system.txt
 
 # Professional security analysis with Code Interpreter (best balance)
 ostruct run prompts/code_interpreter.j2 schemas/scan_result.json \
-  -dc examples --sys-file prompts/system.txt
+  --dir ci:code examples --sys-file prompts/system.txt
 
 # Comprehensive hybrid analysis for critical applications
 ostruct run prompts/hybrid_analysis.j2 schemas/scan_result.json \
-  -d code examples -R -dc examples --sys-file prompts/system.txt
+  --dir code examples --dir ci:analysis examples --sys-file prompts/system.txt
 ```
 
 **Three optimized approaches** for automated security vulnerability scanning:
@@ -154,8 +131,8 @@ Each approach finds the same core vulnerabilities but with different levels of d
 ```bash
 # Upload data for analysis and visualization
 ostruct run analysis.j2 schemas/analysis_result.json \
-  -fc sales_data.csv -fc customer_data.json \
-  -fs reports/ -ft config.yaml
+  --file ci:sales sales_data.csv --file ci:customers customer_data.json \
+  --dir fs:reports reports/ --file config config.yaml
 ```
 
 Perform sophisticated data analysis using Python execution, generate visualizations, and create comprehensive reports with document context.
@@ -165,11 +142,11 @@ Perform sophisticated data analysis using Python execution, generate visualizati
 ```bash
 # Traditional file comparison
 ostruct run prompts/task.j2 schemas/validation_result.json \
-  -f dev examples/basic/dev.yaml -f prod examples/basic/prod.yaml
+  --file dev examples/basic/dev.yaml --file prod examples/basic/prod.yaml
 
 # Enhanced with environment context
 ostruct run prompts/task.j2 schemas/validation_result.json \
-  -ft dev.yaml -ft prod.yaml -fs infrastructure_docs/
+  --file dev dev.yaml --file prod prod.yaml --dir fs:docs infrastructure_docs/
 ```
 
 Validate configuration files across environments with documentation context for better analysis and recommendations.
@@ -179,11 +156,40 @@ Oh, and also, among endless other use cases:
 ### Etymology Analysis
 
 ```bash
-ostruct run prompts/task.j2 schemas/etymology.json -ft examples/scientific.txt
+ostruct run prompts/task.j2 schemas/etymology.json --file text examples/scientific.txt
 ```
 
 Break down words into their components, showing their origins, meanings, and hierarchical relationships. Useful for linguistics, educational tools, and understanding terminology in specialized fields.
 
+### Optional File References
+
+```bash
+# Attach files with aliases
+ostruct run template.j2 schema.json \
+  --dir source-code src/ \
+  --file config config.yaml
+```
+
+**Two ways to access files in templates:**
+
+```jinja2
+{# Option 1: Automatic XML appendix (optional) #}
+Analyze {{ file_ref("source-code") }} and {{ file_ref("config") }}.
+
+{# Option 2: Manual formatting (full control) #}
+## Source Code
+{% for file in source-code %}
+### {{ file.name }}
+```{{ file.name.split('.')[-1] }}
+{{ file.content }}
+```
+
+{% endfor %}
+
+```
+
+The optional `file_ref()` function provides clean references with automatic XML appendix generation. Alternatively, access files directly for custom formatting and placement control. Perfect for code reviews, documentation analysis, and multi-file processing workflows.
+
 ## Features
 
 ### Core Capabilities
@@ -201,7 +207,7 @@ Break down words into their components, showing their origins, meanings, and hie
 - **File Search**: Vector-based document search and retrieval from uploaded files
 - **Web Search**: Real-time information retrieval and current data access via OpenAI's web search tool
 - **MCP Servers**: Connect to Model Context Protocol servers for extended functionality
-- **Explicit File Routing**: Route different files to specific tools for optimized processing
+- **Explicit Tool Targeting**: Route files to specific tools (prompt, code-interpreter, file-search) with precise control
 
 ### Advanced Features
 
@@ -209,6 +215,7 @@ Break down words into their components, showing their origins, meanings, and hie
 - **Unattended Operation**: Designed for CI/CD and automation scenarios
 - **Progress Reporting**: Real-time progress updates with clear, user-friendly messaging
 - **Model Registry**: Dynamic model management with support for latest OpenAI models
+- **Optional File References**: Clean `file_ref()` function for automatic XML appendix, or direct file access for custom formatting
 
 ## Requirements
 
@@ -216,23 +223,93 @@ Break down words into their components, showing their origins, meanings, and hie
 
 ## Installation
 
-### Quick Install (macOS)
+We provide multiple installation methods to suit different user needs. Choose the one that's right for you.
 
-For macOS users, we provide a one-line installer that handles everything automatically:
+<details>
+<summary><strong>Recommended: pipx</strong></summary>
+
+`pipx` is the recommended installation method. It installs `ostruct` in an isolated environment, preventing conflicts with other Python packages.
+
+**macOS (with Homebrew):**
+```bash
+brew install pipx
+pipx install ostruct-cli       # new users
+pipx upgrade ostruct-cli       # existing users
+```
+
+**Linux (Ubuntu/Debian):**
 
 ```bash
-curl -sSL https://github.com/yaniv-golan/ostruct/releases/latest/download/install-macos.sh | bash
+sudo apt install pipx
+pipx install ostruct-cli       # new users
+pipx upgrade ostruct-cli       # existing users
 ```
 
-This script will:
+**Other systems:**
+
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+# Restart your terminal
+pipx install ostruct-cli
+```
+
+</details>
+
+<details>
+<summary><strong>macOS: Homebrew</strong></summary>
+
+If you're on macOS and use Homebrew, you can install `ostruct` with a single command:
+
+```bash
+brew install yaniv-golan/ostruct/ostruct-cli
+```
+
+</details>
+
+<details>
+<summary><strong>Standalone Binaries (No Python Required)</strong></summary>
+
+We provide pre-compiled .zip archives for macOS, Windows, and Linux that do not require Python to be installed.
+
+1. Go to the [**Latest Release**](https://github.com/yaniv-golan/ostruct/releases/latest) page.
+2. Download the `.zip` file for your operating system (e.g., `ostruct-macos-latest.zip`, `ostruct-windows-latest.zip`, `ostruct-ubuntu-latest.zip`).
+3. Extract the `.zip` file. This will create a folder (e.g., `ostruct-macos-amd64`).
+4. On macOS/Linux, make the executable inside the extracted folder runnable:
+
+    ```bash
+    chmod +x /path/to/ostruct-macos-amd64/ostruct
+    ```
+
+5. Run the executable from within the extracted folder, as it depends on bundled libraries in the same directory.
+
+</details>
+
+<details>
+<summary><strong>Docker</strong></summary>
+
+If you prefer to use Docker, you can run `ostruct` from our official container image available on the GitHub Container Registry.
+
+```bash
+docker run -it --rm \
+  -v "$(pwd)":/app \
+  -w /app \
+  ghcr.io/yaniv-golan/ostruct:latest \
+  run template.j2 schema.json --file config input.txt
+```
+
+This command mounts the current directory into the container and runs `ostruct`.
+
+</details>
 
-- Install Python 3.10+ if needed (via Homebrew or python.org)
-- Install Homebrew if needed
-- Install ostruct-cli via pip
-- Configure your shell PATH automatically
-- Verify the installation works
+### Uninstallation
 
-After installation, restart your terminal and test with `ostruct --version`.
+To uninstall `ostruct`, use the method corresponding to how you installed it:
+
+- **pipx**: `pipx uninstall ostruct-cli`
+- **Homebrew**: `brew uninstall ostruct-cli`
+- **Binaries**: Simply delete the binary file.
+- **Docker**: No uninstallation is needed for the image itself, but you can remove it with `docker rmi ghcr.io/yaniv-golan/ostruct:latest`.
 
 ### Manual Installation
 
@@ -254,12 +331,25 @@ If you plan to contribute to the project, see the [Development Setup](#developme
 
 ostruct-cli respects the following environment variables:
 
+**API Configuration:**
+
 - `OPENAI_API_KEY`: Your OpenAI API key (required unless provided via command line)
 - `OPENAI_API_BASE`: Custom API base URL (optional)
 - `OPENAI_API_VERSION`: API version to use (optional)
 - `OPENAI_API_TYPE`: API type (e.g., "azure") (optional)
+
+**System Configuration:**
+
 - `OSTRUCT_DISABLE_REGISTRY_UPDATE_CHECKS`: Set to "1", "true", or "yes" to disable automatic registry update checks
-- `MCP_<NAME>_URL`: Custom MCP server URLs (e.g., `MCP_STRIPE_URL=https://mcp.stripe.com`)
+- `OSTRUCT_MCP_URL_<name>`: Custom MCP server URLs (e.g., `OSTRUCT_MCP_URL_stripe=https://mcp.stripe.com`)
+
+**Template Processing Limits (Template-only files via `--file alias path`):**
+
+- `OSTRUCT_TEMPLATE_FILE_LIMIT`: Maximum individual file size for template access (default: 65536 bytes / 64KB)
+- `OSTRUCT_TEMPLATE_TOTAL_LIMIT`: Maximum total file size for all template files (default: 1048576 bytes / 1MB)
+- `OSTRUCT_TEMPLATE_PREVIEW_LIMIT`: Maximum characters shown in template debugging previews (default: 4096)
+
+> **Note**: Template limits only apply to files accessed via `--file alias path` (template-only routing). Files routed to Code Interpreter (`--file ci:`) or File Search (`--file fs:`) are not subject to these limits.
 
 **💡 Tip**: ostruct automatically loads `.env` files from the current directory. Environment variables take precedence over `.env` file values.
 
@@ -304,78 +394,101 @@ Shell completion will help you with:
 
 ## Enhanced CLI with Multi-Tool Integration
 
-### Migration Notice
+### Breaking Changes in v0.9.0
+
+**⚠️ Important:** ostruct v0.9.0 introduces breaking changes to the file attachment system. The legacy file routing syntax has been completely replaced with a new explicit target/alias attachment system.
 
-ostruct now includes powerful multi-tool integration while maintaining **full backward compatibility**. All existing commands continue to work exactly as before, but you can now take advantage of:
+**New capabilities in v0.9.0:**
 
-- **Code Interpreter** for data analysis and visualization
-- **File Search** for document retrieval
-- **Web Search** for real-time information access
-- **MCP Servers** for extended functionality
-- **Explicit File Routing** for optimized processing
+- **Explicit Tool Targeting**: Direct control over which tools receive files
+- **Enhanced Security**: Three-tier security modes with path validation
+- **Improved Multi-Tool Integration**: Better file sharing between tools
+- **JSON Help Output**: Programmatic access to command help
+- **Migration Guide**: Automated migration scripts for bulk updates
 
 <details>
-<summary><strong>New File Routing Options</strong> (Click to expand)</summary>
+<summary><strong>New Attachment System (v0.9.0)</strong> (Click to expand)</summary>
 
-#### Basic File Routing (Explicit Tool Assignment)
+#### Basic File Attachments
 
 ```bash
-# Template access only (config files, small data)
-ostruct run template.j2 schema.json -ft config.yaml
+# Template access only (default - no tool upload)
+ostruct run template.j2 schema.json --file config config.yaml
 
 # Code Interpreter (data analysis, code execution)
-ostruct run analysis.j2 schema.json -fc data.csv
+ostruct run analysis.j2 schema.json --file ci:data data.csv
 
 # File Search (document retrieval)
-ostruct run search.j2 schema.json -fs documentation.pdf
-
-# Web Search (real-time information)
-ostruct run research.j2 schema.json --enable-tool web-search -V topic="latest AI developments"
+ostruct run search.j2 schema.json --file fs:docs documentation.pdf
 
-# Multiple tools with one file
-ostruct run template.j2 schema.json --file-for code-interpreter shared.json --file-for file-search shared.json
+# Multi-tool attachment (share between tools)
+ostruct run workflow.j2 schema.json --file ci,fs:shared data.json
 ```
 
-#### Directory Routing
+#### Directory Attachments
 
-ostruct provides two directory routing patterns to match different use cases:
+```bash
+# Template-only directory access
+ostruct run template.j2 schema.json --dir config ./config
 
-**Auto-Naming Pattern** (for known directory structures):
+# Upload directory to Code Interpreter
+ostruct run analysis.j2 schema.json --dir ci:datasets ./data
 
-```bash
-# Variables are auto-generated from directory contents
-ostruct run template.j2 schema.json -dt ./config -dc ./datasets -ds ./docs
-# Creates variables like: config_yaml, datasets_csv, docs_pdf (based on actual files)
+# Upload directory to File Search
+ostruct run search.j2 schema.json --dir fs:knowledge ./docs
+
+# Directory with file pattern filtering
+ostruct run template.j2 schema.json --dir source ./src --pattern "*.py"
 ```
 
-**Alias Pattern** (for generic, reusable templates):
+#### File Collections
 
 ```bash
-# Create stable variable names regardless of directory contents
-ostruct run template.j2 schema.json --dta app_config ./config --dca data ./datasets --dsa knowledge ./docs
-# Creates stable variables: app_config, data, knowledge (always these names)
+# Process multiple files from list
+ostruct run batch.j2 schema.json --collect files @file-list.txt
+
+# Upload collection to Code Interpreter
+ostruct run analyze.j2 schema.json --collect ci:data @datasets.txt
 ```
 
-**When to Use Each Pattern:**
+#### Tool Targeting
 
-- Use **auto-naming** (`-dt`, `-dc`, `-ds`) when your template knows the specific directory structure
-- Use **alias syntax** (`--dta`, `--dca`, `--dsa`) when your template is generic and needs stable variable names
+The new system uses explicit targets for precise control:
 
-**Template Example:**
+- **`prompt`** (default): Template access only, no upload
+- **`code-interpreter`** or **`ci`**: Upload for Python execution and analysis
+- **`file-search`** or **`fs`**: Upload to vector store for document search
+- **Multi-target**: `ci,fs:alias` shares file between multiple tools
 
-```jinja
-{# Works with alias pattern - variables are predictable #}
-{% for file in app_config %}
-Configuration: {{ file.name }} = {{ file.content }}
-{% endfor %}
+#### Development Best Practice: Always Use --dry-run
 
-{# Analysis data from stable variable name #}
-{% for file in data %}
-Processing: {{ file.path }}
-{% endfor %}
+**Validate templates before execution** to catch errors early and save API costs:
+
+```bash
+# 1. Validate everything first (catches binary file issues, template errors)
+ostruct run analysis.j2 schema.json --file ci:data report.xlsx --dry-run
+
+# 2. If validation passes, run for real
+ostruct run analysis.j2 schema.json --file ci:data report.xlsx
 ```
 
-This design pattern makes templates reusable across different projects while maintaining full backward compatibility.
+The `--dry-run` flag performs comprehensive validation including template rendering, catching issues like:
+
+- Binary file content access errors
+- Template syntax problems
+- Missing template variables
+- File accessibility issues
+
+#### Security Modes
+
+```bash
+# Strict security with explicit allowlists
+ostruct run template.j2 schema.json \
+  --path-security strict \
+  --allow /safe/directory \
+  --allow-file /specific/file.txt \
+  --file data input.txt
+```
 
 #### MCP Server Integration
 
@@ -397,7 +510,7 @@ models:
 tools:
   code_interpreter:
     auto_download: true
-    output_directory: "./output"
+    output_directory: "./downloads"
     download_strategy: "two_pass_sentinel"  # Enable reliable file downloads
 
 mcp:
@@ -413,6 +526,44 @@ Load custom configuration:
 ostruct --config my-config.yaml run template.j2 schema.json
 ```
 
+### Model Validation
+
+ostruct automatically validates model names against the OpenAI model registry. Only models that support structured output are available for selection, ensuring compatibility with JSON schema outputs.
+
+```bash
+# See all available models with details
+ostruct list-models
+
+# Models are validated at command time
+ostruct run template.j2 schema.json --model invalid-model
+# Error: Invalid model 'invalid-model'. Available models: gpt-4o, gpt-4o-mini, o1 (and 12 more).
+#        Run 'ostruct list-models' to see all 15 available models.
+
+# Shell completion works with model names
+ostruct run template.j2 schema.json --model <TAB>
+# Shows: gpt-4o  gpt-4o-mini  o1  o1-mini  o3-mini  ...
+```
+
+**Model Registry Updates:**
+
+The model list is automatically updated when you run `ostruct update-registry`. If you encounter model validation errors, try updating your registry first:
+
+```bash
+# Update model registry
+ostruct update-registry
+
+# Check available models
+ostruct list-models
+```
+
+**Migration from Free-form Model Names:**
+
+If you have existing scripts with hardcoded model names, they will continue to work as long as the model names are valid. Common issues and solutions:
+
+- **Typos**: `gpt4o` → `gpt-4o`
+- **Old names**: `gpt-4-turbo` → `gpt-4o`
+- **Custom names**: Use `ostruct list-models` to see what's available
+
 ### Code Interpreter File Downloads
 
 **Important**: If you're using Code Interpreter with structured output (JSON schemas), you may need to enable the two-pass download strategy to ensure files are downloaded reliably.
@@ -421,10 +572,14 @@ ostruct --config my-config.yaml run template.j2 schema.json
 
 ```bash
 # Enable reliable file downloads for this run
-ostruct run template.j2 schema.json -fc data.csv --enable-feature ci-download-hack
+ostruct run template.j2 schema.json --file ci:data data.csv --enable-feature ci-download-hack
 
 # Force single-pass mode (override config)
-ostruct run template.j2 schema.json -fc data.csv --disable-feature ci-download-hack
+ostruct run template.j2 schema.json --file ci:data data.csv --disable-feature ci-download-hack
+
+# Handle duplicate output file names
+ostruct run template.j2 schema.json --file ci:data data.csv --ci-duplicate-outputs rename
+ostruct run template.j2 schema.json --file ci:data data.csv --ci-duplicate-outputs skip
 ```
 
 #### Option 2: Configuration File (Recommended for persistent settings)
@@ -436,6 +591,8 @@ tools:
     download_strategy: "two_pass_sentinel"  # Enables reliable file downloads
     auto_download: true
     output_directory: "./downloads"
+    duplicate_outputs: "rename"  # Handle duplicate file names: overwrite|rename|skip
+    output_validation: "basic"   # Validate downloaded files: basic|strict|off
 ```
 
 **Why this is needed**: OpenAI's structured output mode can prevent file download annotations from being generated. The two-pass strategy works around this by making two API calls: one to generate files (without structured output), then another to ensure schema compliance. For detailed technical information, see [docs/known-issues/2025-06-responses-ci-file-output.md](docs/known-issues/2025-06-responses-ci-file-output.md).
@@ -446,6 +603,8 @@ tools:
 
 🚀 **New to ostruct?** Follow our [step-by-step quickstart guide](https://ostruct.readthedocs.io/en/latest/user-guide/quickstart.html) featuring Juno the beagle for a hands-on introduction.
 
+📝 **Template Scripting:** Learn ostruct's templating capabilities with the [template scripting guide](https://ostruct.readthedocs.io/en/latest/user-guide/ostruct_template_scripting_guide.html) - no prior Jinja2 knowledge required!
+
 📖 **Full Documentation:** <https://ostruct.readthedocs.io/>
 
 ### Quick Start
@@ -555,47 +714,54 @@ Provide comprehensive analysis and actionable insights.
 }
 ```
 
-3. For more complex scenarios, use explicit file routing with flexible syntax options:
+3. Use the new attachment system for precise tool targeting:
 
 ```bash
-# Auto-naming (fastest for one-off analysis)
+# Basic multi-tool analysis
 ostruct run analysis_template.j2 analysis_schema.json \
-  -fc sales_data.csv \
-  -fc customer_data.json \
-  -fs market_reports.pdf \
-  -ft config.yaml
+  --file ci:sales sales_data.csv \
+  --file ci:customers customer_data.json \
+  --file fs:reports market_reports.pdf \
+  --file config config.yaml
 
-# Mixed syntax with custom variable names
+# Multi-tool attachment with shared data
 ostruct run analysis_template.j2 analysis_schema.json \
-  -fc sales_data.csv \
-  -fc customers customer_data.json \
-  --fsa reports market_reports.pdf \
-  --fta app_config config.yaml
+  --file ci,fs:shared_data data.json \
+  --file prompt:config settings.yaml
 
-# Alias syntax for reusable templates (best tab completion)
+# Directory-based analysis
 ostruct run reusable_analysis.j2 analysis_schema.json \
-  --fca sales_data sales_data.csv \
-  --fca customer_data customer_data.json \
-  --fsa market_reports market_reports.pdf \
-  --fta config config.yaml
+  --dir ci:sales_data ./sales \
+  --dir fs:documentation ./docs \
+  --file config ./config.yaml
 
-# Code review with stable variable names
+# Code review with multiple tool integration
 ostruct run code_review.j2 review_schema.json \
-  --fca source_code source_code/ \
-  --fsa documentation docs/ \
-  --fta eslint_config .eslintrc.json
+  --dir ci:source ./src \
+  --dir fs:docs ./documentation \
+  --file config .eslintrc.json
 ```
 
-### Example 3: Legacy Compatibility
+### Example 3: Migration from v0.8.x
 
-All existing commands continue to work unchanged:
+Legacy commands need to be updated to the new syntax:
 
 ```bash
-# Traditional usage (fully supported)
-ostruct run extract_from_file.j2 schema.json -f text input.txt -d configs
-ostruct run template.j2 schema.json -p "*.py" source -V env=prod
+# Legacy (v0.8.x) - NO LONGER SUPPORTED
+# ostruct run extract_from_file.j2 schema.json --file text input.txt -d configs
+
+# New (v0.9.0) - Updated syntax
+ostruct run extract_from_file.j2 schema.json --file text input.txt --dir configs ./configs
+
+# Legacy pattern matching - NO LONGER SUPPORTED
+# ostruct run template.j2 schema.json --dir "*.py" source --pattern "*.py" -V env=prod
+
+# New pattern matching with directory attachment
+ostruct run template.j2 schema.json --dir source ./source --pattern "*.py" -V env=prod
 ```
 
+**Migration Help:** See `MIGRATION_GUIDE.md` for automated migration scripts and detailed examples.
+
 <details>
 <summary><strong>System Prompt Handling</strong> (Click to expand)</summary>