re-uploading work

2026-02-04 17:46:30 -06:00
commit 3b14c65998
1388 changed files with 381262 additions and 0 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,199 @@
+# Attune Documentation
+
+Welcome to the Attune project documentation! This directory contains comprehensive documentation for the Attune automation and orchestration platform.
+
+## 📚 Quick Navigation
+
+### Getting Started
+- **[Quick Start Guide](guides/quick-start.md)** - Get up and running quickly
+- **[Workspace Setup](development/WORKSPACE_SETUP.md)** - Set up your development environment
+- **[Configuration Guide](configuration/configuration.md)** - Configure Attune services
+
+### Core Concepts
+- **[Architecture Overview](architecture/)** - System design and service architecture
+- **[Workflow Engine](workflows/workflow-execution-engine.md)** - How workflows are executed
+- **[Pack System](packs/pack-structure.md)** - Understanding automation packs
+- **[Sensors & Triggers](sensors/)** - Event monitoring and triggering
+
+### Development
+- **[API Documentation](api/)** - REST API endpoint reference
+- **[CLI Reference](cli/cli.md)** - Command-line interface guide
+- **[Testing Guide](testing/running-tests.md)** - How to run and write tests
+- **[Authentication](authentication/authentication.md)** - Auth mechanisms and security
+
+### Operations
+- **[Production Deployment](deployment/production-deployment.md)** - Deploy to production
+- **[Operations Runbook](deployment/ops-runbook-queues.md)** - Troubleshooting and maintenance
+- **[Performance Optimization](performance/QUICKREF-performance-optimization.md)** - Performance tuning
+
+## 📁 Directory Structure
+
+```
+docs/
+├── api/                  # REST API documentation
+├── architecture/         # System architecture and service design
+├── authentication/       # Auth, security, and secrets management
+├── cli/                  # Command-line interface documentation
+├── configuration/        # Configuration guides and troubleshooting
+├── dependencies/         # Dependency management documentation
+├── deployment/           # Production deployment and operations
+├── development/          # Developer guides and tooling
+├── examples/             # Example configurations and workflows
+├── guides/               # Getting started guides and tutorials
+├── migrations/           # Database migration documentation
+├── packs/                # Pack system documentation
+├── performance/          # Performance optimization guides
+├── plans/                # Future planning and proposals
+├── sensors/              # Sensor system documentation
+├── testing/              # Testing strategies and guides
+├── web-ui/               # Web UI documentation
+├── webhooks/             # Webhook system documentation
+└── workflows/            # Workflow engine documentation
+```
+
+## 🔍 Finding What You Need
+
+### By Role
+
+**I'm a new developer:**
+1. Start with [Workspace Setup](development/WORKSPACE_SETUP.md)
+2. Read the [Quick Start Guide](guides/quick-start.md)
+3. Review [Architecture Overview](architecture/)
+4. Learn about [Testing](testing/running-tests.md)
+
+**I'm building a pack:**
+1. Read [Pack Structure](packs/pack-structure.md)
+2. Check [Examples](examples/)
+3. Review [Pack Testing Framework](packs/pack-testing-framework.md)
+4. See [Core Pack Integration](packs/core-pack-integration.md)
+
+**I'm creating workflows:**
+1. Start with [Workflow Quickstart](guides/workflow-quickstart.md)
+2. Learn [Workflow Orchestration](workflows/workflow-orchestration.md)
+3. Understand [Rule Parameter Mapping](workflows/rule-parameter-mapping.md)
+4. Review [Execution Hierarchy](workflows/execution-hierarchy.md)
+
+**I'm deploying to production:**
+1. Read [Production Deployment](deployment/production-deployment.md)
+2. Review [Configuration Guide](configuration/configuration.md)
+3. Check [Security Review](authentication/security-review-2024-01-02.md)
+4. Study [Operations Runbook](deployment/ops-runbook-queues.md)
+
+**I'm using the API:**
+1. Browse [API Documentation](api/)
+2. Check [OpenAPI Spec](api/openapi-spec-completion.md)
+3. Learn [Authentication](authentication/auth-quick-reference.md)
+4. Review endpoint-specific guides (e.g., [Actions](api/api-actions.md))
+
+### By Topic
+
+| Topic | Primary Location | Key Files |
+|-------|-----------------|-----------|
+| Authentication | `authentication/` | `authentication.md`, `auth-quick-reference.md` |
+| Workflows | `workflows/` | `workflow-execution-engine.md`, `workflow-orchestration.md` |
+| Sensors | `sensors/` | `sensor-interface.md`, `sensor-lifecycle-management.md` |
+| Testing | `testing/` | `running-tests.md`, `schema-per-test.md` |
+| Performance | `performance/` | `QUICKREF-performance-optimization.md` |
+| Configuration | `configuration/` | `configuration.md`, `config-troubleshooting.md` |
+| CLI | `cli/` | `cli.md`, `cli-profiles.md` |
+
+## 🔎 Search Tips
+
+**Search by content:**
+```bash
+# Find all docs mentioning "execution"
+grep -r "execution" docs/
+
+# Search within a specific area
+grep -r "webhook" docs/webhooks/
+```
+
+**Search by filename:**
+```bash
+# Find all architecture docs
+find docs/architecture/ -name "*.md"
+
+# Find testing guides
+find docs/testing/ -name "*.md"
+```
+
+**Use the AGENTS.md index:**
+```bash
+# View minified documentation index
+cat AGENTS.md
+
+# Regenerate after adding new docs
+make generate-agents-index
+```
+
+## 📖 Documentation Conventions
+
+### File Naming
+- Use lowercase with hyphens: `my-feature-guide.md`
+- Prefix with category when helpful: `api-actions.md`, `testing-authentication.md`
+- Use descriptive names: `workflow-execution-engine.md` not `wf-exec.md`
+
+### Content Structure
+Most documentation files follow this structure:
+1. **Overview** - What this document covers
+2. **Key Concepts** - Important terminology and concepts
+3. **How-To** - Step-by-step instructions
+4. **Examples** - Code/config examples
+5. **Troubleshooting** - Common issues and solutions
+6. **References** - Links to related docs
+
+### Cross-Referencing
+Use relative links to reference other docs:
+```markdown
+See [Authentication Guide](../authentication/authentication.md) for details.
+```
+
+## 🤝 Contributing Documentation
+
+### Adding New Docs
+1. Choose the appropriate subdirectory
+2. Follow naming conventions
+3. Include frontmatter if using a doc generator
+4. Add cross-references to related docs
+5. Run `make generate-agents-index` to update the index
+
+### Updating Existing Docs
+1. Keep the overall structure intact
+2. Add new sections at the end if needed
+3. Update the table of contents if present
+4. Check for broken links
+
+### Work Summaries
+Daily work and session notes go in `work-summary/`, not here:
+- `work-summary/sessions/` - Daily work logs
+- `work-summary/status/` - Status updates
+- `work-summary/phases/` - Phase completion summaries
+
+## 🔗 External Resources
+
+- **GitHub Repository**: [attune](https://github.com/yourusername/attune)
+- **Issue Tracker**: GitHub Issues
+- **Discussions**: GitHub Discussions
+
+## 📝 Documentation Organization
+
+For details on the documentation organization system, see [Documentation Organization](development/documentation-organization.md).
+
+This explains:
+- Why each directory exists
+- What belongs where
+- How to maintain the structure
+- Reorganization history
+
+## 💡 Tips
+
+- **Start broad, go deep**: Begin with guides and overviews, then dive into specific topics
+- **Check examples**: The `examples/` directory has working configurations
+- **Use grep**: Full-text search is your friend for finding specific topics
+- **Update AGENTS.md**: After adding docs, regenerate with `make generate-agents-index`
+
+---
+
+*Last updated: 2026-01-30*
+*Documentation files: 100+*
+*Categories: 16*