From c56e15a5f8206e875c384b49751c8b6dcccf0926 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 3 Dec 2025 18:32:50 +0000
Subject: [PATCH] Add documentation for node tag import feature

README.md:
- Add "Node Tags" section with comprehensive documentation
- Document CLI usage: meshcore-hub collector import-tags
- Document Docker Compose usage: docker compose --profile import-tags
- Document JSON format with field descriptions
- Document import options (--no-create-nodes)
- Document data directory structure for Docker
- Document tag management via REST API (CRUD operations)

AGENTS.md:
- Add tag_import.py to project structure
- Update example/data structure with collector/web subdirectories
- Update data directory structure documentation
---
 AGENTS.md |  8 ++++-
 README.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index c4df373..489c66a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -249,6 +249,7 @@ meshcore-hub/
 │   ├── collector/
 │   │   ├── cli.py
 │   │   ├── subscriber.py     # MQTT subscriber
+│   │   ├── tag_import.py     # Tag import from JSON
 │   │   ├── handlers/         # Event handlers
 │   │   └── webhook.py        # Webhook dispatcher
 │   ├── api/
@@ -278,8 +279,13 @@ meshcore-hub/
 │   └── mosquitto.conf        # MQTT broker configuration
 ├── example/
 │   └── data/
-│       └── members.json      # Example network members data
+│       ├── collector/
+│       │   └── tags.json     # Example node tags data
+│       └── web/
+│           └── members.json  # Example network members data
 ├── data/                     # Runtime data (gitignored)
+│   ├── collector/            # Collector data (tags.json)
+│   └── web/                  # Web data (members.json)
 ├── Dockerfile                # Docker build configuration
 ├── docker-compose.yml        # Docker Compose services (gitignored)
 └── docker-compose.yml.example  # Docker Compose template
diff --git a/README.md b/README.md
index d6f3d29..f686855 100644
--- a/README.md
+++ b/README.md
@@ -231,6 +231,9 @@ meshcore-hub interface --mode sender --mock  # Use mock device
 # Collector component
 meshcore-hub collector --database-url sqlite:///./data.db
 
+# Import node tags from JSON file
+meshcore-hub collector import-tags /path/to/tags.json
+
 # API component
 meshcore-hub api --host 0.0.0.0 --port 8000
 
@@ -243,6 +246,102 @@ meshcore-hub db downgrade    # Rollback one migration
 meshcore-hub db current      # Show current revision
 ```
 
+## Node Tags
+
+Node tags allow you to attach custom metadata to nodes (e.g., location, role, owner). Tags are stored in the database and returned with node data via the API.
+
+### Importing Tags from JSON
+
+Tags can be bulk imported from a JSON file:
+
+```bash
+# Native CLI
+meshcore-hub collector import-tags /path/to/tags.json
+
+# With Docker Compose
+docker compose --profile import-tags run --rm import-tags
+```
+
+### Tags JSON Format
+
+```json
+{
+  "tags": [
+    {
+      "public_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+      "key": "location",
+      "value": "San Francisco, CA",
+      "value_type": "string"
+    },
+    {
+      "public_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+      "key": "altitude",
+      "value": "150",
+      "value_type": "number"
+    }
+  ]
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `public_key` | Yes | 64-character hex public key of the node |
+| `key` | Yes | Tag name (max 100 characters) |
+| `value` | No | Tag value (stored as text) |
+| `value_type` | No | Type hint: `string`, `number`, `boolean`, or `coordinate` (default: `string`) |
+
+### Import Options
+
+```bash
+# Create nodes if they don't exist (default behavior)
+meshcore-hub collector import-tags tags.json
+
+# Skip tags for nodes that don't exist
+meshcore-hub collector import-tags --no-create-nodes tags.json
+```
+
+### Data Directory Structure
+
+For Docker deployments, organize your data files:
+
+```
+data/
+├── collector/
+│   └── tags.json      # Node tags for import
+└── web/
+    └── members.json   # Network members list
+```
+
+Example files are provided in `example/data/`.
+
+### Managing Tags via API
+
+Tags can also be managed via the REST API:
+
+```bash
+# List tags for a node
+curl http://localhost:8000/api/v1/nodes/{public_key}/tags
+
+# Create a tag (requires admin key)
+curl -X POST \
+  -H "Authorization: Bearer <API_ADMIN_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{"key": "location", "value": "Building A"}' \
+  http://localhost:8000/api/v1/nodes/{public_key}/tags
+
+# Update a tag
+curl -X PUT \
+  -H "Authorization: Bearer <API_ADMIN_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{"value": "Building B"}' \
+  http://localhost:8000/api/v1/nodes/{public_key}/tags/location
+
+# Delete a tag
+curl -X DELETE \
+  -H "Authorization: Bearer <API_ADMIN_KEY>" \
+  http://localhost:8000/api/v1/nodes/{public_key}/tags/location
+```
+
 ## API Documentation
 
 When running, the API provides interactive documentation at: