Add comprehensive IOM documentation with modular structure

docs/README.md

@@ -1,127 +1,134 @@
 # Indigo Plugin Development Documentation
 
-**Streamlined, optimized documentation for building Indigo plugins.**
+Optimized documentation for building Indigo plugins.
 
----
-
-## 🚀 Start Here
+## Start Here
 
 ### New to Indigo Plugin Development?
 
 **[Quick Start Guide](quick-start.md)** - Create your first plugin in minutes
-- Setup and prerequisites
-- Hello World plugin walkthrough
-- Plugin structure explained
-- Common beginner mistakes
 
----
+## Documentation Structure
+
+| Section | Purpose |
+|---------|---------|
+| [Concepts](concepts/) | Plugin lifecycle, devices, events, preferences |
+| [API Reference](api/) | Indigo Object Model reference |
+| [Patterns](patterns/) | Implementation patterns and best practices |
+| [Examples](examples/) | SDK example plugin catalog |
+| [Troubleshooting](troubleshooting/) | Common issues and solutions |
+
+## Quick Navigation by Use Case
+
+### "How do I create a device?"
+
+1. **Start**: [Concepts → Devices](concepts/devices.md) - Device types, Devices.xml, ConfigUI
+2. **API details**: [API → IOM → Devices](api/iom/devices.md) - Device class properties/methods
+3. **Example**: [SDK Examples Guide](examples/sdk-examples-guide.md)
+
+### "What device properties/methods exist?"
+
+→ [API → IOM → Devices](api/iom/devices.md)
+
+### "How do I handle device lifecycle?"
 
