docs: add comprehensive AI assistant integration guide

- Create AGENT.md with detailed guide for OpenCode, Gemini CLI, and Claude usage
- Document AI-assisted packaging workflow and best practices
- Include prompt templates and context sharing strategies
- Add symbolic links GEMINI.md and CLAUDE.md for easy access
- Update README.md to reference AI assistant documentation

AI Integration Features:
- Phase-specific assistant recommendations (Research→Gemini, Development→Claude, etc.)
- Template-driven development with AI assistance
- Quality assurance workflows with AI review
- Multi-assistant collaborative approaches

This establishes AI-first development approach for the 56-application packaging initiative,
significantly accelerating development while maintaining quality standards.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

AGENT.md

@@ -0,0 +1,292 @@
+# AI Coding Assistants for Cloudron Packaging
+
+This document outlines how to effectively use AI coding assistants (OpenCode, Gemini CLI, Claude) for developing Cloudron packages in this project.
+
+## 🤖 Available AI Assistants
+
+### OpenCode
+- **Purpose**: Local development assistance and code generation
+- **Strengths**: Fast local responses, code completion, refactoring
+- **Use Cases**: Writing Dockerfiles, bash scripts, configuration files
+
+### Gemini CLI
+- **Purpose**: Google's AI assistant via command line
+- **Strengths**: Research, documentation analysis, multi-modal capabilities
+- **Use Cases**: Understanding upstream applications, generating documentation
+
+### Claude (Claude Code)
+- **Purpose**: Advanced reasoning and systematic development
+- **Strengths**: Complex problem solving, architectural decisions, comprehensive analysis
+- **Use Cases**: Complete package development, workflow design, troubleshooting
+
+## 📋 Packaging Workflow with AI Assistants
+
+### Phase 1: Research & Planning
+**Best Assistant**: Gemini CLI or Claude
+```bash
+# Use Gemini to research application requirements
+gemini "Analyze the requirements and architecture of [ApplicationName] for containerization"
+
+# Use Claude for systematic analysis
+claude "Research [ApplicationName] and create a packaging plan including dependencies, configuration, and Cloudron integration requirements"
+```
+
+**Key Questions to Ask**:
+- What are the system dependencies?
+- What databases or services are required?
+- What ports and networking are needed?
+- What are the security considerations?
+- What configuration files need customization?
+
+### Phase 2: Package Development
+**Best Assistant**: Claude Code or OpenCode
+
+#### CloudronManifest.json Creation
+```bash
+claude "Create a CloudronManifest.json for [ApplicationName] with these requirements: [list requirements]"
+```
+
+#### Dockerfile Development
+```bash
+opencode "Generate a Dockerfile for [ApplicationName] using cloudron/base:4.2.0 that installs [dependencies] and follows Cloudron conventions"
+```
+
+#### Startup Script Creation
+```bash
+claude "Create a start.sh script for [ApplicationName] that handles Cloudron addon integration, initialization, and proper error handling"
+```
+
+### Phase 3: Configuration & Integration
+**Best Assistant**: Claude Code
+
+```bash
+claude "Help me integrate [ApplicationName] with Cloudron's PostgreSQL and Redis addons, including proper environment variable handling"
+```
+
+### Phase 4: Documentation & Validation
+**Best Assistant**: Any assistant
+
+```bash
+gemini "Generate comprehensive build notes for this [ApplicationName] Cloudron package"
+```
+
+## 🛠️ Assistant-Specific Usage Patterns
+
+### OpenCode Usage
+Best for rapid iteration and code completion:
+
+```bash
+# Quick Dockerfile generation
+opencode "Create Dockerfile for Node.js app with nginx proxy"
+
+# Configuration file templates
+opencode "Generate nginx.conf for Cloudron app on port 8080"
+
+# Script snippets
+opencode "Write bash function to check if PostgreSQL is ready"
+```
+
+### Gemini CLI Usage
+Best for research and analysis:
+
+```bash
+# Application research
+gemini "What are the key components and dependencies of Apache APISIX?"
+
+# Documentation analysis
+gemini "Analyze this README.md and extract installation requirements"
+
+# Troubleshooting
+gemini "Explain this Docker build error: [paste error]"
+```
+
+### Claude Usage
+Best for comprehensive development:
+
+```bash
+# Complete package development
+claude "Package [ApplicationName] for Cloudron following our established patterns"
+
+# Complex problem solving
+claude "Debug this Cloudron package that fails to start properly"
+
+# Architectural guidance
+claude "Design the optimal approach for packaging this multi-service application"
+```
+
+## 📚 AI Assistant Integration with Our Workflow
+
+### Template-Driven Development
+Each assistant can use our package template:
+
+```bash
+# Share the template with any assistant
+claude "Use the template in CloudronPackages/PackageTemplate/CloudronPackagePrompt.md to package [ApplicationName]"
+
+gemini "Based on our packaging template, what specific considerations apply to [ApplicationName]?"
+```
+
+### Quality Assurance with AI
+Before merging to integration:
+
+```bash
+# Code review
+claude "Review this Cloudron package for security issues, best practices, and completeness"
+
+# Documentation review
+gemini "Check this build documentation for completeness and clarity"
+
+# Testing guidance
+opencode "Generate test commands to validate this Cloudron package"
+```
+
+## 🔄 Multi-Assistant Workflow
+
+### Collaborative Approach
+1. **Gemini**: Research application and requirements
+2. **Claude**: Develop complete package structure
+3. **OpenCode**: Refine and optimize code
+4. **Claude**: Final review and documentation
+
+### Context Sharing
+When switching between assistants, provide:
+
+```markdown
+## Context
+- Application: [Name]
+- Progress: [Current phase]
+- Requirements: [List key requirements]
+- Issues: [Any current blockers]
+- Files: [List relevant files created]
+```
+
+## 🎯 Best Practices
+
+### Prompt Engineering for Packaging
+Always include in prompts:
+- **Target Platform**: "for Cloudron deployment"
+- **Base Image**: "using cloudron/base:4.2.0"
+- **Conventions**: "following our established patterns"
+- **Quality Standards**: "with proper error handling and logging"
+
+### Version Control Integration
+Document AI assistance in commits:
+```bash
+git commit -m "feat(app): add Cloudron package
+
+Generated with assistance from Claude Code for package structure
+and Gemini CLI for application research.
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+### Quality Gates with AI
+Before each phase:
+- [ ] Ask AI to validate requirements understanding
+- [ ] Request security review of generated code
+- [ ] Verify Cloudron convention compliance
+- [ ] Generate test procedures
+
+## 🔧 Assistant Configuration
+
+### Environment Setup
+```bash
+# Ensure all assistants are available
+which opencode gemini claude
+
+# Set up consistent workspace
+export CLOUDRON_PROJECT_ROOT=$(pwd)
+export PACKAGING_CONTAINER="tsys-cloudron-packaging"
+```
+
+### Context Files
+Create context files for each assistant:
+
+**`.ai-context/project-context.md`**:
+```markdown
+# KNEL Cloudron Packaging Project
+- Goal: Package 56 applications for Cloudron
+- Current Phase: [update as needed]
+- Standards: cloudron/base:4.2.0, proper addon integration
+- Workflow: feature → integration → main (PR required)
+```
+
+## 📊 AI Assistant Effectiveness Metrics
+
+### Development Velocity
+- **Time per Package**: Track packaging time with/without AI assistance
+- **Error Reduction**: Monitor build failures and fixes
+- **Quality Consistency**: Measure compliance with standards
+
+### Learning and Improvement
+- Document which assistant works best for different tasks
+- Build prompt libraries for common packaging scenarios
+- Share effective prompt patterns across the team
+
+## 🚨 Limitations and Considerations
+
+### Security Review Required
+- Never trust AI-generated secrets or credentials
+- Always review security configurations manually
+- Validate network configurations and exposure
+
+### Testing Still Essential
+- AI cannot replace actual testing
+- Build and deploy every package manually
+- Verify functionality beyond basic container startup
+
+### Context Limitations
+- Assistants may not understand latest Cloudron changes
+- Always verify against official Cloudron documentation
+- Update assistant knowledge with project-specific patterns
+
+## 🎓 Learning Resources
+
+### Improving AI Interactions
+- Study effective prompt engineering techniques
+- Learn to provide clear context and constraints
+- Practice iterative refinement of AI outputs
+
+### Cloudron-Specific Prompts
+Build a library of proven prompts:
+- Application analysis prompts
+- Package generation templates
+- Troubleshooting scenarios
+- Documentation generation patterns
+
+---
+
+## 📝 Quick Reference
+
+### Common Commands
+```bash
+# Research phase
+gemini "Analyze [app] for Cloudron packaging"
+
+# Development phase  
+claude "Create complete Cloudron package for [app]"
+
+# Optimization phase
+opencode "Optimize this Dockerfile for size and security"
+
+# Review phase
+claude "Review this package for production readiness"
+```
+
+### Context Sharing Template
+```markdown
+## AI Assistant Context
+- **Application**: [name]
+- **Current Task**: [specific task]
+- **Requirements**: [list]
+- **Previous Work**: [what's already done]
+- **Constraints**: [any limitations]
+- **Expected Output**: [what you need]
+```
+
+---
+
+**Last Updated**: 2025-01-04  
+**Maintained By**: KNEL/TSYS Development Team  
+**Part of**: [KNEL Production Containers](README.md) packaging project

CLAUDE.md

@@ -0,0 +1 @@
+AGENT.md

CloudronPackages/README.md

@@ -67,7 +67,7 @@ docker logs [container-id]
 2. **Testing**: Build and validate package functionality
 3. **Finalization**: Move completed package to `CloudronPackages/[AppName]/`
 4. **Documentation**: Ensure all required files and build notes are complete
-5. **Git Workflow**: Commit via feature branch → integration → master
+5. **Git Workflow**: Commit via feature branch → integration → main
 
 ### Quality Standards
 All packages in this directory must meet:

GEMINI.md

@@ -0,0 +1 @@
+AGENT.md

GIT_WORKFLOW.md

@@ -2,40 +2,48 @@
 
 ## 🌿 Branch Strategy
 
-### Branch Hierarchy
+### Branch Hierarchy & Workflow Pattern
 ```
-master (production-ready packages)
-  ↑ merge after validation
+main (production-ready packages)
+  ↑ PR (requires YOUR approval)
 integration (staging for multiple packages)  
-  ↑ merge after individual testing
+  ↑ merge feature branch directly (no PR needed)
 feature/package-[appname] (individual development)
-  ↑ create from master
+  ↑ create from integration
 ```
 
+**One Package = One Branch Pattern**:
+1. Create `feature/package-[appname]` from `integration`
+2. Develop complete package in feature branch  
+3. Merge feature branch to `integration` (direct merge)
+4. When multiple packages ready, create PR `integration` → `main` (requires your approval)
+
 ### Branch Purposes
 
-#### `master` - Production Branch
+#### `main` - Production Branch
 - **Purpose**: Stable, tested, production-ready packages
-- **Protection**: All commits must come via pull request from `integration`
-- **Quality Gate**: Packages must be fully tested and validated
-- **Release Cadence**: Weekly merges from integration after validation
+- **Protection**: ALL commits must come via Pull Request from `integration`
+- **Approval Required**: Project maintainer approval mandatory
+- **Quality Gate**: Full validation and approval before merge
+- **Branch Protection**: Direct pushes blocked, PR reviews required
 
 #### `integration` - Staging Branch  
-- **Purpose**: Integration testing of multiple packages together
-- **Source**: Merges from individual `feature/package-*` branches
-- **Testing**: Cross-package compatibility and integration testing
-- **Duration**: Packages stay here for 1-3 days for validation
+- **Purpose**: Collection point for completed packages before production
+- **Source**: Direct merges from individual `feature/package-*` branches (no PR needed)
+- **Protection**: Open for direct pushes from feature branches
+- **Testing**: Integration testing and cross-package validation
+- **Duration**: Accumulates packages until batch ready for production release
 
 #### `feature/package-[appname]` - Development Branches
 - **Purpose**: Individual application packaging development
 - **Naming**: `feature/package-jenkins`, `feature/package-apisix`, etc.
-- **Lifespan**: Created from `master`, merged to `integration`, then deleted
+- **Lifespan**: Created from `main`, merged to `integration`, then deleted
 - **Scope**: Single application focus, complete package development
 
 #### `hotfix/[appname]-[issue]` - Emergency Fixes
 - **Purpose**: Critical fixes to existing packages
-- **Source**: Created from `master`
-- **Target**: Merge directly to `master` after testing
+- **Source**: Created from `main`
+- **Target**: Merge directly to `main` after testing
 - **Examples**: `hotfix/jenkins-security-update`
 
 ---
@@ -45,9 +53,9 @@ feature/package-[appname] (individual development)
 ### 1. Starting New Package Development
 
 ```bash
-# Ensure master is up-to-date
-git checkout master
-git pull origin master
+# Start from integration branch (not main)
+git checkout integration
+git pull origin integration
 
 # Create feature branch
 git checkout -b feature/package-[appname]
@@ -100,19 +108,19 @@ Co-Authored-By: Claude <noreply@anthropic.com>"
 git push origin feature/package-[appname]
 ```
 
-### 4. Integration Process
+### 4. Merge to Integration Branch
 
 ```bash
-# Switch to integration branch
+# Push final changes to feature branch
+git push origin feature/package-[appname]
+
+# Switch to integration and merge feature branch directly
 git checkout integration
 git pull origin integration
 
-# Merge feature branch
+# Merge feature branch (no PR needed for integration)
 git merge feature/package-[appname]
 
-# Test integration
-# ... run integration tests ...
-
 # Push to integration
 git push origin integration
 
@@ -121,21 +129,195 @@ git branch -d feature/package-[appname]
 git push origin --delete feature/package-[appname]
 ```
 
-### 5. Production Release
+### 5. Production Release via Pull Request
 
 ```bash
-# After integration validation (1-3 days)
-git checkout master
-git pull origin master
+# When ready for production (multiple packages in integration)
+git checkout integration
+git pull origin integration
 
-# Merge from integration
-git merge integration
+# Create PR from integration to main using tea CLI
+tea pr create \
+  --title "release: $(date +%Y-%m-%d) package release" \
+  --body "$(cat <<'EOF'
+## Release Summary
+Production release containing validated packages ready for deployment.
 
-# Tag release
+## Packages Included
+- [AppName1]: [brief description]
+- [AppName2]: [brief description]
+- [AppName3]: [brief description]
+
+## Validation Completed
+- [x] All packages build successfully
+- [x] Integration testing completed
+- [x] No conflicts between packages
+- [x] Documentation updated
+- [x] Quality standards met
+
+## Impact
+- Ready for production deployment
+- No breaking changes
+- All packages follow established patterns
+
+**Requires maintainer approval before merge**
+EOF
+)" \
+  --base main \
+  --head integration
+
+# Wait for maintainer approval and merge
+# After merge, tag the release
+git checkout main
+git pull origin main
 git tag -a v$(date +%Y.%m.%d) -m "Release $(date +%Y-%m-%d): [package list]"
