### Install Pre-commit Hooks and Serve Documentation

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/developer/index.html

Install pre-commit hooks for automated checks before commits and start the documentation development server using MkDocs.

```bash
# Install pre-commit hooks
pre-commit install
# Start development server (for documentation)
mkdocs serve
```

--------------------------------

### Development Session Setup

Source: https://github.com/fulvian/exc-to-pdf/blob/main/CLAUDE.md

Steps to prepare for a development session by navigating to the project directory, setting the multi-project mode environment variable, and starting DevStream. This ensures the development environment is correctly configured.

```bash
# 1. Navigate to project directory
cd /Users/fulvioventura/exc-to-pdf

# 2. Set multi-project mode
export DEVSTREAM_PROJECT_ROOT="/Users/fulvioventura/exc-to-pdf"

# 3. Start DevStream
./path/to/devstream/start-devstream.sh start

# 4. Work on project using project-specific tools
# DevStream provides memory, context, and agent capabilities
```

--------------------------------

### Install exc-to-pdf from Source

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/index.md

Install exc-to-pdf by cloning the repository and installing from source. This is useful for development or if you need the latest unreleased features.

```bash
git clone https://github.com/exc-to-pdf/exc-to-pdf.git
cd exc-to-pdf
pip install -e .
```

--------------------------------

### Development Installation of exc-to-pdf

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/index.md

Set up a development environment for exc-to-pdf, including installing development dependencies.

```bash
git clone https://github.com/exc-to-pdf/exc-to-pdf.git
cd exc-to-pdf
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

--------------------------------

### Install and Use exc-to-pdf in Virtual Environment

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Install the library within an activated virtual environment and verify the installation. Includes command to deactivate the environment.

```bash
# Install exc-to-pdf
pip install exc-to-pdf

# Verify installation
exc-to-pdf --version

# Deactivate when done
deactivate
```

--------------------------------

### Verify exc-to-pdf installation

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/index.md

Verify the installation by checking the installed version. This command should display the version number.

```bash
exc-to-pdf --version
```

--------------------------------

### Install exc-to-pdf from PyPI

Source: https://github.com/fulvian/exc-to-pdf/blob/main/README.md

Install the exc-to-pdf package using pip. This is the recommended installation method.

```bash
pip install exc-to-pdf
```

--------------------------------

### Install exc-to-pdf from Source

Source: https://github.com/fulvian/exc-to-pdf/blob/main/README.md

Install the exc-to-pdf package from its source code. This involves cloning the repository, setting up a virtual environment, and installing in development mode.

```bash
# Clone the repository
git clone https://github.com/fulvian/exc-to-pdf.git
cd exc-to-pdf

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .
```

--------------------------------

### Install exc-to-pdf from Source

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Install the library directly from the source code without including development dependencies.

```bash
# Clone the repository
git clone https://github.com/exc-to-pdf/exc-to-pdf.git
cd exc-to-pdf

# Install package
pip install .

# Verify installation
exc-to-pdf --version
```

--------------------------------

### Install exc-to-pdf using a Virtual Environment

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Creates and activates a virtual environment for installing exc-to-pdf, isolating dependencies. This is a recommended practice.

```bash
python -m venv .venv
source .venv/bin/activate
pip install exc-to-pdf
```

--------------------------------

### Install Build Tools on Ubuntu/Debian

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/quick-start/installation/index.html

Before installing exc-to-pdf, ensure you have the necessary build tools installed on Ubuntu or Debian-based systems.

```bash
sudo apt install build-essential python3-dev
```

--------------------------------

### Install exc-to-pdf from Local Wheels

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Installs exc-to-pdf using locally downloaded wheel files. This method is efficient for offline installations when dependencies are not needed in the download.

```bash
pip install exc-to-pdf --no-index --find-links ./wheels
```

--------------------------------

### Configuration File Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/user-guide/cli-reference/index.html

Example TOML configuration file demonstrating settings for template, orientation, margins, and features.

```toml
[page]
template = "modern"
orientation = "landscape"
margin_top = 80
margin_bottom = 80

