docs(timestream-influxdb-mcp-server): Add schema design, query, and ingestion guidance

src/timestream-for-influxdb-mcp-server/power/POWER.md

@@ -34,34 +34,52 @@ This Power enables you to deploy and operate Timestream for InfluxDB instances a
 	- ALWAYS load when there is ambiguity in InfluxDB versions
 	- ALWAYS load on migrations between InfluxDB 2 and 3
 
-- [ ] `line-protocol.md` - Explains InfluxData's line protocol specification, with best practices and limitations
-	- SHOULD load when working with line protocol
-
 - [ ] `glossary.md` - Glossary of terms related to InfluxDB
 	- SHOULD load when there is vagueness in terminology or overlapping concepts
 
-
 - [ ] `troubleshooting.md` - Common errors while working with InfluxDB and how to solve them
 	- SHOULD load on errors or when debugging
 
 - `influxdb3/`
-	- [ ] `developer-guide.md` - Contains guide for managing instances/clusters, queries/writes, example workflows
+	- [ ] `development-guide.md` - Contains guide for managing instances/clusters, queries/writes, example workflows
 	- [ ] `query-guide.md` - Query examples (SQL, InfluxQL)
 	- [ ] `troubleshooting.md` - Common errors in InfluxDB 3 and how to solve them
 	- [ ] `migrations.md`
+		- ALWAYS load when migrating between InfluxDB versions or products (OSS/Core, Enterprise, or InfluxDB Cloud -> Timestream for InfluxDB 3)
 		- [ ] OSS (Core) -> Timestream for InfluxDB 3
 		- [ ] Core -> Enterprise
 		- [ ] InfluxDB Cloud -> Timestream for InfluxDB 3
 	- [ ] `dashboard-guide.md` - Generate grafana dashboards and visualizations
+		- SHOULD load when building Grafana dashboards or visualizations
+	- [ ] `schema-design.md` - Schema modeling: tables, tags vs. fields, cardinality
+		- ALWAYS load when designing or modifying schema (table/tag/field choices, cardinality planning)
+	- [ ] `ingestion.md` - Data ingestion & writing: line protocol, batching, write endpoints
+		- ALWAYS load when writing data or ingesting via line protocol
+	- [ ] `parameters.md` - InfluxDBv3 Core/Enterprise parameter reference and duration formats
+		- SHOULD load when configuring or tuning cluster/database parameters
+	- [ ] `gotchas.md` - Common gotchas & pain points: batching, cardinality, replica lag, limits
+		- SHOULD load when ingesting at scale or diagnosing performance/limit issues
+	- [ ] `onboarding.md` - Interactive get-started: provision cluster, retrieve token, first write/query
+		- SHOULD load when getting started or provisioning a new cluster
 
 - `influxdb2/`
-	- [ ] `developer-guide.md` - Contains guide for managing instances/clusters, queries/writes, example workflows
+	- [ ] `development-guide.md` - Contains guide for managing instances/clusters, queries/writes, example workflows
 	- [ ] `query-guide.md` - Query examples (Flux, InfluxQL)
 	- [ ] `troubleshooting.md` - Common errors in InfluxDB 2 and how to solve them
-	- [ ] `migrations`
+	- [ ] `migrations.md`
+		- ALWAYS load when migrating to or from Timestream for InfluxDB 2 (OSS -> v2, or v2 -> v3)
 		- [ ] Timestream for InfluxDB (2) -> Timestream for InfluxDB 3
 		- [ ] OSS -> Timestream for InfluxDB (2)
 	- [ ] `dashboard-guide.md` - Generate grafana dashboards and visualizations
+		- SHOULD load when building Grafana dashboards or visualizations
+	- [ ] `schema-design.md` - Schema modeling: buckets/measurements, tags vs. fields, cardinality
+		- ALWAYS load when designing or modifying schema (measurement/tag/field choices, cardinality planning)
+	- [ ] `ingestion.md` - Data ingestion & writing: line protocol, batching, write endpoints
+		- ALWAYS load when writing data or ingesting via line protocol
+	- [ ] `gotchas.md` - Common gotchas & pain points: cardinality, batching, limits
+		- SHOULD load when ingesting at scale or diagnosing performance/limit issues
+	- [ ] `onboarding.md` - Interactive get-started: provisioning through first write and query
+		- SHOULD load when getting started or provisioning a new instance
 
 
 ## Available MCP Tools