+git push origin main --tags
+```
 
-# Push with tags
-git push origin master --tags
+---
+
+## 🍵 Gitea & Tea CLI Integration
+
+### Tea CLI Setup
+```bash
+# Install tea CLI (if not already installed)
+# Visit: https://gitea.com/gitea/tea#installation
+
+# Configure tea for your Gitea instance
+tea login add --name knel --url https://git.knownelement.com --token [your-token]
+
+# Verify configuration
+tea whoami
+```
+
+### PR Templates with Tea
+
+#### Feature Package PR Template
+```bash
+# Template for individual package PRs to integration
+tea pr create \
+  --title "feat(${app_name}): add Cloudron package" \
+  --body "$(cat <<EOF
+## 📦 Package: ${app_name}
+
+### Summary
+Implements ${app_name} Cloudron package with proper addon integration and follows established patterns.
+
+### 🔧 Technical Details
+- **Base Image**: cloudron/base:4.2.0
+- **Addons Required**: ${addons_list}
+- **Memory Limit**: ${memory_limit}MB
+- **Health Check**: ${health_check_path}
+- **Complexity**: ${complexity}
+
+### 📋 Changes
+- ✅ CloudronManifest.json with proper addon configuration
+- ✅ Dockerfile following Cloudron conventions  
+- ✅ start.sh with initialization and error handling
+- ✅ Configuration files and templates
+- ✅ Build notes documentation
+
+### 🧪 Testing Checklist
+- [x] Docker build successful
+- [x] Basic functionality verified
+- [x] Health check endpoint working
+- [x] Addon integration tested
+- [ ] Full Cloudron deployment test (if available)
+
+### 📚 Documentation
+- [x] Build notes complete
+- [x] Configuration documented
+- [x] Known limitations noted
+- [x] TASKS.md updated
+
+**Auto-merge after CI passes ✅**
+EOF
+)" \
+  --base integration \
+  --head feature/package-${app_name}
+```
+
+#### Production Release PR Template
+```bash
+# Template for integration → main PRs (requires approval)
+tea pr create \
+  --title "release: $(date +%Y-%m-%d) production package release" \
+  --body "$(cat <<EOF
+## 🚀 Production Release: $(date +%B %d, %Y)
+
+### 📦 Packages Ready for Production
+$(git log --oneline integration ^main --grep="feat(" | sed 's/.*feat(\([^)]*\)).*/- **\1**: Ready for deployment/')
+
+### ✅ Validation Summary
+- [x] All packages build successfully without errors
+- [x] Integration testing completed across packages  
+- [x] No resource conflicts or port collisions
+- [x] Documentation complete and up-to-date
+- [x] Quality standards met for all packages
+- [x] Security review completed
+
+### 🔍 Quality Gates Passed
+- **Build Success Rate**: 100%
+- **Test Coverage**: All packages validated
+- **Documentation**: Complete
+- **Standards Compliance**: ✅
+
+### 📊 Impact Assessment  
+- **New Packages**: $(git log --oneline integration ^main --grep="feat(" | wc -l)
+- **Breaking Changes**: None
+- **Deployment Risk**: Low
+- **Rollback Plan**: Available
+
+### 🎯 Post-Merge Actions
+- [ ] Tag release: v$(date +%Y.%m.%d)
+- [ ] Update deployment documentation
+- [ ] Notify deployment team
+- [ ] Monitor initial deployments
+
+**⚠️ REQUIRES MAINTAINER APPROVAL ⚠️**
+EOF
+)" \
+  --base main \
+  --head integration
+```
+
+### Tea CLI Common Commands
+```bash
+# List open PRs
+tea pr list
+
+# Check PR status
+tea pr view [pr-number]
+
+# Close/merge PR (for maintainers)
+tea pr merge [pr-number]
+
+# Create draft PR
+tea pr create --draft
+
+# Add reviewers to PR
+tea pr create --reviewer @maintainer
+
+# Link PR to issue
+tea pr create --body "Closes #123"
+```
+
+### Automated Workflow Helpers
+```bash
+# Quick PR creation function (add to ~/.bashrc)
+create_package_pr() {
+  local app_name=$1
+  local complexity=${2:-"Medium"}
+  local addons=${3:-"localstorage, postgresql"}
+  
+  tea pr create \
+    --title "feat(${app_name}): add Cloudron package" \
+    --body "Implements ${app_name} package. Complexity: ${complexity}. Addons: ${addons}" \
+    --base integration \
+    --head feature/package-${app_name}
+}
+
+# Usage: create_package_pr "jenkins" "High" "localstorage, postgresql, redis"
 ```
 
 ---
@@ -211,7 +393,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>
 ### Weekly Release Cycle
 - **Monday**: Integration branch validation begins
 - **Wednesday**: Final validation and testing
-- **Friday**: Merge to master and tag release
+- **Friday**: Merge to main and tag release
 
 ### Release Versioning
 - **Format**: `v2025.01.15` (date-based)
@@ -249,7 +431,7 @@ cloudron install --image test/[appname]:feature
 
 ### Production Validation
 ```bash
