Canonical docs restructure — vendor Indigo 2025.2, fix fabricated facts (v2.0.0)

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "indigo",
       "source": "./",
       "description": "Indigo home automation development toolkit \u2014 plugin development, API integration, and control page building",
-      "version": "1.9.5",
+      "version": "2.0.0",
       "repository": "https://github.com/simons-plugins/indigo-claude-plugin",
       "license": "MIT",
       "keywords": [

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "indigo",
-  "version": "1.9.5",
+  "version": "2.0.0",
   "description": "Indigo home automation development toolkit \u2014 plugin development, API integration, and control page building",
   "repository": "https://github.com/simons-plugins/indigo-claude-plugin"
 }

README.md

@@ -33,19 +33,19 @@ Skills activate automatically when working on relevant files:
 
 ## Documentation
 
-- `docs/plugin-dev/` — Plugin development guides, concepts, API reference
-- `docs/api/` — WebSocket and HTTP API integration docs
+- `reference/canonical/` — **Indigo docs vendored verbatim** (generated by `tools/refresh_canonical.py`, pinned to 2025.2); the source of truth for all reference facts. Start at `reference/canonical/INDEX.md`.
+- `docs/plugin-dev/` — Workspace on-ramps & patterns (quick-start, lifecycle, testing, troubleshooting)
 - `docs/control-pages/` — Control page schema, images, layouts, export
-- `reference/` — SDK reference documents and migration guide
+- `reference/` — SDK reference + legacy Python 2→3 porting guide
 - `sdk-examples/` — 16 complete SDK example plugins
 - `snippets/` — Plugin templates
 - `examples/` — Control page .textClipping examples