src/timestream-for-influxdb-mcp-server/power/steering/glossary.md

@@ -1 +1,98 @@
 # Glossary
+
+Terms used across Amazon Timestream for InfluxDB (v2 and v3). Where a term differs
+between versions, the version is noted. For a fuller treatment of version
+differences, see [influxdb-2-vs-3.md](./influxdb-2-vs-3.md).
+
+## Version & terminology map
+
+InfluxDB 2 (Timestream for InfluxDB) and InfluxDB 3 (Timestream for InfluxDB 3)
+name several concepts differently:
+
+| InfluxDB 2 | InfluxDB 3 | Notes |
+|---|---|---|
+| Organization (`org`) | — (no orgs) | V3 has no organization concept |
+| Bucket | Database (`db`) | Top-level write/query namespace |
+| Measurement | Table | A measurement becomes a table in V3 (auto-created on first write) |
+| Flux / InfluxQL | SQL / InfluxQL | V3 has no Flux; SQL is primary |
+| Token (`Token` prefix) | Token (`Bearer` prefix) | Data-plane auth header differs |
+| Tasks (Flux) | Processing engine (Python) | Scheduled automation |
+| TSM + TSI | Parquet on S3 + DataFusion | Storage + query engine |
+| Port 8086 | Port 8181 | Default endpoint port |
+
+## Data model
+
+- **Line protocol** — InfluxDB's text format for writing data:
+  `measurement,tag=val field=1.0 timestamp`. Unchanged across versions. See
+  [line-protocol.md](./line-protocol.md).
+- **Point** — a single data record: a measurement + tag set + field set + timestamp.
+- **Measurement** (V2) / **Table** (V3) — logical container for points of the same
+  kind (e.g. `cpu`).
+- **Tag** — indexed key/value metadata (e.g. `host=server01`), used for filtering and
+  grouping. High tag cardinality is the main driver of V2 performance limits.
+- **Tag set** — the unique combination of all tag key/values on a point.
+- **Field** — the measured value(s) (e.g. `usage=42.0`). Not indexed. Field type is
+  inferred on first write and then locked.
+- **Field set** — all field key/values on a point.
+- **Timestamp** — the time of a point; default precision is nanoseconds. Always specify
+  precision explicitly to avoid silent shifts.
+- **Series** — a unique combination of measurement + tag set + field key.
+- **Series cardinality** — the number of unique series. V2 (TSM/TSI) degrades above
+  ~10M series; V3 is effectively unbounded.
+
+## Namespaces & auth
+
+- **Organization (org)** — V2-only top-level tenant that groups buckets.
+- **Bucket** — V2 named container for data with a retention period; the write/query
+  target (`bucket`).
+- **Database (db)** — V3 top-level namespace (replaces org/bucket).
+- **Retention period / policy** — how long data is kept before it expires.
+- **Token** — data-plane credential. V2 uses `Authorization: Token <token>`; V3 uses
+  `Authorization: Bearer <token>`. Operator/all-access tokens differ in scope.
+- **Control plane vs data plane** — the control plane (create/manage instances and
+  clusters) uses AWS SigV4/IAM; the data plane (read/write) is authorized only by the
+  engine token (IAM does not gate it).
+
+## Engines & storage
+
+- **TSM (Time-Structured Merge Tree)** — V2's on-disk storage engine.
+- **TSI (Time-Series Index)** — V2's index over tags; large indexes drive memory use
+  and the cardinality limit.
+- **Apache Parquet** — V3's columnar on-disk (S3) file format.
+- **Apache DataFusion** — V3's SQL query engine/optimizer.
+- **Apache Arrow / Arrow Flight SQL** — Arrow is V3's in-memory columnar format; Flight
+  SQL is its high-performance gRPC query protocol.
+- **WAL (write-ahead log)** — durability buffer for recent writes before they are
+  persisted to Parquet.
+- **Compaction** — background merging of files for query efficiency; V3 Enterprise can
+  use a dedicated compactor node.
+- **Last Value Cache (LVC)** — V3 cache of the most recent value per field (fast
+  "last point" lookups).
+- **Distinct Value Cache (DVC)** — V3 cache of unique tag/field values (fast metadata
+  lookups, e.g. template-variable queries).
+
+## Query & automation
+
+- **Flux** — V2's functional data-scripting language (primary in V2; absent in V3).
+- **InfluxQL** — SQL-like legacy language; supported in both V2 and V3 (via a
+  compatibility endpoint).
+- **SQL** — V3's primary query language (DataFusion).
+- **Tasks** — V2 scheduled Flux scripts (downsampling, alerting).
+- **Processing engine** — V3's embedded Python VM that runs plugins on schedule or on
+  WAL-flush events (replaces V2 Tasks).
+- **Telegraf** — InfluxData's plugin-based metrics collection agent; writes line
+  protocol to either version.
+
+## Deployment
+
+- **Instance** — V2 single-node deployment (`create-db-instance`); optionally with a
+  multi-AZ standby (failover only, does not serve reads).
+- **Read-replica cluster** — V2 multi-node deployment that adds read-serving nodes
+  (adds a license fee).
+- **Cluster** — V3's only deployment shape (`create-db-cluster`).
+- **Core (`InfluxDBV3Core`)** — single-node V3 cluster; no dedicated compactor; best for
+  recent data. Uses an open-source binary with more limitations than Enterprise.
+- **Enterprise (`InfluxDBV3Enterprise`)** — multi-node V3 cluster (up to 15 nodes) with
+  role separation; adds a per-node AWS Marketplace license.
+- **Parameter group** — immutable named set of engine parameters; change by creating a
+  new group and reassigning it (which triggers a reboot).