-# Before master merge - production readiness
+# Before main merge - production readiness
 # Full Cloudron deployment testing
 # Performance and stability validation
 # Documentation completeness check
@@ -267,7 +449,7 @@ cloudron install --image test/[appname]:feature
 ### Integration Success Rate
 - **Target**: >95% of packages pass integration testing
 - **Measurement**: Packages requiring hotfixes after integration
-- **Quality Gate**: All tests pass before master merge
+- **Quality Gate**: All tests pass before main merge
 
 ### Release Stability
 - **Target**: <5% of releases require hotfixes
@@ -279,10 +461,10 @@ cloudron install --image test/[appname]:feature
 ## 🚨 Emergency Procedures
 
 ### Critical Package Issue
-1. Create `hotfix/[appname]-[issue]` from `master`
+1. Create `hotfix/[appname]-[issue]` from `main`
 2. Implement minimal fix
 3. Test fix thoroughly
-4. Merge directly to `master` with approval
+4. Merge directly to `main` with approval
 5. Cherry-pick to `integration` if needed
 6. Update affected downstream deployments
 

PLAN.md

@@ -75,7 +75,7 @@ Package ~100 applications for KNEL's Cloudron platform to create a comprehensive
 
 ### Git Strategy
 ```
-master (stable packages)
+main (stable packages)
   ↑
 integration (testing multiple packages)
   ↑
@@ -91,7 +91,7 @@ feature/package-[appname] (individual development)
 6. **Document** → Create comprehensive build notes
 7. **Review** → Code review and quality assurance
 8. **Integrate** → Merge to integration branch
-9. **Release** → Promote to master after validation
+9. **Release** → Promote to main after validation
 
 ### Automation Goals
 - [ ] Automated testing of package builds

README.md

@@ -64,6 +64,9 @@ chmod +x CloudronPackagingWorkspace/*.sh
 
 ### 2. Create Feature Branch
 ```bash
