tacowan · Copilot · Mar 4, 2026 · Mar 4, 2026
diff --git a/README.md b/README.md
@@ -12,8 +12,19 @@ The Model Command Line Interface (M-CLI) is a minimalist tool designed for devel
 ## Configuration
 This sample requires configuration setting in order to connect to remote services. You will need to define settings for Azure Open AI.
 ```powershell
-// Generated by Copilot
 dotnet user-secrets set "AzureOpenAISettings:ApiKey" "<api-key>" 
 dotnet user-secrets set "AzureOpenAISettings:Endpoint" "<model-endpoint>"
 dotnet user-secrets set "AzureOpenAISettings:ChatModelDeployment" "gpt-4o"
 ```
+
+## Documentation
+
+Detailed documentation is available in the [`doc/`](doc/README.md) folder:
+
+| Document | Description |
+|----------|-------------|
+| [Project Overview](doc/project-overview.md) | Architecture, design philosophy, external dependencies, and potential features |
+| [Getting Started](doc/getting-started.md) | Prerequisites, installation, and first-run walkthrough |
+| [Configuration Guide](doc/configuration.md) | Azure OpenAI settings, AI parameters, and advanced options |
+| [Tools Reference](doc/tools-reference.md) | Kernel functions available to the AI agent |
+| [Troubleshooting](doc/troubleshooting.md) | Common issues and solutions |
diff --git a/doc/README.md b/doc/README.md
@@ -9,7 +9,7 @@ Welcome to the **CardMaker** project documentation! This AI-powered tool helps y
 - [**Configuration Guide**](configuration.md) - Setting up Azure OpenAI and user secrets
 
 ### 📖 Project Information  
-- [**Project Overview**](project-overview.md) - Architecture and design philosophy
+- [**Project Overview**](project-overview.md) - Architecture, design philosophy, external dependencies, and potential features
 - [**Tools Reference**](tools-reference.md) - Available AI tools and functions
 
 ### 🛠️ Support

diff --git a/doc/project-overview.md b/doc/project-overview.md
@@ -177,6 +177,45 @@ Example card structure:
 }
 ```
 
+## 🌐 External Dependencies
+
+CardMaker relies on the following external services and libraries. All must be available for the application to function.
+
+### Required External Services
+
+| Service | Purpose | Configuration Key | Notes |
+|---------|---------|-------------------|-------|
+| **Azure OpenAI** – Chat Completion | Drives the AI assistant that generates card content | `AzureOpenAISettings:Endpoint`, `AzureOpenAISettings:ApiKey`, `AzureOpenAISettings:ChatModelDeployment` | Requires a deployed model (e.g., `gpt-4o`). The endpoint must be a valid Azure OpenAI resource URL in the form `https://<resource>.openai.azure.com/`. |
+| **Azure OpenAI** – Assistants API | Creates and manages the stateful OpenAI Assistant and its thread | Same credentials as above | Uses `OpenAIAssistantAgent` from `Microsoft.SemanticKernel.Agents.OpenAI`. The assistant is created on startup and deleted on exit. |
+| **Azure OpenAI** – Vector Stores | Provides a RAG (Retrieval-Augmented Generation) knowledge base for the assistant | Same credentials as above | An empty vector store is created on startup and deleted on exit. File upload to the store is commented out by default; see `Program.cs` lines 35-42. |
+
+### Optional / Implicit Network Dependencies
+
+| Service | Purpose | Notes |
+|---------|---------|-------|
+| **Bing Search** (`www.bing.com`) | Target URL embedded in generated QR codes | The `create_qr_code` tool builds a URL of the form `https://www.bing.com/search?q=<query>+site:learn.microsoft.com`. No API key is required; the URL is encoded in the QR image. |
+| **Microsoft Learn** (`learn.microsoft.com`) | Documentation destination for QR codes | Reachable by end-users who scan generated QR codes. No direct API call is made. |
+
+### NuGet Package Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `Microsoft.SemanticKernel` | 1.32.0 | AI orchestration and kernel plugin system |
+| `Microsoft.SemanticKernel.Agents.OpenAI` | 1.32.0-alpha | OpenAI Assistants API integration |
+| `Microsoft.SemanticKernel.Yaml` | 1.32.0 | YAML prompt template loading |
+| `Azure.AI.OpenAI.Assistants` | 1.0.0-beta.4 | Azure OpenAI Assistants client |
+| `Azure.Identity` | 1.13.1 | Azure authentication |
+| `QRCoder` | 1.6.0 | QR code image generation |
+| `TextCopy` | 6.2.1 | System clipboard access |
+| `System.Drawing.Common` | 9.0.0 | Bitmap image handling (Windows-only) |
+| `ConsoleTextFormat` | 1.3.0 | Unicode escape-code terminal formatting |
+| `Microsoft.Extensions.Configuration` | 9.0.0 | Configuration/user-secrets binding |
+| `OpenTelemetry.Exporter.Console` | 1.10.0 | Optional observability tracing |
+
+> ⚠️ **Platform note:** `System.Drawing.Common` and `TextCopy` clipboard operations require a Windows host. The project target framework is `net9.0-windows`.
+
+---
+
 ## 🌟 Extensibility
 
 ### Adding New Tools