-- `tools/` — Utility scripts (e.g., create_clipping.py)
+- `tools/` — Utility scripts (`refresh_canonical.py`, `create_clipping.py`)
 
 ## Related
 
 - [Indigo](https://www.indigodomo.com) — Home automation platform for macOS
-- [Plugin Developer's Guide](https://wiki.indigodomo.com/doku.php?id=indigo_2025.1_documentation:plugin_guide)
+- [Plugin Development (official docs)](https://docs.indigodomo.com/2025.2/plugin-dev/)
 - [Developer Forum](https://forums.indigodomo.com/viewforum.php?f=18)
 
 ## License

commands/api.md

@@ -16,53 +16,59 @@ Expert assistant for building applications that integrate with Indigo home autom
 
 ## CRITICAL: Context Optimization Strategy
 
-This command provides focused API documentation (~50KB). Load selectively based on query type.
-
-### All Files (Load by Topic)
-
-| File | Size | Use For |
-|------|------|---------|
-| `docs/api/README.md` | 5KB | Navigation and quick lookup |
-| `docs/api/overview.md` | 7KB | WebSocket vs HTTP decision |
-| `docs/api/authentication.md` | 7KB | API key setup and security |
-| `docs/api/websocket-api.md` | 10KB | WebSocket API reference |
-| `docs/api/http-api.md` | 11KB | HTTP/REST API reference |
-| `docs/api/device-commands.md` | 12KB | Complete command reference |
-
-**Total**: ~52KB across 6 files - load selectively.
+Reference docs are vendored verbatim from Indigo's published docs under `reference/canonical/`
+(generated by `tools/refresh_canonical.py`, pinned to Indigo 2025.2). Load only the page a query
+needs — never the whole tree. Start from `reference/canonical/INDEX.md` if unsure. All
+`reference/canonical/…` paths are relative to `${CLAUDE_PLUGIN_ROOT}` (this plugin), not the user's project.
+
+### Canonical API Files (Load by Topic)
+
+| File | Use For |
+|------|---------|
+| `reference/canonical/api.md` | Integration-APIs overview, WebSocket-vs-HTTP choice |
+| `reference/canonical/api/http.md` | HTTP endpoints, authentication, curl/Python examples |
+| `reference/canonical/api/messages.md` | Message format — commands, events, error responses |
+| `reference/canonical/api/websocket.md` | WebSocket feeds, `refresh`, add/patch/delete handling |
+| `reference/canonical/api/webhooks.md` | Receiving webhooks from external services |
+| `reference/canonical/api/rest-migration.md` | Converting legacy REST API calls to the HTTP API |
 
 ## Query Routing Guide
 
 ### General Integration Questions
 
 **"Build iOS/web app" / "Get started with Indigo API"**
-1. Read `docs/api/overview.md` (WebSocket vs HTTP decision)
-2. Read `docs/api/authentication.md` (API key setup)
+1. Read `reference/canonical/api.md` (WebSocket vs HTTP decision)
+2. Read `reference/canonical/api/http.md` → Authentication section (API key setup)
 
 **"Should I use WebSocket or HTTP?"**
-1. Read `docs/api/overview.md`
+1. Read `reference/canonical/api.md`
 
 ### WebSocket API Questions
 
 **"Monitor devices in real-time" / "WebSocket API" / "Live updates"**
-1. Read `docs/api/websocket-api.md`
-2. If auth needed: Read `docs/api/authentication.md`
+1. Read `reference/canonical/api/websocket.md`
+2. For command/event message shapes: Read `reference/canonical/api/messages.md`
 
 ### HTTP API Questions
 
-**"Control via REST API" / "HTTP endpoints" / "curl examples"**
-1. Read `docs/api/http-api.md`
-2. If auth needed: Read `docs/api/authentication.md`
+**"Control via HTTP" / "REST" / "HTTP endpoints" / "curl examples"**
+1. Read `reference/canonical/api/http.md`
+2. For the command message shapes: Read `reference/canonical/api/messages.md`
 
 ### Command Reference Questions
 
 **"What commands can I send?" / "Device commands" / "Control devices"**
-1. Read `docs/api/device-commands.md`
+1. Read `reference/canonical/api/messages.md` (device/variable/action/thermostat command messages)
+
+### Webhook Questions
+
+**"Receive a webhook" / "trigger from external service" / "doorbell/location webhook"**
+1. Read `reference/canonical/api/webhooks.md`
 
 ### Authentication Questions
 
 **"Setup API keys" / "Authentication" / "Security"**
-1. Read `docs/api/authentication.md`
+1. Read `reference/canonical/api/http.md` → Authentication section
 
 ### Device Capability Catalog
 
@@ -88,28 +94,27 @@ If the user has the `indigo-device-catalog` installed (check for `../indigo-devi
 
 **User**: "I want to build an iOS app that shows my Indigo devices in real-time"
 
-1. Read `docs/api/overview.md` - Explain WebSocket is best for real-time
-2. Read `docs/api/authentication.md` - Show API key setup
-3. Read `docs/api/websocket-api.md` - Provide connection example
-4. Read `docs/api/device-commands.md` - Show control commands
+1. Read `reference/canonical/api.md` - Explain WebSocket is best for real-time
+2. Read `reference/canonical/api/http.md` → Authentication - Show API key setup
+3. Read `reference/canonical/api/websocket.md` - Provide feed connection + `refresh` example
+4. Read `reference/canonical/api/messages.md` - Show control command messages
 
 ### Building a Web Dashboard
 
 **User**: "Create a web dashboard to control my lights"
 
-1. Read `docs/api/overview.md` - Suggest HTTP for initial load, WebSocket for updates
-2. Read `docs/api/authentication.md` - API key setup
-3. Read `docs/api/http-api.md` - Show GET /devices endpoint
-4. Read `docs/api/websocket-api.md` - Real-time updates
-5. Read `docs/api/device-commands.md` - Control commands
+1. Read `reference/canonical/api.md` - Suggest HTTP for initial load, WebSocket for updates
+2. Read `reference/canonical/api/http.md` → Authentication - API key setup
+3. Read `reference/canonical/api/http.md` - Show `GET /v2/api/indigo.devices`
+4. Read `reference/canonical/api/websocket.md` - Real-time updates
+5. Read `reference/canonical/api/messages.md` - Control command messages
 
 ### Simple Automation Script
 
 **User**: "I want to turn off all lights via curl script"
 
-1. Read `docs/api/http-api.md` - Show curl examples
-2. Read `docs/api/authentication.md` - Header authentication
-3. Read `docs/api/device-commands.md` - turnOff command
+1. Read `reference/canonical/api/http.md` - Show curl examples + `POST /v2/api/command`
+2. Read `reference/canonical/api/messages.md` - `indigo.device.turnOff` message
 
 ## Key Concepts
 
@@ -125,43 +130,46 @@ If the user has the `indigo-device-catalog` installed (check for `../indigo-devi
 
 ### Command Messages Across Transports
 
-The APIs share most command messages (documented in `device-commands.md`), though some commands may be specific to one transport:
-- WebSocket sends commands via persistent connection
-- HTTP sends commands via POST to `/v2/api/command`
+Both transports share the same command envelope (documented in `reference/canonical/api/messages.md`):
+`{"message": "indigo.<namespace>.<command>", "objectId": <id>, "parameters": {...}}`. There is no
+`PUT`/per-object write endpoint and no `?detail` flag — GET returns full objects.
+- WebSocket sends commands over a persistent feed connection
+- HTTP sends commands via `POST /v2/api/command`
 
 ### Authentication
 
-Both APIs use **API Keys** or **Local Secrets**:
-- API Keys: Created in Indigo Account portal, per-app, revocable
-- Local Secrets: Shared secret in Indigo preferences, local network only
+Both APIs accept **HTTP Digest, API Keys, or local secrets**:
+- **API Keys** (recommended): managed in Indigo Account → **Authorizations**, per-app, revocable. Sent as `Authorization: Bearer <key>` or `?api-key=<key>`. Can control devices but not modify the database.
+- **Local secrets**: a special kind of API key that doesn't route through the reflector (LAN/same-machine); used identically as a Bearer token.
+- **HTTP Basic** and the **old REST API** are deprecated.
 
 ## Common Use Cases
 
 ### iOS/Android App
 - WebSocket API for real-time device status
 - Send commands via WebSocket
-- Files: `websocket-api.md`, `authentication.md`, `device-commands.md`
+- Files: `api/websocket.md`, `api/http.md` (auth), `api/messages.md`
 
 ### Web Dashboard
 - HTTP for initial page load
 - WebSocket for live updates
-- Files: `http-api.md`, `websocket-api.md`, `device-commands.md`
+- Files: `api/http.md`, `api/websocket.md`, `api/messages.md`
 
 ### Automation Script
 - HTTP API with curl/requests
 - Simple polling or command execution
-- Files: `http-api.md`, `device-commands.md`
+- Files: `api/http.md`, `api/messages.md`
 
 ### Third-Party Integration
-- Webhooks receive HTTP POST
+- Receive external events via Indigo webhooks
 - WebSocket for monitoring Indigo events
-- Files: `http-api.md`, `websocket-api.md`
+- Files: `api/webhooks.md`, `api/http.md`, `api/websocket.md`
 
 ## External Resources
 
-- [Official API Documentation](https://wiki.indigodomo.com/doku.php?id=indigo_2025.1_documentation:api)
+- [Integration APIs (official docs)](https://docs.indigodomo.com/2025.2/api/)
 - [Indigo Forum](https://forums.indigodomo.com/)
-- [Indigo Account Portal](https://www.indigodomo.com/account/) - Create API keys
+- [Indigo Account → Authorizations](https://www.indigodomo.com/account/authorizations) - Create/revoke API keys
 
 ## Related Commands