[features]
include_bookmarks = true
include_metadata = true
```

--------------------------------

### Handle ConfigurationException Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/api/exceptions.md

Example demonstrating how to catch and handle ConfigurationException, accessing its message and context.

```python
from exc_to_pdf.config import PDFConfig
from exc_to_pdf.exceptions import ConfigurationException

try:
    config = PDFConfig()
    config.margin_top = -10  # Invalid negative margin
    generator = PDFGenerator(config)
except ConfigurationException as e:
    print(f"Configuration error: {e.message}")
    if e.context:
        print(f"Invalid setting: {e.context.get('setting', 'unknown')}")
```

--------------------------------

### Full Conversion Example with All Options

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/user-guide/cli-reference.md

Demonstrates a comprehensive conversion command with multiple configuration options specified directly on the command line.

```bash
exc-to-pdf convert \
  financial-report.xlsx \
  financial-report.pdf \
  --config company-config.toml \
  --template modern \
  --orientation landscape \
  --sheet "Q4 Results" \
  --margin-top 60 \
  --margin-bottom 60 \
  --margin-left 50 \
  --margin-right 50 \
  --verbose
```

--------------------------------

### Install exc-to-pdf in User Directory

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Installs exc-to-pdf with user-specific permissions, avoiding system-wide conflicts. Recommended when facing permission errors.

```bash
pip install --user exc-to-pdf
```

--------------------------------

### Context7 Tool: Resolve Library and Get Docs

Source: https://github.com/fulvian/exc-to-pdf/blob/main/templates/implementation-plan-glm46.md

Example of using Context7 tools to resolve a library ID and retrieve its documentation when an unknown library or pattern is encountered.

```python
# Step 1: Resolve
library_id = mcp__context7__resolve-library-id(libraryName="{{library}}")
# Step 2: Get docs
docs = mcp__context7__get-library-docs(
    context7CompatibleLibraryID=library_id,
    topic="{{specific_topic}}",
    tokens=3000
)
```

--------------------------------

### Clone Repository and Setup Environment

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/developer/index.md

Clone the repository and set up a Python virtual environment for development.

```bash
git clone https://github.com/exc-to-pdf/exc-to-pdf.git
cd exc-to-pdf
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

--------------------------------

### Install Build Tools on macOS

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/quick-start/installation/index.html

On macOS, install the Xcode command-line tools to resolve build failures during installation.

```bash
xcode-select --install
```

--------------------------------

### Check exc-to-pdf Basic Commands

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Verify the installation by checking the command-line interface version and help output.

```bash
# Check version
exc-to-pdf --version

# Show help
exc-to-pdf --help
```

--------------------------------

### Install exc-to-pdf from Local Packages

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Installs exc-to-pdf using locally downloaded packages without an internet connection. Requires packages to be downloaded first.

```bash
pip install exc-to-pdf --no-index --find-links ./packages
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/developer/index.md

Install the project's development dependencies using pip.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Project Environment File Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/CLAUDE.md

An example of a project environment file (.env.project) that is automatically managed by DevStream. It contains essential paths and configuration variables for the project and framework.

```bash
# This file is automatically generated/updated by DevStream
# Do NOT edit manually - use DevStream configuration system

DEVSTREAM_PROJECT_ENV=development
DEVSTREAM_PROJECT_ROOT=/Users/fulvioventura/exc-to-pdf
DEVSTREAM_PROJECT_NAME=exc-to-pdf
DEVSTREAM_PROJECT_TYPE=generic

# Framework paths (for reference)
DEVSTREAM_FRAMEWORK_PATH=/Users/fulvioventura/devstream
DEVSTREAM_FRAMEWORK_VENV_PATH=/Users/fulvioventura/devstream/.devstream

