docs: Create comprehensive documentation for Teal Agents Framework

[devin-ai-integration]

Comprehensive Documentation for Teal Agents Framework

Description

This PR creates comprehensive documentation for the Teal Agents Framework, covering repository structure, framework components, demo configurations, working agents, and architectural overviews. Additionally, it addresses identified documentation gaps with complete guides for build automation, deployment, security, performance, and migration.

Requested by: @bartot_merck (tyler.barto@merck.com)
Link to Devin run: https://app.devin.ai/sessions/24ff613dd71241c0ad236c817200d848

Changes

Core Framework Documentation

• README.md - Complete architecture overview with component relationships, API versioning, and getting started guide
• AGENT_DEVELOPMENT.md - Step-by-step guide for creating new agents with examples for all agent types (v1, v2alpha1, v1alpha1)
• DEVELOPER_GUIDE.md - Development environment setup, workflows, and troubleshooting
• TESTING_GUIDE.md - Comprehensive testing strategies including unit, integration, and performance testing
• AGENT_TEMPLATE.md - Template structure for documenting future agents

Demo Configuration Documentation

• src/sk-agents/docs/demos/README.md - Complete index of all 11 demos with learning progression and migration guide from demo configs to production agents

Production Documentation (Addressing Identified Gaps)

• BUILD_AUTOMATION.md - Complete Makefile documentation, Docker builds, and GitHub Actions workflows
• DEPLOYMENT_GUIDE.md - Production deployment strategies for single-node and Kubernetes environments
• API_REFERENCE.md - Complete API documentation for REST, WebSocket, and A2A endpoints
• SECURITY_GUIDE.md - Authentication, authorization, and security best practices
• PERFORMANCE_GUIDE.md - Performance optimization, monitoring, and troubleshooting strategies
• PACKAGE_CONFIGURATION.md - Package management, dependency handling, and build system configuration
• MIGRATION_GUIDE.md - Version migration paths and upgrade procedures between framework versions

Enhanced Contributing Guidelines

• CONTRIBUTING.md - Updated with Teal Agents specific development guidelines and workflows

Type of Change

• Documentation
• Bugfix
• New feature
• Refactor
• Other

Human Review Checklist

⚠️ High Priority - Accuracy Verification

• Verify all file paths and directory references are correct (many examples reference specific files)

• Check YAML configuration examples match actual schemas in the codebase

• Validate API endpoint documentation against actual FastAPI routes in src/sk-agents/src/sk_agents/app.py

• Test key setup/migration procedures in DEVELOPER_GUIDE.md and MIGRATION_GUIDE.md

• Verify Docker commands and Makefile targets in BUILD_AUTOMATION.md actually exist and work

Medium Priority - Content Validation

• Check that security recommendations in SECURITY_GUIDE.md align with actual framework security features
• Verify performance optimization strategies in PERFORMANCE_GUIDE.md are applicable to the framework
• Ensure demo descriptions in demos/README.md accurately reflect the actual demo configurations
• Validate that plugin development examples use correct inheritance patterns and decorators

Low Priority - Consistency

• Check cross-references between documents are accurate
• Verify consistent terminology usage across all documentation
• Ensure code examples follow the same style and patterns

Additional Comments

Documentation Scale: This PR adds 5,681 lines of documentation across 14 files. The comprehensive nature makes it challenging to verify every detail, so focus review on the high-priority items above.

No Functional Testing: Since this is pure documentation, the accuracy of code examples, configuration snippets, and procedural steps cannot be automatically validated. Manual spot-checking of key examples is recommended.

Framework Coverage: The documentation now covers all major framework components including the three app versions (V1, V2, V3), orchestrators, plugins, custom types, and deployment patterns. This should significantly improve developer onboarding and framework adoption.

[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