feat: Sync latest templates from blackroad-sandbox

✨ Generated with [Claude Code](https://claude.com/claude-code)

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

templates/README-TEMPLATE.md

@@ -0,0 +1,389 @@
+# [Service/Feature Name]
+
+**One-line description of what this does**
+
+## Quick Start (Copy-Paste Ready)
+
+```bash
+# Clone and setup
+cd ~/blackroad-sandbox
+git pull origin main
+
+# Install dependencies
+pip3 install -r requirements.txt
+
+# Start service
+PORT=8000 python3 blackroad-service.py
+
+# Verify it's running
+curl http://localhost:8000/health
+```
+
+---
+
+## What This Does
+
+[2-3 sentence explanation of purpose and value]
+
+---
+
+## Installation
+
+### Local Development
+
+```bash
+# Navigate to project
+cd ~/blackroad-sandbox
+
+# Install Python dependencies
+pip3 install -r requirements.txt
+
+# Copy environment template
+cp .env.example .env
+
+# Add your secrets
+cat >> .env <<'EOF'
+SERVICE_TOKEN=your-token-here
+API_KEY=your-key-here
+EOF
+
+# Verify installation
+python3 -c "import flask; print('✅ Dependencies installed')"
+```
+
+### Docker
+
+```bash
+# Build image
+docker build -t blackroad-service .
+
+# Run container
+docker run -p 8000:8000 --env-file .env blackroad-service
+
+# Verify
+curl http://localhost:8000/health
+```
+
+---
+
+## Usage
+
+### Start the Service
+
+```bash
+# Development mode
+PORT=8000 python3 blackroad-service.py
+
+# Production mode
+FLASK_ENV=production PORT=8000 python3 blackroad-service.py
+
+# With Docker Compose
+docker-compose up -d service-name
+```
+
+### Test the Service
+
+```bash
+# Health check
+curl http://localhost:8000/health
+
+# Test specific endpoint
+curl http://localhost:8000/api/resource -X POST -H "Content-Type: application/json" -d '{"key":"value"}'
+
+# Run automated tests
+pytest tests/test_service.py -v
+```
+
+### Deploy to Production
+
+```bash
+# Deploy to Railway
+cd ~/blackroad-sandbox
+railway up --service service-name
+
+# Deploy to Cloudflare
+cd cloudflare-workers
+wrangler deploy service.js --config wrangler-service.toml
+
+# Verify deployment
+curl https://service.blackroad.io/health
+```
+
+---
+
+## API Reference
+
+### Endpoints
+
+#### `GET /health`
+
+Health check endpoint.
+
+```bash
+# Example
+curl http://localhost:8000/health
+```
+
+**Response:**
+```json
+{
+  "ok": true,
+  "service": "service-name",
+  "version": "1.0.0"
+}
+```
+
+#### `POST /api/resource`
+
+Create a new resource.
+
+```bash
+# Example
+curl http://localhost:8000/api/resource \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"name":"example","value":42}'
+```
+
+**Response:**
+```json
+{
+  "ok": true,
+  "resource_id": "abc123"
+}
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required
+SERVICE_TOKEN=your-service-token
+API_KEY=your-api-key
+
+# Optional
+PORT=8000
+LOG_LEVEL=info
+ENVIRONMENT=production
+```
+
+### Config Files
+
+- `.env` - Environment variables
+- `config.yaml` - Service configuration
+- `railway.toml` - Railway deployment config
+
+---
+
+## Development
+
+### Running Tests
+
+```bash
+# All tests
+pytest -v
+
+# Unit tests only
+pytest -m unit -v
+
+# Integration tests
+pytest -m integration -v
+
+# With coverage
+pytest --cov=. --cov-report=html
+open coverage_html/index.html
+```
+
+### Local Development Workflow
+
+```bash
+# 1. Create feature branch
+git checkout -b feature/new-feature
+
+# 2. Make changes
+# Edit files...
+
+# 3. Test locally
+pytest -v
+python3 blackroad-service.py
+
+# 4. Commit
+git add .
+git commit -m "feat: Add new feature"
+
+# 5. Push
+git push -u origin feature/new-feature
+
+# 6. Create PR
+gh pr create --title "Add new feature" --body "Description"
+```
+
+---
+
+## Deployment
+
+### Railway
+
+```bash
+# Link to project
+railway link 0c7bcf07-307b-4db6-9c94-22a456500d68
+
+# Deploy
+railway up --service service-name
+
+# Check status
+railway status
+
+# View logs
+railway logs --tail 100
+```
+
+### Cloudflare Pages/Workers
+
+```bash
+# Deploy worker
+cd cloudflare-workers
+wrangler deploy service.js --config wrangler-service.toml
+
+# Deploy page
+cd domains/domain-name
+wrangler pages deploy . --project-name=domain-name
+
+# Check deployment
+wrangler pages deployment list --project-name=domain-name
+```
+
+### Vercel
+
+```bash
+# Deploy
+cd vercel-projects/project-name
+vercel --prod
+
+# Check deployment
+vercel ls
+```
+
+---
+
+## Troubleshooting
+
+### Service Won't Start
+
+```bash
+# Check if port is in use
+lsof -i :8000
+
+# Kill existing process
+kill -9 $(lsof -t -i:8000)
+
+# Restart service
+PORT=8000 python3 blackroad-service.py
+```
+
+### Import Errors
+
+```bash
+# Reinstall dependencies
+pip3 install -r requirements.txt --force-reinstall
+
+# Verify Python version
+python3 --version  # Should be 3.11+
+
+# Check imports
+python3 -c "import flask; print('✅ Flask OK')"
+```
+
+### Environment Variables Not Loaded
+
+```bash
+# Check .env exists
+ls -la .env
+
+# Source manually
+source .env
+
+# Verify variables
+echo $SERVICE_TOKEN
+```
+
+### Deployment Failed
+
+```bash
+# Railway
+railway logs --tail 100
+railway status
+railway variables  # Check secrets are set
+
+# Cloudflare
+wrangler tail  # View live logs
+wrangler pages deployment list --project-name=PROJECT_NAME
+```
+
+---
+
+## Architecture
+
+[Diagram or description of how this service fits into the larger system]
+
+---
+
+## Contributing
+
+```bash
+# 1. Fork/clone
+git clone https://github.com/BlackRoad-OS/repo-name.git
+
+# 2. Create branch
+git checkout -b feature/your-feature
+
+# 3. Make changes and test
+pytest -v
+
+# 4. Commit with conventional commits
+git commit -m "feat: Add your feature"
+
+# 5. Push
+git push -u origin feature/your-feature
+
+# 6. Create PR
+gh pr create
+```
+
+---
+
+## License
+
+```
+# ============================================================================
+# BlackRoad OS - Proprietary Software
+# Copyright (c) 2025 BlackRoad OS, Inc. / Alexa Louise Amundson
+# All Rights Reserved.
+# ============================================================================
+```
+
+---
+
+## Support
+
+- **Email**: blackroad.systems@gmail.com
+- **Docs**: [Link to docs]
+- **Issues**: [Link to GitHub issues]
+
+---
+
+## Related Services
+
+- [Service 1](link) - Description
+- [Service 2](link) - Description
+- [Service 3](link) - Description
+
+---
+
+**Quick Links**:
+- [API Documentation](link)
+- [Deployment Guide](link)
+- [Troubleshooting](link)