@@ -194,4 +233,42 @@ Example card structure:
 2. Update agent prompt documents
 3. Include additional vector store files
 
+---
+
+## 🚀 Potential Features
+
+The following are ideas for extending CardMaker beyond its current capabilities.
+
+### Card Generation & Content
+| Feature | Description |
+|---------|-------------|
+| **Multi-deck themes** | Support themes beyond Platform Engineering (e.g., DevSecOps, Cloud Architecture, SRE). |
+| **Custom card ranks and suits** | Allow users to configure the number of suits and card values, or use non-standard decks. |
+| **AI image generation** | Integrate Azure OpenAI DALL·E or another image model to generate card artwork automatically. |
+| **Card validation** | Add a tool that checks generated JSON against a schema to ensure all required fields are present before saving. |
+
+### Output & Integration
+| Feature | Description |
+|---------|-------------|
+| **PDF/print export** | Generate print-ready PDFs directly from JSON card specs, removing the manual Illustrator data-merge step. |
+| **Web UI** | Wrap the CLI in a lightweight web front-end (e.g., Blazor or React) to make card creation accessible without a terminal. |
+| **Template marketplace** | Provide downloadable card face templates (SVG/Illustrator) alongside the JSON specs. |
+| **CSV / Excel export** | Export card data to spreadsheet formats for non-technical stakeholders. |
+
+### AI & Knowledge
+| Feature | Description |
+|---------|-------------|
+| **Populated vector store** | Pre-load the vector store with curated Platform Engineering documentation so the assistant has richer domain knowledge out of the box. |
+| **Multi-model support** | Allow switching between Azure OpenAI and standard OpenAI endpoints (the `OpenAISettings` class in `Settings.cs` already defines a skeleton for this). |
+| **Feedback loop** | Let users rate generated cards and feed that signal back to refine prompts or fine-tune a model. |
+| **Localization** | Generate card content in multiple languages using a language parameter passed to the agent. |
+
+### Developer Experience
+| Feature | Description |
+|---------|-------------|
+| **Unit tests** | Add a test project covering `Tools.cs` and `Settings.cs` to enable CI validation. |
+| **Cross-platform support** | Replace `System.Drawing.Common` with a cross-platform imaging library (e.g., ImageSharp) to allow Linux/macOS execution. |
+| **Docker image** | Publish a Docker image so the tool can run in containerized environments without a local .NET SDK install. |
+| **Configuration wizard** | Add an interactive first-run setup that prompts for Azure OpenAI credentials instead of requiring manual `dotnet user-secrets` commands. |
+
 Ready to dive deeper? Check out the [**Tools Reference**](tools-reference.md) for detailed function documentation! 🔧