src/timestream-for-influxdb-mcp-server/power/steering/influxdb-2-vs-3.md

@@ -1 +1,129 @@
 # InfluxDB 2 vs 3
+
+Covers the differences between **Timestream for InfluxDB** (the InfluxDB 2.x engine) and **Timestream for InfluxDB 3** (the InfluxDB 3 engine). Load this when there is ambiguity about which version a user is on, or when planning a migration between the two.
+
+## At-a-Glance Comparison
+
+| Aspect | V2 (Timestream for InfluxDB) | V3 (Timestream for InfluxDB 3) |
+|--------|----|----|
+| Underlying engine | InfluxDB OSS 2.x branch (Go) | InfluxDB 3 (Rust) |
+| Storage engine | TSM (Time-Structured Merge Tree) + TSI index | Apache Parquet on object storage |
+| Query engine | InfluxDB built-in | Apache DataFusion |
+| Storage layer | Influx IOPS Included volumes (local, block) | Amazon S3 (object storage) |
+| Namespace | Organization → Bucket | Database → Table (no orgs) |
+| Query language | Flux (primary), InfluxQL | SQL (primary), InfluxQL — **no Flux** |
+| Query/network protocol | HTTP | Apache Arrow Flight SQL (gRPC) + HTTP |
+| Default port | 8086 | 8181 |
+| Auth prefix | `Token` | `Bearer` |
+| Write namespacing | `org` + `bucket` | `db` (database) |
+| Cardinality | ~10M series practical limit | Virtually unlimited |
+| **Deployment topology** | **Single node** (optionally + standby); **read-replica cluster** for multiple nodes | **Cluster only** (Core = single-node, Enterprise = multi-node) |
+| Control-plane create op | `create-db-instance` or `create-db-cluster` | `create-db-cluster` only |
+| Max storage | Up to 16 TiB provisioned, **cannot grow after creation** | Elastic via S3 |
+| Processing/automation | Tasks (Flux) | Processing engine (embedded Python VM) |
+| Extra licensing | Read replicas add a license fee | Enterprise adds a per-node Marketplace license; Core has none |
+
+## Deployment Topology
+
+This is the most commonly misunderstood difference. The two versions have fundamentally different deployment models.
+
+### V2 — single node by default
+A Timestream for InfluxDB **instance** (`create-db-instance`) is a **single node**. Availability options change this only slightly:
+
+- **`SINGLE_AZ`** (default) — one node, one Availability Zone.
+- **`WITH_MULTIAZ_STANDBY`** — a primary node plus a secondary **standby** in another AZ. The standby is for **failover only**; it does not serve reads or add throughput.
+
+To get more than one serving node, you must create a **read-replica cluster** (`create-db-cluster` with `--deployment-type MULTI_NODE_READ_REPLICAS`). Only then does V2 run multiple nodes. **Without a read-replica cluster, V2 is a single node.**
+
+### V3 — cluster only
+Timestream for InfluxDB 3 is **always deployed as a cluster** (`create-db-cluster`). There is no single-instance API for V3. The cluster's topology is determined by the parameter group, not a `--deployment-type` flag (do **not** pass `--deployment-type` for V3):
+
+- **Core** (`InfluxDBV3Core`) — a **single-node** cluster. Ingestion, querying, compaction, and the processing engine all run on one node and share compute. Core has **no dedicated compactor**, so it is best for recent data (typically the last 3–5 days).
+- **Enterprise** (`InfluxDBV3Enterprise`) — a **multi-node** cluster, up to 15 nodes: 1–4 writer (ingest) nodes, 0–13 read-only (query) nodes, and 1 compactor node. Nodes can be assigned distinct roles to isolate ingest/query/compaction/processing. All multi-node deployments are spread across multiple AZs for availability.
+
+**Summary:** V2 is single-node unless you build a read-replica cluster; V3 is only ever a cluster (single-node for Core, multi-node for Enterprise).
+
+## Architecture & Storage
+
+**V2** uses the InfluxDB 2.x **TSM** storage engine with a **TSI** (time-series index). Tags are indexed, which is what makes high cardinality expensive — every unique tag-value combination becomes a series key, and large indexes drive memory pressure and slow writes/queries. Practical guidance caps a V2 instance at **~10M series**. Storage is local **Influx IOPS Included** block volumes (up to 16 TiB), and **storage cannot be increased after creation** — capacity must be planned upfront.
+
+**V3** is a ground-up redesign built on open formats:
+- **Rust** core for performance.
+- **Apache Arrow** for in-memory columnar processing (vectorized execution, predicate/projection pushdown).
+- **Apache Parquet** for persisted columnar files.
+- **Apache DataFusion** as the query optimizer/engine.
+- **Apache Arrow Flight SQL** (gRPC) as the high-performance query protocol.
+- **Amazon S3** as the core storage layer — 11 nines (99.999999999%) durability, multi-AZ, and effectively elastic capacity.
+
+V3 also adds two in-memory caches that accelerate common patterns:
+- **Last Value Cache (LVC)** — most recent value per field; millisecond "last point" lookups for dashboards.
+- **Distinct Value Cache (DVC)** — unique tag/field values per table; fast metadata queries (e.g., listing host or sensor IDs).
+
+## Query Languages
+
+- **V2:** **Flux** is the primary language; **InfluxQL** is also supported, **SQL** is not.
+- **V3:** **SQL** is the primary language (via DataFusion); a v1-compatible **InfluxQL** endpoint is provided for legacy apps. **Flux is not supported.**
+
+There is **no automatic Flux-to-SQL conversion**. Migrating from V2 to V3 requires rewriting all Flux queries, tasks, and dashboards into SQL or InfluxQL.
+
+## Data Model & API
+
+- **V2** organizes data as **Organization → Bucket**. Writes specify `org` and `bucket`; data-plane auth uses the `Token` prefix; default port **8086**.
+- **V3** organizes data as **Database → Table** (no organizations). Tables are created automatically on first write (a measurement becomes a table). Writes specify `db`; data-plane auth uses the `Bearer` prefix; default port **8181**.
+
+**Backward compatibility:** V3 exposes v1- and v2-compatible write endpoints (including `/api/v2/write`), so existing line-protocol writers and Telegraf configs can keep writing without changes during a migration. Line protocol itself is unchanged across versions.
+
+## Automation / Processing
+
+- **V2** uses **Tasks** — scheduled Flux scripts for downsampling, alerting, and transforms.
+- **V3** ships a **processing engine**: an embedded Python virtual machine that runs plugins on scheduled events or WAL-flush events (downsampling, alerting, anomaly detection) with zero-copy access to data. Timestream for InfluxDB 3 provides a curated, security-hardened set of plugins.
+  - **Gotcha:** on multi-node Enterprise, scheduled triggers run on **every** node and can OOM small instances — target nodes with `node_spec` or scale up.
+
+## Cost & Licensing
+
+- **V2:** billed on instance hours + provisioned storage (per GiB) + data transfer. **Read replicas add a license fee**.
+- **V3 Core:** compute + S3 storage only — **no license fee**.
+- **V3 Enterprise:** compute + S3 storage **plus** an Enterprise license billed per node-hour via **AWS Marketplace** (InfluxData). The license is separate from AWS compute spend, and **EDP discounts do not apply** to Marketplace charges.
+
+## Choosing / Migration Guidance
+
+- **Choose V3** for high or unpredictable cardinality, SQL/BI integration, large historical retention (cheap S3), or when you need a multi-node solution for high ingest. V3 is also the forward path for workloads leaving Timestream for LiveAnalytics (in maintenance mode).
+- **Stay on / choose V2** when you depend on **Flux**, existing v2 tooling/dashboards, or org/bucket semantics, and your cardinality stays well under ~10M series.
+- **Migration checklist (V2 → V3):** rewrite Flux → SQL/InfluxQL; map orgs/buckets → databases/tables; switch auth `Token` → `Bearer` and port `8086` → `8181`; re-point writers (or use V3's v2-compatible write endpoint); re-provision as a cluster (Core or Enterprise).
+- **No turnkey data migration:** the engines share no storage format, and managed V2 blocks host access (so the OSS `influxd inspect export-lp` disk dump is unavailable). Data must move through the **query API**: extract from V2 as annotated CSV or a DataFrame (V2 cannot emit line protocol from queries), then load into V3 — the InfluxDB 3 Python client's `write_file()` (CSV/JSON/Parquet/…) and `write_dataframe()` are the most capable loaders. Full runbook: `influxdb2/migrations.md`.
+
+## Retrieving tokens
+
+To interact with your deployed Timestream for InfluxDB instance or cluster, creating buckets, executing queries, ingesting data, etc., using the InfluxDB v2 or v3 HTTP APIs, you must retrieve or create an InfluxDB token.
+
+### V2
+
+Once your v2 instance or cluster has been deployed, create a new operator token, using the [Influx v2 CLI](https://docs.influxdata.com/influxdb/v2/tools/influx-cli/?section=influxdb%252Fv2%252Ftools):
+
+```shell
+influx config create --config-name CONFIG_NAME1  --host-url "https://yourinstanceid.eu-central-1.timestream-influxdb.amazonaws.com:8086" --org [YOURORG]  --username-password [YOURUSERNAME] --active
+
+influx auth create --org [YOURORG] --operator
+```
+
+### V3
+
+After you have deployed a Timestream for InfluxDB v3 cluster, a secret in AWS Secrets Manager will be associated with your cluster. The ID of this secret will be returned as part of the `aws timestream-influxdb get-db-cluster` AWS CLI call and is visible in the AWS console.
+
+Given the cluster ID, you can retrieve your token with the following command, replacing `<cluster ID>` with your cluster ID:
+```shell
+aws secretsmanager \
+  get-secret-value \
+  --secret-id READONLY-InfluxDB-auth-parameters-<cluster ID> \
+  --query SecretString \
+  --output text | jq -r '.token'
+```
+
+## Sources
+
+- [What is Timestream for InfluxDB?](https://docs.aws.amazon.com/timestream/latest/developerguide/timestream-for-influxdb.html)
+- [Amazon Timestream for InfluxDB 3](https://docs.aws.amazon.com/timestream/latest/developerguide/influxdb3.html)
+- [Features and workflows with Amazon Timestream for InfluxDB 3](https://aws.amazon.com/blogs/database/features-and-workflows-with-amazon-timestream-for-influxdb-3/)
+- [Timestream for InfluxDB 3 workload analysis and best practices](https://aws.amazon.com/blogs/database/timestream-for-influxdb-3-workload-analysis-and-best-practices/)
+- [InfluxDB v2 HTTP API](https://docs.influxdata.com/influxdb/v2/api/?section=influxdb%252Fv2%252Fapi)
+- [InfluxDB v3 HTTP API](https://docs.influxdata.com/influxdb3/enterprise/api/)