# Project-specific paths
{% if project.type == 'python' %}
PYTHONPATH=/Users/fulvioventura/exc-to-pdf/src:/Users/fulvioventura/exc-to-pdf
{% endif %}
```

--------------------------------

### Setup First TodoWrite Task

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/development/plan/handoff-prompt-glm46-p2.md

Initializes the first task in the TodoWrite system, marking it as 'in_progress'. This is part of the initial setup for a new task.

```python
TodoWrite([
    {"content": "P2.1 Create ExcelReader core class structure", "status": "in_progress", "activeForm": "Creating ExcelReader core class structure"},
    # ... other tasks
])
```

--------------------------------

### Download Packages for Offline Installation

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Downloads the exc-to-pdf package and its dependencies to a local directory. Use this to prepare for offline installation.

```bash
pip download exc-to-pdf -d ./packages
```

--------------------------------

### Error Output Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/user-guide/cli-reference.md

Shows an example of an error message when a file is not found, including helpful suggestions.

```bash
$ exc-to-pdf convert missing.xlsx output.pdf
❌ Error: File not found: missing.xlsx

💡 Suggestions:
   • Check if the file exists and is readable
   • Ensure the file is a valid Excel file (.xlsx, .xls)
   • Try using the absolute file path
```

--------------------------------

### Get help

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/user-guide/cli-reference.md

Displays help messages for the CLI. This is a global option.

```bash
exc-to-pdf --help
```

```bash
exc-to-pdf convert --help
```

--------------------------------

### Download Wheel Files for Offline Installation

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Downloads only the wheel files for exc-to-pdf, excluding dependencies. Useful for installing on systems where dependencies are already met or managed separately.

```bash
pip download --no-deps exc-to-pdf -d ./wheels
```

--------------------------------

### API Documentation Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/developer/index.md

Shows an example of a Python class with a docstring intended for API documentation generation. It includes class-level documentation and attribute descriptions.

```python
from typing import Dict, Any

class PDFGenerator:
    """Main PDF generation engine.

    This class provides the primary interface for converting Excel files
    to PDF format with AI optimization features.

    Attributes:
        config: PDF configuration object
        table_renderer: Table rendering component
        bookmark_manager: Bookmark management component
    """
```

--------------------------------

### Verify Installation and Code Quality

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/developer/index.md

Run tests, check code style with black, and perform type checking with mypy.

```bash
# Run tests
pytest

# Check code style
black --check src tests

