📝 Document existing examples folder

Summary

Document the existing examples in the examples/ folder and add them to the main documentation site.

Current Examples

examples/
├── basic_rate_limiting.py      # Simple acquire/release patterns
├── hierarchical_limits.py      # Parent/child entities, cascade
├── llm_token_reconciliation.py # Post-hoc token adjustment
└── fastapi-demo/               # Full FastAPI app with LocalStack
    ├── README.md
    ├── docker-compose.yml
    ├── app/
    └── ...

Tasks

1. Add Examples to Documentation

Create docs/examples/ or docs/guide/examples.md:

• Overview page listing all examples
• Link to source code in repo
• Brief description of what each demonstrates
• Prerequisites (LocalStack for fastapi-demo)

2. Review and Update Existing Examples

• Ensure all examples work with current API
• Add inline comments explaining key concepts
• Consistent code style
• Test with latest version

3. Add to README

• "Examples" section in main README
• Quick links to key examples
• Note about fastapi-demo requiring LocalStack

4. Cross-link from Guide

• Link from docs/guide/basic-usage.md → basic_rate_limiting.py
• Link from docs/guide/hierarchical.md → hierarchical_limits.py
• Link from docs/guide/llm-integration.md → llm_token_reconciliation.py

Example Documentation Template

# Examples

## Basic Rate Limiting
[basic_rate_limiting.py](../examples/basic_rate_limiting.py)

Demonstrates:
- Creating a RateLimiter instance
- Acquiring and releasing rate limit leases
- Handling RateLimitExceeded errors

## Hierarchical Limits
[hierarchical_limits.py](../examples/hierarchical_limits.py)

Demonstrates:
- Parent/child entity relationships
- Cascade mode for hierarchical limits
- Organization → User limit patterns

## LLM Token Reconciliation
[llm_token_reconciliation.py](../examples/llm_token_reconciliation.py)

Demonstrates:
- The key differentiator: `lease.adjust()`
- Estimating tokens before LLM call
- Reconciling with actual token usage after

## FastAPI Demo App
[fastapi-demo/](../examples/fastapi-demo/)

A complete FastAPI application showing:
- Production-like deployment with LocalStack
- REST API with rate limiting middleware
- Swagger UI for exploration
- Docker Compose setup

**Requires:** Docker, LocalStack

Acceptance Criteria

• All examples documented in docs site
• Examples tested and working
• Cross-links from relevant guide pages
• README updated with examples section
• area/examples label created and applied

Related

• #163 - zae-limiter demo command (zero-friction moto-based demo)

Start by reading the existing files under examples/, the documentation structure, README, and the linked guide pages: docs/guide/basic-usage.md, hierarchical.md, and llm-integration.md. Run each example against the current API, including fastapi-demo with LocalStack, then document all examples, add the requested cross-links and README section, and verify the documentation site reflects them.