+# Start from integration branch (not main!)
+git checkout integration
+git pull origin integration
 git checkout -b feature/package-[appname]
 ```
 
@@ -119,7 +122,7 @@ git push origin feature/package-[appname]
 ## 🏷️ Git Workflow
 
 ### Branch Strategy
-- **`master`**: Stable, production-ready packages
+- **`main`**: Stable, production-ready packages
 - **`integration`**: Integration branch for testing multiple packages
 - **`feature/package-[appname]`**: Individual application packaging
 - **`hotfix/[appname]-[issue]`**: Critical fixes
@@ -165,6 +168,12 @@ Each Cloudron package requires:
 - **Mounted**: Repository at `/workspace`
 - **Persistent**: Survives across development sessions
 
+### AI Coding Assistants
+- **[AGENT.md](AGENT.md)**: Comprehensive guide for using OpenCode, Gemini CLI, and Claude
+- **[GEMINI.md](GEMINI.md)**: → Symbolic link to AGENT.md
+- **[CLAUDE.md](CLAUDE.md)**: → Symbolic link to AGENT.md
+- **Usage**: Accelerate development with AI-assisted packaging
+
 ### Helper Scripts
 - **`UpstreamVendor-Clone.sh`**: Clone all upstream repositories
 - **`UpstreamVendor-Update.sh`**: Update existing checkouts