Updates for Documentation

.claude/commands/ignition-configure.md

@@ -0,0 +1,191 @@
+# ignition-configure
+
+Use this skill whenever the user asks you to configure, inspect, or manage the Ignition gateway
+via the HTTP API — adding connections, importing tags, checking status, managing modules, etc.
+
+## Setup: Resolve token and host
+
+1. Read `docker/.env` for `GATEWAY_HOSTNAME` (default: `localhost:8088`)
+2. Read `~/.config/ignition-dev/secrets.env` for `IGNITION_API_TOKEN` (format: `name:token`)
+   - Fall back to asking the user if not found
+3. Set shell variables for all subsequent calls:
+
+```bash
+TOKEN=$(grep IGNITION_API_TOKEN ~/.config/ignition-dev/secrets.env | cut -d= -f2)
+GW="http://$(grep GATEWAY_HOSTNAME docker/.env | cut -d= -f2- || echo 'localhost:8088')"
+HEADER="X-Ignition-API-Token: $TOKEN"
+```
+
+## Step 1: Confirm gateway is reachable
+
+Always check before making changes:
+
+```bash
+curl -s -H "$HEADER" $GW/data/api/v1/overview | python3 -m json.tool
+```
+
+If this fails, check `docker compose ps` and gateway logs before proceeding.
+
+## Step 2: Inspect current state
+
+Before creating or modifying anything, read what's already there:
+
+```bash
+# Gateway connections overview
+curl -s -H "$HEADER" $GW/data/api/v1/overview/connections | python3 -m json.tool
+
+# Any critical problems
+curl -s -H "$HEADER" $GW/data/api/v1/overview/problems | python3 -m json.tool
+```
+
+---
+
+## Common Configuration Tasks
+
+### Add a database connection
+
+```bash
+# First — describe the schema to see available props
+curl -s -H "$HEADER" $GW/data/api/v1/resources/type/ignition/database-connection | python3 -m json.tool
+
+# Create
+curl -s -X POST -H "$HEADER" -H "Content-Type: application/json" \
+  $GW/data/api/v1/resources/ignition/database-connection \
+  -d '{
+    "name": "ignition_db",
+    "enabled": true,
+    "props": {
+      "ConnectURL": "jdbc:postgresql://postgres:5432/ignition",
+      "Username": "ignition",
+      "Password": "'"$POSTGRES_PASSWORD"'"
+    }
+  }'
+
+# Verify
+curl -s -H "$HEADER" $GW/data/api/v1/resources/find/ignition/database-connection/ignition_db | python3 -m json.tool
+```
+
+### Add an OPC connection (Modbus or AB PLC)
+
+```bash
+# Describe schema first
+curl -s -H "$HEADER" $GW/data/api/v1/resources/type/ignition/opc-connection | python3 -m json.tool
+
+# Create
+curl -s -X POST -H "$HEADER" -H "Content-Type: application/json" \
+  $GW/data/api/v1/resources/ignition/opc-connection \
+  -d '{
+    "name": "modbus-sim-pumps",
+    "enabled": true,
+    "props": {
+      "EndpointUrl": "opc.tcp://modbus-sim-pumps:4840",
+      "SecurityPolicy": "None",
+      "MessageSecurity": "None"
+    }
+  }'
+```
+
+### Add an OPC-UA device
+
+```bash
+# List available device types
+curl -s -H "$HEADER" $GW/data/api/v1/resources/type/com.inductiveautomation.opcua/device | python3 -m json.tool
+
+# Create
+curl -s -X POST -H "$HEADER" -H "Content-Type: application/json" \
+  $GW/data/api/v1/resources/com.inductiveautomation.opcua/device \
+  -d '{ "name": "MyDevice", "enabled": true, "props": { ... } }'
+```
+
+### Modify an existing resource
+
+Always GET first to obtain the current `signature`:
+
+```bash
+# Step 1: Get current config and signature
+RESOURCE=$(curl -s -H "$HEADER" $GW/data/api/v1/resources/find/ignition/database-connection/ignition_db)
+SIG=$(echo $RESOURCE | python3 -c "import json,sys; print(json.load(sys.stdin)['signature'])")
+
+# Step 2: Modify (include signature in body)
+curl -s -X PUT -H "$HEADER" -H "Content-Type: application/json" \
+  $GW/data/api/v1/resources/ignition/database-connection \
+  -d "{\"name\": \"ignition_db\", \"signature\": \"$SIG\", \"props\": { ... }}"
+```
+
+### Import tags
+
+```bash
+# Export first (to see current state or create a template)
+curl -s -H "$HEADER" \
+  "$GW/data/api/v1/tags/export?provider=default&path=Devices&recursive=true" \
+  -o tags-export.json
+
+# Import (collisionPolicy: Abort | Overwrite | Ignore | MergeOverwrite | MergeIgnore)
+curl -s -X POST -H "$HEADER" -H "Content-Type: application/json" \
+  "$GW/data/api/v1/tags/import?provider=default&path=Devices&collisionPolicy=MergeOverwrite" \
+  -d @tags-export.json
+```
+
+### Download a backup
+
+```bash
+curl -s -H "$HEADER" \
+  "$GW/data/api/v1/backup" \
+  -o "gateway-$(date +%Y%m%d-%H%M%S).gwbk"
+```
+
+---
+
+## After Making Changes — Scan to Sync
+
+After editing files in `ignition/project/`:
+```bash
+curl -s -X POST -H "$HEADER" $GW/data/api/v1/scan/projects
+```
+
+After editing files in `docker/gw-config/`:
+```bash
+curl -s -X POST -H "$HEADER" $GW/data/api/v1/scan/config
+```
+
+Check scan status:
+```bash
+curl -s -H "$HEADER" $GW/data/api/v1/scan/projects | python3 -m json.tool
+curl -s -H "$HEADER" $GW/data/api/v1/scan/config | python3 -m json.tool
+```
+
+---
+
+## Gateway Restart ⚠️
+
+**Never restart without explicit user confirmation.** Check for pending tasks first:
+
+```bash
+# Check what requires a restart
+curl -s -H "$HEADER" $GW/data/api/v1/restart-tasks/pending | python3 -m json.tool
+
+# Restart (confirm=true required — disruptive to all active sessions)
+curl -s -X POST -H "$HEADER" "$GW/data/api/v1/restart-tasks/restart?confirm=true"
+```
+
+---
+
+## Logs and Diagnostics
+
+```bash
+# Recent warnings and errors
+curl -s -H "$HEADER" "$GW/data/api/v1/logs?minLevel=WARN&limit=50" | python3 -m json.tool
+
+# Logs for a specific logger
+curl -s -H "$HEADER" "$GW/data/api/v1/logs?logger=IgnitionGateway&limit=25" | python3 -m json.tool
+
+# Audit trail
+curl -s -H "$HEADER" "$GW/data/api/v1/audit/log/Audit?limit=25" | python3 -m json.tool
+```
+
+---
+
+## Reference
+
+Full API reference: [ignition/ignition-api.md](../../ignition/ignition-api.md)
+Live spec: `http://localhost:8088/openapi`