# Type checking
mypy src
```

--------------------------------

### Attribution Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/about/license.md

While not strictly required by the MIT license, this is an example of how to provide attribution when using exc-to-pdf in your projects. It includes the project name, URL, copyright year, and copyright holder.

```text
This project uses exc-to-pdf (https://github.com/exc-to-pdf/exc-to-pdf)
Copyright (c) 2025 exc-to-pdf Team
```

--------------------------------

### Generic Project Layout Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/CLAUDE.md

Illustrates a typical directory structure for a generic project, including source code, tests, documentation, configuration files, and project-specific files.

```text
exc-to-pdf/
├── src/                    # Source code (if applicable)
├── tests/                  # Test files (if applicable)
├── docs/                   # Documentation (if applicable)
├── .env.project           # Project configuration (auto-generated)
├── CLAUDE.md              # This file (project-specific rules)
├── README.md              # Project documentation
└── [Project-specific files]  # Depends on project type
```

--------------------------------

### Verbose Output Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/user-guide/cli-reference.md

Demonstrates the detailed progress information provided by the --verbose flag during file conversion.

```bash
$ exc-to-pdf --verbose convert data.xlsx output.pdf
🔧 Initializing PDF generator...
📄 Converting: data.xlsx
📄 Output:    output.pdf
🎨 Template:  modern
📐 Orientation: portrait
📋 Found 3 worksheets:
  1. Sheet1
  2. Sales Data
  3. Summary
🔄 Processing worksheet: Sheet1
📊 Detected 1 table (15 rows × 8 columns)
📄 Rendering table to PDF...
🔄 Processing worksheet: Sales Data
📊 Detected 1 table (245 rows × 12 columns)
📄 Rendering table to PDF...
🔄 Processing worksheet: Summary
📊 Detected 2 tables (12 rows × 6 columns, 8 rows × 4 columns)
📄 Rendering tables to PDF...
📑 Creating bookmarks...
🏷️  Adding metadata for AI optimization...
✅ Conversion completed successfully!
📊 Output size: 4.67 MB
📈 Processing time: 3.2 seconds
```

--------------------------------

### Handle PDFGenerationException Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/api/exceptions.md

Example showing how to catch PDFGenerationException and access details like the output file path.

```python
from exc_to_pdf.exceptions import PDFGenerationException

try:
    generator.convert_excel_to_pdf("large_file.xlsx", "/protected/output.pdf")
except PDFGenerationException as e:
    print(f"PDF generation failed: {e.message}")
    if e.file_path:
        print(f"Output file: {e.file_path}")
```

--------------------------------

### Wide Data Table Conversion Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/basic-usage.md

Example command for converting a wide data table, likely using landscape orientation.

```bash
# Convert a wide data table
exc-to-pdf convert wide-data.xlsx wide-report.pdf --orientation landscape
```

--------------------------------

### Check All Dependencies

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/quick-start/installation/index.html

A Python script to verify if all required packages for exc-to-pdf are installed. It lists missing packages and exits with an error if any are not found.

```python
import sys
required_packages = ['openpyxl', 'pandas', 'reportlab', 'Pillow', 'click', 'structlog']
missing = []

for package in required_packages:
    try:
        __import__(package)
        print(f'✅ {package}')
    except ImportError:
        missing.append(package)
        print(f'❌ {package}')

if missing:
    print(f'\n❌ Missing packages: {missing}')
    sys.exit(1)
else:
    print('\n✅ All dependencies satisfied!')
```

--------------------------------

### Install Build Tools for Compilation

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Installs necessary build tools and Python development headers for compiling packages. Required on systems like Ubuntu/Debian or macOS when encountering build failures.

```bash
# On Ubuntu/Debian
sudo apt install build-essential python3-dev

# On macOS
xcode-select --install
```

--------------------------------

### Real-World Example: Financial Reports

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/index.md

Convert a financial report to PDF using the modern template, landscape orientation, and custom margins.

```bash
exc-to-pdf convert financial-report.xlsx report.pdf \
  --template modern \
  --orientation landscape \
  --margin-top 60 \
  --margin-bottom 60
```

--------------------------------

### Financial Report Conversion Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/basic-usage.md

Example of converting a financial report with professional styling, specific orientation, custom margins, and verbose output enabled.

```bash
# Convert financial report with professional styling
exc-to-pdf convert financial-report.xlsx report.pdf \
  --template modern \
  --orientation portrait \
  --margin-top 80 \
  --margin-bottom 80 \
  --verbose
```

--------------------------------

### ReportLab AI Optimization Metadata Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/development/plan/handoff_p3-pdf-generation-engine-to-glm46.md

Provides an example of metadata dictionary for AI optimization in PDFs, suitable for NotebookLM compatibility. Include relevant details like title, author, subject, and keywords.

```python
# AI optimization metadata
metadata = {
    'title': 'Excel Data Analysis',
    'author': 'exc-to-pdf converter',
    'subject': 'Structured data for AI analysis',
    'keywords': 'excel,table,data,analysis,notebooklm',
    'creator': 'exc-to-pdf v2.2.0'
}
```

--------------------------------

### Verify Environment and Dependencies

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/development/plan/handoff_p3-pdf-generation-engine-to-glm46.md

Check the Python version and installed packages, ensuring reportlab, pandas, and openpyxl are present.

```bash
# Verify venv and Python version
.devstream/bin/python --version  # Must be 3.11.x
.devstream/bin/python -m pip list | grep -E "(reportlab|pandas|openpyxl)"
```

--------------------------------

### Process Large Datasets with Progress Monitoring

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/quick-start/examples/index.html

Convert a large Excel dataset to PDF with progress monitoring. This example uses a modern template and landscape orientation, with verbose output enabled.

```bash
exc-to-pdf convert Large-Dataset.xlsx Dataset-Analysis.pdf \
  --template modern \
  --orientation landscape \
  --verbose
```

--------------------------------

### Check exc-to-pdf Dependencies in Python

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Execute a Python script to verify that all core dependencies required by exc-to-pdf are installed and accessible.

```python
# Check all dependencies
python -c "
import sys
required_packages = ['openpyxl', 'pandas', 'reportlab', 'Pillow', 'click', 'structlog']
missing = []

for package in required_packages:
    try:
        __import__(package)
        print(f'✅ {package}')
    except ImportError:
        missing.append(package)
        print(f'❌ {package}')

if missing:
    print(f'\n❌ Missing packages: {missing}')
    sys.exit(1)
else:
    print('\n✅ All dependencies satisfied!')
"
```

--------------------------------

### Build and Check Package Locally

Source: https://github.com/fulvian/exc-to-pdf/blob/main/DEPLOYMENT_GUIDE.md

Commands to build the Python package and check its quality using twine. Ensure you have the 'build' and 'twine' packages installed.

```bash
# Build package
python -m build

# Check package quality
twine check dist/*

# Test install locally
pip install dist/exc_to_pdf-1.0.0-py3-none-any.whl
```

--------------------------------

### Subagent Delegation Example

Source: https://github.com/fulvian/exc-to-pdf/blob/main/templates/implementation-plan-sonnet45.md

Use this format to delegate tasks to specialized subagents. Replace placeholders with specific component and aspect details.

```shell
@python-specialist Implement the {{specific_component}} according to the architecture specified in the plan. Focus on {{specific_aspects}}.
```

--------------------------------

### Resolve Library ID and Get Docs Tool Usage

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/development/plan/implementation-plan-glm46-p2.md

Example of using context7 tools to resolve a library ID and retrieve its documentation for unknown libraries.

```python
# Step 1: Resolve
library_id = mcp__context7__resolve-library-id(libraryName="openpyxl")
# Step 2: Get docs
docs = mcp__context7__get-library-docs(
    context7CompatibleLibraryID=library_id,
    topic="worksheet access sheet names iteration",
    tokens=3000
)

```

--------------------------------

### Monitor Memory Usage

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/user-guide/index.html

Command-line examples for monitoring memory usage during conversion. Includes a verbose option and a memory-saving template option.

```bash
# Monitor memory usage on large files
exc-to-pdf convert large.xlsx output.pdf --verbose
```

```bash
# Use minimal template for lower memory usage
exc-to-pdf convert large.xlsx output.pdf --template minimal --no-bookmarks
```

--------------------------------

### Batch Conversion using find Command

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/user-guide/cli-reference.md

Examples of using the 'find' command to locate and convert Excel files, including options for sequential and parallel processing.

```bash
# Convert all Excel files recursively
find . -name "*.xlsx" -type f -exec exc-to-pdf convert {} {}.pdf \;

# Convert with parallel processing (requires GNU parallel)
find . -name "*.xlsx" | parallel -j 4 exc-to-pdf convert {} {.}.pdf
```

--------------------------------

### ExcelReader class structure and initialization

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/development/plan/implementation-plan-glm46-p2.md

Defines the core ExcelReader class with initialization, docstring, type hints, and an example of its usage. This is the starting point for Excel file processing.

```python
class ExcelReader:
    """
    Excel file processing engine with hybrid table detection and multi-sheet support.

    Provides comprehensive Excel file analysis capabilities including sheet discovery,
    table detection, and data extraction optimized for PDF generation.

    Attributes:
        file_path: Path to the Excel file
        config: Configuration object for processing options
        workbook: OpenPyXL workbook instance
        _is_read_only: Flag indicating read-only mode usage
    """

    def __init__(
        self,
        file_path: str,
        config: Optional["ExcelConfig"] = None
    ) -> None:
        """
        Initialize ExcelReader with file path and optional configuration.

        Args:
            file_path: Path to the Excel file (.xlsx format)
            config: Optional configuration object for processing settings

        Raises:
            FileNotFoundError: If the specified file does not exist
            InvalidFileException: If the file is not a valid Excel file

        Example:
            >>> reader = ExcelReader("data.xlsx")
            >>> sheets = reader.discover_sheets()
        """

```

--------------------------------

### Set Up and Activate Virtual Environment

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/developer/index.html

Create a Python virtual environment and activate it. The activation command differs between operating systems.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

--------------------------------

### Install Python on macOS

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/quick-start/installation/index.html

Use Homebrew to install Python version 3.11, or download it directly from python.org.

```bash
brew install python@3.11
```

--------------------------------

### Install Python on Linux

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Install Python 3.11 and its associated pip and venv modules on Ubuntu/Debian systems.

```bash
sudo apt update
sudo apt install python3.11 python3.11-pip python3.11-venv
```

--------------------------------

### Using a Configuration File with CLI

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/user-guide/index.md

Apply a TOML configuration file to the exc-to-pdf conversion process via the command line.

```bash
# Use configuration file
exc-to-pdf convert input.xlsx output.pdf --config company-config.toml
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/developer/index.html

Clone the project repository and change the directory to the project root.

```bash
git clone https://github.com/exc-to-pdf/exc-to-pdf.git
cd exc-to-pdf
```

--------------------------------

### Ensure pip is Installed and Upgraded

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Installs and upgrades pip to the latest version. This is a prerequisite for many Python package management tasks.

```bash
python -m ensurepip --upgrade
python -m pip install --upgrade pip
```

--------------------------------

### Read Implementation Plan

Source: https://github.com/fulvian/exc-to-pdf/blob/main/templates/handoff-prompt-glm46.md

Use this command to read the detailed implementation plan provided by the previous agent.

```bash
cat {{plan_file_path}}
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Set up a dedicated virtual environment for the project to manage dependencies and avoid conflicts. Includes activation commands for Windows and macOS/Linux.

```bash
# Create virtual environment
python -m venv exc-to-pdf-env

# Activate environment
# On Windows
exc-to-pdf-env\Scripts\activate

# On macOS/Linux
source exc-to-pdf-env/bin/activate
```

--------------------------------

### Use Configuration File

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/user-guide/cli-reference/index.html

Specify a configuration file using the --config option to customize conversion settings.

```bash
exc-to-pdf convert data.xlsx output.pdf --config my-config.toml
```

--------------------------------

### Basic CLI Command Structure

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/user-guide/cli-reference/index.html

Illustrates the general syntax for invoking the exc-to-pdf CLI. It shows the placement of global options, commands, command-specific options, and arguments.

```bash
exc-to-pdf [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGUMENTS]
```

--------------------------------

### Resolve Library ID and Get Documentation

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/development/plan/implementation-plan-glm46-p2/index.html

Demonstrates a two-step process using DevStream tools to get documentation for a library. First, resolve the library ID using `resolve-library-id`, then fetch documentation using `get-library-docs`.

```python
# Step 1: Resolve
library_id = mcp__context7__resolve-library-id(libraryName="openpyxl")
# Step 2: Get docs
docs = mcp__context7__get-library-docs(
    context7CompatibleLibraryID=library_id,
    topic="worksheet access sheet names iteration",
    tokens=3000
)
```

--------------------------------

### Read Implementation Plan

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/development/plan/handoff_p3-pdf-generation-engine-to-glm46.md

Use the 'cat' command to read the detailed implementation plan for the PDF generation engine.

```bash
cat /Users/fulvioventura/exc-to-pdf/docs/development/plan/piano_p3-pdf-generation-engine.md
```

--------------------------------

### Go Project Commands

Source: https://github.com/fulvian/exc-to-pdf/blob/main/CLAUDE.md

Essential commands for building, testing, running, formatting, and vetting Go projects. Uses the standard Go toolchain.

```bash
# Build
go build ./...

# Run tests
go test ./...

# Development
go run main.go

# Format
go fmt ./...

# Vet
go vet ./...
```

--------------------------------

### Iterating Through Worksheets in OpenPyXL

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/development/plan/implementation-plan-glm46-p2.md

Shows how to get all worksheet names and iterate through each worksheet in an openpyxl workbook.

```python
# Get all worksheet names
sheet_names = wb.sheetnames

# Iterate through worksheets
for sheet in wb:
    print(sheet.title)

# Access worksheet by name
ws = wb["Sheet1"]
```

--------------------------------

### Verify exc-to-pdf command-line help

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/index.md

Display the help message for the exc-to-pdf command-line tool to confirm it's accessible and to see available commands.

```bash
exc-to-pdf --help
```

--------------------------------

### Handle InvalidFileException in Python

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/api/exceptions/index.html

Example demonstrating how to catch an InvalidFileException, printing the error message and file path.

```python
from exc_to_pdf.exceptions import InvalidFileException

try:
    generator.convert_excel_to_pdf("nonexistent.xlsx", "output.pdf")
except InvalidFileException as e:
    print(f"File error: {e.message}")
    print(f"File path: {e.file_path}")
```

--------------------------------

### Update exc-to-pdf via pip

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Command to update the exc-to-pdf library to the latest version when installed via pip.

```bash
pip install --upgrade exc-to-pdf
```

--------------------------------

### Check Python Version

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/quick-start/installation.md

Verify your Python installation. Ensure it meets the minimum requirement of Python 3.9 or higher.

```bash
# Check Python version
python --version

# Should show 3.9 or higher
Python 3.11.5
```

--------------------------------

### Completion Commands for Bookmark Manager

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/development/plan/piano_p3-pdf-generation-engine.md

Commands to run after implementing the BookmarkManager. Includes running unit tests and static type checking.

```bash
# Run after implementation
.devstream/bin/python -m pytest tests/unit/test_bookmark_manager.py -v
.devstream/bin/python -m mypy src/bookmark_manager.py --strict
```

--------------------------------

### Handle ExcelReaderError in Python

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/api/exceptions/index.html

Example of how to catch and process the base ExcelReaderError, accessing its message, file path, and context.

```python
from exc_to_pdf.exceptions import ExcelReaderError

try:
    # Some operation that might fail
    pass
except ExcelReaderError as e:
    print(f"Error: {e.message}")
    if e.file_path:
        print(f"File: {e.file_path}")
    if e.context:
        print(f"Context: {e.context}")
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/developer/index.md

Commands for setting up pre-commit hooks, serving documentation, and running tests in watch mode.

```bash
# Install pre-commit hooks
pre-commit install

# Start development server (for documentation)
mkdocs serve

# Run tests in watch mode
pytest --watch
```

--------------------------------

### Create PDF Generator with Custom Configuration

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/api/index.md

Demonstrates how to create a PDFGenerator instance with custom configuration settings for business reports, such as table style, orientation, margins, and metadata inclusion.

```python
from exc_to_pdf import PDFGenerator
from exc_to_pdf.config import PDFConfig

def create_business_report_generator():
    """Create generator optimized for business reports"""
    config = PDFConfig()
    config.table_style = "modern"
    config.orientation = "portrait"
    config.margin_top = 80
    config.margin_bottom = 80
    config.include_bookmarks = True
    config.include_metadata = True

    return PDFGenerator(config)

# Usage
generator = create_business_report_generator()
generator.convert_excel_to_pdf("report.xlsx", "output.pdf")
```

--------------------------------

### Search Memory Tool Usage

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/development/plan/implementation-plan-glm46-p2.md

Example of using the devstream_search_memory tool to find existing code patterns before implementation.

```python
mcp__devstream__devstream_search_memory(
    query="openpyxl worksheet iteration sheet names",
    content_type="code",
    limit=5
)

```

--------------------------------

### Verify Python Environment and Dependencies

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/development/plan/handoff-prompt-glm46-p2/index.html

Check the Python version and ensure required libraries (openpyxl, pandas, pytest) are installed.

```bash
.devstream/bin/python --version  # Must be 3.11.x
.devstream/bin/python -m pip list | grep -E "(openpyxl|pandas|pytest)"
```

--------------------------------

### Troubleshooting: File Not Found Error

Source: https://github.com/fulvian/exc-to-pdf/blob/main/docs/user-guide/cli-reference.md

Demonstrates a 'File not found' error and provides command-line solutions including checking file existence, using absolute paths, and verifying the current directory.

```bash
$ exc-to-pdf convert non-existent.xlsx output.pdf
❌ Error: File not found: non-existent.xlsx

# Solutions:
# 1. Check file exists
ls -la non-existent.xlsx

# 2. Use absolute path
exc-to-pdf convert /full/path/to/file.xlsx output.pdf

# 3. Check current directory
pwd
ls -la *.xlsx
```

--------------------------------

### Test exc-to-pdf Conversion

Source: https://github.com/fulvian/exc-to-pdf/blob/main/site/quick-start/installation/index.html

Create a simple CSV file and test the conversion process. This involves creating a test file and then converting it.

```bash
echo "Test,Data
1,2
3,4" > test.csv
```