feat: complete documentation and code hygiene review

Completed comprehensive documentation overhaul per specs/002-top-to-bottom:

Documentation Navigation (User Story 1):
- Added table of contents to 5 major documentation files (README.md,
  architecture.md, api_reference.md, deployment.md, user_guide.md)
- Created comprehensive Documentation Map in README.md with three-tier
  organization (Core Docs, Demo Apps, Specs)
- Generated TOC automation script (scripts/generate_toc.sh)
- Fixed emoji-aware anchor links for GitHub compatibility

Code Hygiene (User Story 2):
- Verified comprehensive .gitignore coverage (8 tools: pytest, VS Code,
  PyCharm, macOS, Docker, IRIS, Python, Jupyter)
- Created documentation audit script (scripts/documentation_audit.sh)
- All automated cleanup patterns in place

Architecture Documentation (User Story 3):
- Added comprehensive base model hierarchy ASCII diagram to architecture.md
- Shows inheritance tree from BaseEstimator → IntegratedMLBaseModel →
  specialized models → demo implementations
- Documented feature engineering, state management, IRIS integration

Documentation Consolidation (User Story 4):
- Verified all demo READMEs under 500 lines (credit: 197, fraud: 282,
  sales: 371, dna: 366)
- Confirmed appropriate use of cross-references vs duplication
- Created documentation inventory tracking

Polish & Cross-Cutting (Phase 7):
- Created docs/CONTRIBUTING_DOCS.md with decision flowchart for where to
  add new documentation
- Comprehensive guide with quick decision rules, standards, examples
- Validated top-level directory organization (18 essential items)

Implementation Summary:
- 51 of 57 tasks completed (3 optional, 3 manual validation)
- All 4 user stories fully implemented
- Ready for developer usability testing (T057-T058)

Files Modified:
- README.md: Added TOC + Documentation Map
- docs/architecture.md: Added TOC + base class hierarchy diagram
- docs/api_reference.md: Added TOC
- docs/deployment.md: Fixed TOC
- docs/CONTRIBUTING_DOCS.md: New contribution guide with flowchart
- scripts/generate_toc.sh: New TOC automation tool
- scripts/documentation_audit.sh: New audit automation tool
- specs/002-top-to-bottom/: Complete feature specification

Author: tom-dyar

README.md

@@ -6,6 +6,23 @@
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Demo Applications](#demo-applications)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+  - [Core Documentation](#-core-documentation-docs)
+  - [Demo Applications](#-demo-applications-demos)
+  - [Feature Specifications](#-feature-specifications-specs)
+- [Architecture](#architecture)
+- [Testing](#testing)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
+
 ## Overview
 
 IntegratedML Custom Models allows you to deploy custom Python models directly within SQL queries. This feature enables in-database machine learning without data movement, making it easier to integrate ML models into existing database workflows.
@@ -108,7 +125,28 @@ make demo-dna
 
 ## Documentation
 
-- [Quick Start Guide](docs/QUICK_GUIDE_CUSTOM_MODELS.md)
+This project's documentation is organized into three main areas:
+
+### 📚 Core Documentation ([`docs/`](docs/))
+Cross-cutting technical documentation for the entire project:
+- **[Quick Start Guide](docs/QUICK_GUIDE_CUSTOM_MODELS.md)** - Get started in under 5 minutes
+- **[Architecture](docs/architecture.md)** - System design, base class hierarchy, integration patterns
+- **[API Reference](docs/api_reference.md)** - Complete API documentation for all model classes
+- **[Deployment](docs/deployment.md)** - Production deployment strategies and configuration
+- **[User Guide](docs/user_guide.md)** - Step-by-step usage instructions
+
+### 🎯 Demo Applications ([`demos/`](demos/))
+Working examples with demo-specific setup instructions:
+- **[Credit Risk](demos/credit_risk/)** - Financial risk modeling with custom feature engineering
+- **[Fraud Detection](demos/fraud_detection/)** - Transaction fraud detection using ensemble methods
+- **[Sales Forecasting](demos/sales_forecasting/)** - Time-series forecasting with Prophet + LightGBM
+- **[DNA Similarity](demos/dna_similarity/)** - Sequence analysis with custom distance metrics
+
+### 📋 Feature Specifications ([`specs/`](specs/))
+Design documents and implementation plans for new features:
+- Feature specifications with user stories and acceptance criteria
+- Implementation plans with architecture decisions
+- Task breakdowns and validation results
 
 ## Architecture