Security doc (#176)

* updated proxy user explanation

* re-structured doc

* updated docker doc

* added OpenWebui and prod deployment guide

* updated architecture and readme

* added architecture diagrams

* Added Code examples to quickstart

Author: remi-td

README.md

@@ -19,7 +19,7 @@ We are providing groupings of tools and associated helpful prompts to support al
   - [Base Tools](https://github.com/Teradata/teradata-mcp-server/blob/main/src/teradata_mcp_server/tools/base/README.md)
 - **Table** tools, to efficiently and predictably access structured data models:
   - [Feature Store Tools](https://github.com/Teradata/teradata-mcp-server/blob/main/src/teradata_mcp_server/tools/fs/README.md) to access and manage the Teradata Enterprise Feature Store.
-  - [Semantic layer definitions](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/CUSTOMIZING.md) to easily implement domain-specific tools, prompts and resources for your own business data models. 
+  - [Semantic layer definitions](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/server_guide/CUSTOMIZING.md) to easily implement domain-specific tools, prompts and resources for your own business data models. 
 - **Data Quality** tools, prompts and resources accelerate exploratory data analysis:
   - [Data Quality Tools](https://github.com/Teradata/teradata-mcp-server/blob/main/src/teradata_mcp_server/tools/qlty/README.md)
 - **DBA** tools, prompts and resources to facilitate your platform administration tasks:
@@ -57,7 +57,7 @@ Configure the claude_desktop_config.json (Settings>Developer>Edit Config) by add
 
 **Step 1.** - Identify the running Teradata System, you need username, password and host details. If you do not have a Teradata system to connect to, then leverage [Teradata Clearscape Experience](https://www.teradata.com/getting-started/demos/clearscape-analytics)
 
-**Step 2.** - To install, configure and run the MCP server, refer to the [Getting started guide](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/GETTING_STARTED.md), or see below for a quick [CLI installation](#CLI-Installation). You can easily [customize the server with your own tools, prompts and resources](docs/CUSTOMIZING.md).
+**Step 2.** - To install, configure and run the MCP server, refer to the [Getting started guide](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/server_guide/GETTING_STARTED.md), or see below for a quick [CLI installation](#CLI-Installation). You can easily [customize the server with your own tools, prompts and resources](docs/server_guide/CUSTOMIZING.md).
 
 **Step 3.** - There are many client options available, the [Client Guide](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/client_guide/CLIENT_GUIDE.md) explains how to configure and run a sample of different clients.
 
@@ -132,7 +132,7 @@ For Claude Desktop with development build, use this configuration:
 ```
 
 ## Contributing
-Please refer to the [Contributing](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/CONTRIBUTING.md) guide and the [Developer Guide](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/developer_guide/DEVELOPER_GUIDE.md).
+Please refer to the [Contributing](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/developer_guide/CONTRIBUTING.md) guide and the [Developer Guide](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/developer_guide/DEVELOPER_GUIDE.md).
 
 
 ---------------------------------------------------------------------

docs/CHANGE_LOG.md

@@ -0,0 +1,75 @@
+# Teradata MCP Server Documentation
+
+This guide will help you get started, configure, and customize your Teradata MCP Server setup.
+
+## 🚀 Quick Start
+
+New to Teradata MCP Server? Choose your 5-minute quickstart to rapidly evaluate the server with your favorite tool:
+
+| **Client** | **Deployment** | **Communication** | **Best For** |
+|------------|----------------|------------------|--------------|
+| [Claude Desktop](server_guide/QUICK_START.md) | CLI (uv/pipx) | stdio | Exploratory Data Analytics, Platform Administration, general evaluation |
+| [VS Code + Copilot](server_guide/QUICK_START_VSCODE.md) | CLI (uv/pipx) | HTTP | Data Engineering, Agentic app development |
+| [Open WebUI](server_guide/QUICK_START_OPEN_WEBUI.md) | Docker | REST | Local AI, evaluate new LLMs |
+| [Code examples](examples/README.md) | Python | HTTP | Build your own client. Example library using ADK, Bedrock, Langchain... |
+
+**Other Options:**
+- **[Getting Started Guide](server_guide/GETTING_STARTED.md)** - Detailed path selection and role-based recommendations
+- **[Video Library](server_guide/VIDEO_LIBRARY.md)** - Watch step-by-step tutorials
+
+## 📖 Documentation Sections
+
+### 🛠 Server Guide
+Everything you need to know about running and configuring the MCP server:
+
+- **[Getting Started](server_guide/GETTING_STARTED.md)** - Choose your path (routing guide)
+- **[Quick Start (Claude)](server_guide/QUICK_START.md)** - 5-minute Claude Desktop setup using `stdio` transport mode
+- **[Quick Start (VS Code + Copilot)](server_guide/QUICK_START_VSCODE.md)** - 5-minute VS Code and GitHub Copilot setup using `streamable-http` transport mode
+- **[Quick Start (Open WebUI)](server_guide/QUICK_START_OPEN_WEBUI.md)** - 5-minute Open WebUI setup using REST interface
+- **[Installation](server_guide/INSTALLATION.md)** - Deployment methods and options
+- **[Configuration](server_guide/CONFIGURATION.md)** - Server settings and tuning
+- **[Architecture](server_guide/ARCHITECTURE.md)** - How components work together
+- **[Customizing](server_guide/CUSTOMIZING.md)** - Add your own tools and business logic
+- **[Security](server_guide/SECURITY.md)** - Authentication and access control
+
+### 👥 Client Guide
+Connect different AI clients to your Teradata MCP Server:
+
+- **[Client Overview](client_guide/CLIENT_GUIDE.md)** - Supported clients and general setup
+- **[Claude Desktop](client_guide/Claude_desktop.md)** - Desktop AI assistant
+- **[Visual Studio Code](client_guide/Visual_Studio_Code.md)** - IDE integration
+- **[Google Gemini CLI](client_guide/Google_Gemini_CLI.md)** - Command-line interface
+- **[Microsoft Copilot](client_guide/Microsoft_copilot.md)** - Enterprise integration
+- **[Open WebUI](client_guide/Open_WebUI.md)** - Web-based interface
+- **[REST API](client_guide/Rest_API.md)** - HTTP/API integration
+- **[MCP Inspector](client_guide/MCP_Inspector.md)** - Debugging and testing tool
+
+### 🔧 Developer Guide
+Extend and contribute to the Teradata MCP Server:
+
+- **[Developer Guide](developer_guide/DEVELOPER_GUIDE.md)** - Architecture and development setup
+- **[Contributing](developer_guide/CONTRIBUTING.md)** - How to contribute code
+- **[Adding Functions](developer_guide/HOW_TO_ADD_YOUR_FUNCTION.md)** - Create custom tools
+- **[Prompt Guidelines](developer_guide/PROMPT_DEFINITION_GUIDELINES.md)** - Best practices for prompts
+
+## 🎯 Common Use Cases
+
+### For Data Engineers & Analysts
+- **Quick Setup**: [5-Minute Quick Start](server_guide/QUICK_START.md) → [Claude Desktop](client_guide/Claude_desktop.md)
+- **Custom Business Logic**: [Customizing Guide](server_guide/CUSTOMIZING.md)
+- **Security Setup**: [Security Configuration](server_guide/SECURITY.md)
+
+### For Developers & DevOps
+- **API Integration**: [REST API Guide](client_guide/Rest_API.md)
+- **Custom Tools**: [Adding Functions](developer_guide/HOW_TO_ADD_YOUR_FUNCTION.md)
+- **Contributing**: [Developer Guide](developer_guide/DEVELOPER_GUIDE.md)
+
+### for IT Administrators
+- **Enterprise Deployment**: [Security Guide](server_guide/SECURITY.md)
+- **Client Management**: [Client Guide](client_guide/CLIENT_GUIDE.md)
+
+## 🆘 Need Help?
+
+- 📹 **Visual Learner?** Check our [Video Library](server_guide/VIDEO_LIBRARY.md)
+- 🤝 **Want to contribute?** See our [Contributing Guide](developer_guide/CONTRIBUTING.md)
+- 💡 **Have Ideas or identified a bug?** Open an issue on GitHub

docs/README.md

@@ -0,0 +1,71 @@
+# Documentation Strategy for Teradata MCP Server
+
+## 🎯 Documentation Overview 
+
+The documentation follows a **progressive disclosure design** with clear user journey optimization.Users should be guided through layered complexity: Quick Start (5 minutes) → Detailed Setup → Advanced Configuration → Development. Each document has a single responsibility and provides clear navigation to related topics, reducing cognitive load and time-to-success. 
+
+### 📁 Structure
+```
+docs/
+├── README.md                    # 🏠 Main documentation hub
+├── VIDEO_LIBRARY.md            # 🎬 Video tutorials
+├── server_guide/               # 🛠 For server operators
+│   ├── GETTING_STARTED.md      # Quick start guide
+│   ├── CUSTOMIZING.md          # Business customization
+│   └── SECURITY.md             # Authentication & RBAC
+├── client_guide/               # 👥 For end users
+│   ├── CLIENT_GUIDE.md         # Overview
+│   ├── Claude_desktop.md       # Most popular client
+│   ├── Visual_Studio_Code.md
+│   └── [other clients...]
+└── developer_guide/            # 🔧 For contributors
+    ├── DEVELOPER_GUIDE.md
+    ├── CONTRIBUTING.md
+    └── [technical guides...]
+```
+
+## 🎨 Documentation Strategy
+
+### 1. **Progressive Disclosure Design**
+- **Layer 1**: Quick start (5-minute setup) → Most users stop here
+- **Layer 2**: Detailed configuration → Power users continue
+- **Layer 3**: Advanced customization → Technical users explore
+- **Layer 4**: Development/contribution → Developers engage
+
+### 2. **User Journey**
+```
+New User Journey:
+docs/README.md → server_guide/GETTING_STARTED.md → client_guide/Claude_desktop.md ✅
+
+Admin Journey:  
+docs/README.md → server_guide/SECURITY.md → server_guide/CUSTOMIZING.md ✅
+
+Developer Journey:
+docs/README.md → developer_guide/DEVELOPER_GUIDE.md → CONTRIBUTING.md ✅
+```
+
+### 3. **UX Principles**
+
+#### **Visual Hierarchy**
+- ✅ **Clear headings**: H1 for page title, H2 for sections
+- ✅ **Emoji navigation**: 📍 breadcrumbs, 🚀 quick start sections
+- ✅ **Callout blocks**: `> **📍 Navigation:**` for wayfinding
+- ✅ **Section grouping**: Related content grouped with clear headings
+
+#### **Scannable Content**
+- ✅ **TL;DR sections**: Quick start boxes at top of long guides
+- ✅ **Use case routing**: "For X users, go here" in main README
+- ✅ **Progressive headers**: H2 → H3 → H4 hierarchy maintained
+- ✅ **Code block consistency**: All examples properly formatted
+
+#### **Cognitive Load Reduction**
+- ✅ **Single responsibility**: Each doc has one clear purpose
+- ✅ **Cross-references**: Related links clearly marked
+- ✅ **Context awareness**: Breadcrumbs show where you are
+- ✅ **Next steps**: Each doc suggests logical next actions
+
+## 📊 Objectives
+
+### User Experience Indicators
+- **Time to first success**: < 10 minutes from README to working setup
+- **Issues reduction**: Reduce "how do I..." questions and issues originating from misleading documentation.