attune/docs

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 - Get up and running quickly
• Workspace Setup - Set up your development environment
• Configuration Guide - Configure Attune services

Core Concepts

• Architecture Overview - System design and service architecture
• Workflow Engine - How workflows are executed
• Pack System - Understanding automation packs
• Sensors & Triggers - Event monitoring and triggering

Development

• API Documentation - REST API endpoint reference
• CLI Reference - Command-line interface guide
• Testing Guide - How to run and write tests
• Authentication - Auth mechanisms and security

Operations

• Production Deployment - Deploy to production
• Operations Runbook - Troubleshooting and maintenance
• Performance Optimization - 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
2. Read the Quick Start Guide
3. Review Architecture Overview
4. Learn about Testing

I'm building a pack:

1. Read Pack Structure
2. Check Examples
3. Review Pack Testing Framework
4. See Core Pack Integration

I'm creating workflows:

1. Start with Workflow Quickstart
2. Learn Workflow Orchestration
3. Understand Rule Parameter Mapping
4. Review Execution Hierarchy

I'm deploying to production:

1. Read Production Deployment
2. Review Configuration Guide
3. Check Security Review
4. Study Operations Runbook

I'm using the API:

1. Browse API Documentation
2. Check OpenAPI Spec
3. Learn Authentication
4. Review endpoint-specific guides (e.g., Actions)

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:

# Find all docs mentioning "execution"
grep -r "execution" docs/

# Search within a specific area
grep -r "webhook" docs/webhooks/

Search by filename:

# Find all architecture docs
find docs/architecture/ -name "*.md"

# Find testing guides
find docs/testing/ -name "*.md"

Use the AGENTS.md index:

# 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:

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
• Issue Tracker: GitHub Issues
• Discussions: GitHub Discussions

📝 Documentation Organization

For details on the documentation organization system, see Documentation Organization.

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