-## 📖 Core Documentation
+→ [Concepts → Plugin Lifecycle](concepts/plugin-lifecycle.md#device-lifecycle-callbacks)
 
-### [Concepts](concepts/)
-**Essential architectural concepts**
-- **[Plugin Lifecycle](concepts/plugin-lifecycle.md)** - `__init__()`, `startup()`, `shutdown()`, concurrent threads
-- **[Device Development](concepts/devices.md)** - Device types, states, configuration UIs
+### "How do I update device state?"
 
-### [API Reference](api/)
-**Complete API documentation**
-- **[Indigo Object Model](api/indigo-object-model.md)** - Devices, variables, server objects, constants
+→ [Patterns → API Patterns](patterns/api-patterns.md#device-state-updates)
 
-### [Examples](examples/)
-**16 official SDK example plugins + patterns**
-- **[SDK Examples Guide](examples/sdk-examples-guide.md)** - Complete catalog of all examples
-- Device types, integrations, hardware protocols
+### "How do I save plugin preferences?"
 
-### [Troubleshooting](troubleshooting/)
-**Common issues and solutions**
-- **[Common Issues](troubleshooting/common-issues.md)** - Debugging guide with solutions
+→ [Concepts → Plugin Preferences](concepts/plugin-preferences.md)
 
-### [Patterns](patterns/)
-**Implementation patterns** (coming soon)
-- API integration, polling, error handling, configuration UI
+### "How do I create custom trigger events?"
 
----
+→ [Concepts → Custom Events](concepts/events.md)
 
-## 🎯 Quick Navigation
+### "How do I iterate/filter devices?"
 
-### I want to...
+→ [API → IOM → Filters](api/iom/filters.md)
 
-| Task | Go To |
-|------|-------|
-| Create my first plugin | [Quick Start](quick-start.md) |
-| Understand plugin lifecycle | [Concepts → Plugin Lifecycle](concepts/plugin-lifecycle.md) |
-| Create devices | [Concepts → Devices](concepts/devices.md) |
-| Look up API methods | [API → Indigo Object Model](api/indigo-object-model.md) |
-| Find code examples | [Examples → SDK Guide](examples/sdk-examples-guide.md) |
-| Debug an error | [Troubleshooting → Common Issues](troubleshooting/common-issues.md) |
+### "How does replaceOnServer work?"
 
-### By Device Type
+→ [API → IOM → Architecture](api/iom/architecture.md)
+
+### "How do I subscribe to changes?"
+
+→ [API → IOM → Subscriptions](api/iom/subscriptions.md)
+
+### "What constants/icons are available?"
+
+→ [API → IOM → Constants](api/iom/constants.md)
+
+## By Device Type
 
 | Device | Example |
 |--------|---------|
-| Custom device with unique states | [Example Device - Custom](examples/sdk-examples-guide.md#example-device---custom) |
+| Custom device | [Example Device - Custom](examples/sdk-examples-guide.md#example-device---custom) |
 | Lights/switches | [Example Device - Relay/Dimmer](examples/sdk-examples-guide.md#example-device---relay-and-dimmer) |
 | Thermostat | [Example Device - Thermostat](examples/sdk-examples-guide.md#example-device---thermostat) |
 | Sensors | [Example Device - Sensor](examples/sdk-examples-guide.md#example-device---sensor) |
-| Web API/Dashboard | [Example HTTP Responder](examples/sdk-examples-guide.md#example-http-responder) |
-
----
-
-## 📦 What's Included
-
-- ✅ **Comprehensive guides** - Step-by-step tutorials and references
-- ✅ **16 official SDK examples** - Production-quality code in `../sdk-examples/`
-- ✅ **API reference** - Complete Indigo Object Model documentation
-- ✅ **Troubleshooting** - Common issues and solutions
-- ✅ **Code snippets** - Ready-to-use templates in `../snippets/`
+| Web API | [Example HTTP Responder](examples/sdk-examples-guide.md#example-http-responder) |
 
----
+## For Claude (Context Optimization)
 
-## 🔍 For Claude (AI Assistant)
+### File Loading Strategy
 
-**Context optimization guidelines**:
+**Concepts vs API**: These are complementary, not duplicates:
+- `concepts/devices.md` → Design (Devices.xml, ConfigUI, validation)
+- `api/iom/devices.md` → Reference (class properties, methods)
 
-**Load these files (all < 12KB)**:
-- `quick-start.md` - Complete getting started guide
-- `concepts/plugin-lifecycle.md` - Lifecycle reference
-- `concepts/devices.md` - Device development
-- `api/indigo-object-model.md` - API reference
-- `examples/sdk-examples-guide.md` - Example catalog
-- `troubleshooting/common-issues.md` - Troubleshooting
+**Load based on question type**:
 
-**Never load all at once**:
-- `../sdk-examples/` - 16 complete plugins (1.3MB) - Load individually only
+| User Question | Load |
+|---------------|------|
+| "How do I create a device?" | `concepts/devices.md` |
+| "What properties does a device have?" | `api/iom/devices.md` |
+| "How do I update state?" | `patterns/api-patterns.md` |
+| "How do I save settings?" | `concepts/plugin-preferences.md` |
+| "How do I create trigger events?" | `concepts/events.md` |
+| "Show me an example" | Specific example from `sdk-examples/` |
 
-**Strategy**:
-1. Check `examples/sdk-examples-guide.md` to find relevant example
-2. Use Read tool to load ONLY that specific example
-3. Don't load multiple examples simultaneously
+### Modular IOM Files
 
----
+The IOM documentation is split into focused files (~4KB each):
 
-## 📚 External Resources
+| Topic | File |
+|-------|------|
+| Core architecture | `api/iom/architecture.md` |
+| Device classes | `api/iom/devices.md` |
+| Trigger classes | `api/iom/triggers.md` |
+| Iteration filters | `api/iom/filters.md` |
+| Change subscriptions | `api/iom/subscriptions.md` |
+| Constants/icons | `api/iom/constants.md` |
+| indigo.Dict/List | `api/iom/containers.md` |
+| Utility functions | `api/iom/utilities.md` |
 
-- [Official Plugin Guide](https://www.indigodomo.com/docs/plugin_guide) - Complete development guide
-- [Object Model Reference](https://www.indigodomo.com/docs/object_model_reference) - API reference
-- [Scripting Tutorial](https://www.indigodomo.com/docs/plugin_scripting_tutorial) - Learn by examples
-- [Developer Forum](https://forums.indigodomo.com/viewforum.php?f=18) - Community support
+### Concept Files
 
----
+| Topic | File |
+|-------|------|
+| Plugin lifecycle | `concepts/plugin-lifecycle.md` |
+| Device development | `concepts/devices.md` |
+| Plugin preferences | `concepts/plugin-preferences.md` |
+| Custom events | `concepts/events.md` |
 
-## 🤝 Contributing
+Load only the specific topic needed.
 
-This documentation is community-maintained!
+### Never Load All at Once
 
-Found an issue or want to add documentation?
-- See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines
-- Open an issue or pull request
-- Join discussions on GitHub
+- `sdk-examples/` - 16 complete plugins (1.3MB) - Load individually
+- Don't load all IOM files together - load by topic
 
----
+## External Resources
 
-## ℹ️ Version Information
+- [Official Plugin Guide](https://wiki.indigodomo.com/doku.php?id=indigo_2025.1_documentation:plugin_guide)
+- [Object Model Reference](https://wiki.indigodomo.com/doku.php?id=indigo_2025.1_documentation:object_model_reference)
+- [Developer Forum](https://forums.indigodomo.com/viewforum.php?f=18)
 
-- **Current**: Indigo 2023.2+ (Python 3.10+)
-- **Legacy**: 2022.x and earlier (Python 2.7, not recommended)
+## Version Information
 
-All documentation focuses on current versions. For migration help, see [`../reference/Python3-Migration-Guide.md`](../reference/Python3-Migration-Guide.md).
+- **Current**: Indigo 2025.1+ (Python 3.10+)
+- **Migration**: See [`../reference/Python3-Migration-Guide.md`](../reference/Python3-Migration-Guide.md)