docs: Create comprehensive documentation for repository structure and framework components

[devin-ai-integration]

Description

This PR creates comprehensive documentation for the Teal Agents Framework to improve maintainability, onboarding, and understanding of the architecture. The documentation serves both human developers and AI coding agents by providing detailed information about framework components, agent development workflows, and production patterns.

Link to Devin run: https://app.devin.ai/sessions/d394371ad8d94c7997ce830457705281
Requested by: @thepollari

Changes

Framework Architecture Documentation

• Updated main README.md with comprehensive Architecture Overview section explaining Semantic Kernel integration, FastAPI web layer, plugin system, and orchestrator patterns
• Documented the distinction between demo configurations (src/sk-agents/docs/demos/) and working agents (src/orchestrators/assistant-orchestrator/example/)
• Added getting started guide referencing University Agent as primary example implementation

Demo Configuration Documentation

• Created src/sk-agents/docs/demos/README.md with comprehensive demo index and learning progression path
• Documented learning objectives for each demo type (basic, plugins, multi-modal, remote APIs)
• Added migration guide showing how to adapt demo configurations for production agents
• Created cross-reference table mapping demo features to production implementations

Working Agent Documentation

• Enhanced University Agent README (src/orchestrators/assistant-orchestrator/example/university/README.md) with detailed implementation patterns
• Documented custom completion factory integration using Gemini API
• Explained plugin development patterns with UniversityPlugin as reference implementation
• Added troubleshooting section with common issues and solutions

Developer Onboarding Documentation

• Created DEVELOPER_GUIDE.md with development environment setup (uv, Python 3.13+, dependencies)
• Created AGENT_DEVELOPMENT.md with comprehensive step-by-step agent creation workflow
• Created TESTING_GUIDE.md documenting unit test, integration test, and mocking patterns
• Created AGENT_TEMPLATE.md providing structure template for future agent documentation
• Updated CONTRIBUTING.md with Teal Agents specific development guidelines and troubleshooting

Type of Change

• Documentation
• Bugfix
• New feature
• Refactor
• Other

Human Review Checklist

Critical Areas Requiring Verification:

1. File Path Accuracy - Verify all referenced file paths in documentation actually exist and are correct:

   • Configuration file paths in examples
   • Code snippet file references
   • Cross-references between documentation files

2. Configuration Examples - Test that YAML configuration examples are valid:

   python -c "import yaml; yaml.safe_load(open('path/to/config.yaml'))"

3. Code References - Verify that referenced code snippets and implementations actually exist:

   • UniversityPlugin implementation details
   • GeminiChatCompletionFactory patterns
   • Framework component references

4. University Agent as Reference - Validate that University Agent documentation accurately reflects the actual implementation and can be successfully run following the provided instructions

5. Cross-Reference Consistency - Check that links between documents work and terminology is consistent across all new documentation files

6. Framework Claims - Verify that documented capabilities and features actually work as described in the codebase

Additional Comments

This documentation effort creates a comprehensive knowledge base for the Teal Agents Framework. The University Agent serves as the primary reference implementation throughout the documentation, demonstrating production-ready patterns for custom completion factories, plugin development, and UI integration.

The documentation follows a layered approach:

• Architecture Overview for high-level understanding
• Demo Configurations for learning and experimentation
• Working Agent Examples for production patterns
• Developer Guides for hands-on development

All documentation uses consistent terminology and cross-references to create an interconnected knowledge base that supports both human developers and AI coding agents working with the framework.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring