@kinetica/admin-agent 0.1.0

package/knowledge/playbooks/config-drift.md

@@ -0,0 +1,26 @@
+---
+title: Config Drift / Configuration Pitfalls
+category: configuration
+severity: warning
+keywords: [config, drift, configuration, regression, upgrade]
+---
+
+## Symptoms
+
+- Unexpected behavior after upgrade or config change
+- Performance regression with no workload change
+
+## Detection
+
+- `kinetica_get_system_properties` → compare against known-good values
+- `kinetica_get_config` → snapshot shows non-default values (7.2.x: use system properties instead)
+
+## Root Cause
+
+Configuration issue from manual edits, upgrade migration, or environment-specific settings.
+
+## Remediation
+
+1. Use `kinetica_alter_system_properties` to restore known-good config values
+2. Review Kinetica changelog for breaking config changes between versions
+3. Document baseline configuration for future comparison

package/knowledge/playbooks/gpu-out-of-memory.md

@@ -0,0 +1,27 @@
+---
+title: GPU Out-of-Memory
+category: performance
+severity: critical
+keywords: [VRAM, GPU, OOM, memory, timeout]
+---
+
+## Symptoms
+
+- ERROR logs with "out_of_memory" or GPU OOM, query failures
+- `kinetica_get_metrics` shows GPU memory near 100%
+
+## Detection
+
+- `kinetica_get_metrics` → check `vram_used` on worker ranks
+- `ki_catalog.ki_tiered_objects` → find large VRAM-tier objects
+
+## Root Cause
+
+Queries materializing too much data in VRAM; oversized objects loaded into GPU memory.
+
+## Remediation
+
+1. Identify largest GPU objects via `kinetica_resource_objects`
+2. Add query limits to constrain result set sizes
+3. Review GPU memory allocation config via `kinetica_get_system_properties` (conf.tier.\*)
+4. Consider tier eviction policy changes

package/knowledge/playbooks/memory-pressure.md

@@ -0,0 +1,29 @@
+---
+title: Memory Pressure
+category: performance
+severity: warning
+keywords: [memory, pressure, eviction, RAM, slow, disk]
+---
+
+## Symptoms
+
+- Slow queries with no obvious cause
+- Eviction warnings in logs
+- `ki_tiered_objects` showing data moved to PERSIST or DISK tier
+
+## Detection
+
+- `kinetica_get_metrics` → high RAM usage percentage (above 80%)
+- `ki_catalog.ki_tiered_objects` → objects in PERSIST/DISK tier that should be in RAM
+- `kinetica_resource_objects` → non-zero eviction counts
+
+## Root Cause
+
+Total working set exceeds available RAM; large objects not fitting in configured tier limits.
+
+## Remediation
+
+1. Increase tier memory allocation via `kinetica_alter_system_properties` (conf.tier.\*)
+2. Identify and evict cold objects via `kinetica_resource_objects`
+3. Archive unused tables to free tier capacity
+4. Review resource group memory limits in `kinetica_resource_groups`

package/knowledge/playbooks/query-contention.md

@@ -0,0 +1,28 @@
+---
+title: Query Contention
+category: performance
+severity: warning
+keywords: [query, contention, slow, blocking, lock, concurrent]
+---
+
+## Symptoms
+
+- Long-running queries in `ki_query_history` (large elapsed time between start and completion)
+- Active queries blocking each other
+
+## Detection
+
+- `ki_catalog.ki_query_active_all` → multiple long-running queries
+- `ki_catalog.ki_query_history` → queries with large elapsed time
+- `ki_catalog.ki_query_workers` → blocked worker threads
+
+## Root Cause
+
+Concurrent large queries competing for GPU resources; lock contention on shared tables.
+
+## Remediation
+
+1. Stagger large queries to reduce concurrent GPU pressure
+2. Review query priority settings in resource groups
+3. Consider query queue configuration via `kinetica_alter_system_properties`
+4. Check `kinetica_resource_groups` for CPU concurrency limits

package/knowledge/playbooks/resource-group-exhaustion.md

@@ -0,0 +1,27 @@
+---
+title: Resource Group Exhaustion
+category: resources
+severity: warning
+keywords: [resource, group, limit, exhaustion, tier, capacity]
+---
+
+## Symptoms
+
+- Queries failing with resource limit errors
+- Tier capacity warnings
+
+## Detection
+
+- `kinetica_resource_groups` → tier usage near limits
+- `kinetica_resource_objects` → uneven object distribution across ranks
+
+## Root Cause
+
+Resource group limits too low for workload; uneven data placement across tiers.
+
+## Remediation
+
+1. Increase resource group limits via `kinetica_alter_system_properties`
+2. Use `kinetica_admin_rebalance` to redistribute data evenly across ranks
+3. Review resource group assignments in `kinetica_show_security`
+4. Consider adding new resource groups for workload isolation

package/knowledge/playbooks/stale-rank.md

@@ -0,0 +1,26 @@
+---
+title: Stale Rank (Rank Not Responding)
+category: cluster
+severity: critical
+keywords: [rank, stale, offline, crash, partition]
+---
+
+## Symptoms
+
+- Health check shows unhealthy rank
+- Cluster status shows rank offline
+
+## Detection
+
+- `kinetica_health_check` → non-OK rank status
+- `kinetica_cluster_status` → rank alerts, shard mapping gaps
+
+## Root Cause
+
+Stale rank process after crash or network partition; rank failed to rejoin cluster.
+
+## Remediation
+
+1. Tell user to run `gadmin restart rank <N>` manually (no REST API for worker restart in 7.2)
+2. After rank recovers, use `kinetica_admin_rebalance` to redistribute shards
+3. Verify recovery with `kinetica_health_check` and `kinetica_cluster_status`

package/knowledge/references/catalog-enums.md

@@ -0,0 +1,82 @@
+---
+title: ki_catalog Enum Values
+category: catalog-schema
+keywords:
+  [
+    ki_catalog,
+    enums,
+    obj_kind,
+    shard_kind,
+    persistence,
+    partition_type,
+    tier,
+    priority,
+    tiered_objects,
+  ]
+---
+
+## Overview
+
+Many `ki_catalog` columns encode state as single-character codes or
+small string constants. These are the canonical values — decode them
+explicitly when interpreting query results or building WHERE clauses.
+
+## ki_objects
+
+| Column        | Value | Meaning                       |
+| ------------- | ----- | ----------------------------- |
+| `obj_kind`    | `R`   | table / relation              |
+| `obj_kind`    | `V`   | view                          |
+| `shard_kind`  | `S`   | sharded                       |
+| `shard_kind`  | `N`   | not sharded                   |
+| `persistence` | `P`   | persistent (survives restart) |
+| `persistence` | `T`   | temporary                     |
+
+## ki_partitions
+
+| Column           | Value      | Meaning                          |
+| ---------------- | ---------- | -------------------------------- |
+| `partition_type` | `NONE`     | unpartitioned                    |
+| `partition_type` | `INTERVAL` | time-based interval partitioning |
+
+## ki_tiered_objects
+
+### `id` format
+
+String identifier (`char256`), format like `@schema@oid[col][chunk]`
+(e.g., `@nyctaxi@365[col][0]`). NOT a numeric OID — **cannot** be
+joined to `ki_objects.oid`. See `catalog-joins.md` for the correct
+lookup path.
+
+### `tier`
+
+Storage tier placement. One of:
+
+- `RAM` — host memory
+- `PERSIST` — persistent SSD/disk tier
+- `DISK0` — primary disk tier
+- `VRAM` — GPU memory
+
+Same values appear in `ki_partitions.tier`.
+
+### `priority`
+
+Tier manager priority — determines eviction order when a tier fills:
+
+| Value | Meaning                             |
+| ----- | ----------------------------------- |
+| 1     | system / `ki_catalog` (never evict) |
+| 5     | regular user tables                 |
+| 9     | temporary / ephemeral               |
+
+Higher `priority` = more expendable = evicted first.
+
+### `locked` and `evictable`
+
+- `locked = 1` — pinned in its current tier; tier manager cannot move it.
+- `evictable = 1` — tier manager may move this object to a lower tier
+  when space is needed.
+
+An object can be both unlocked and non-evictable (rare; means the tier
+manager will not proactively move it but nothing prevents an
+administrator from doing so).

package/knowledge/references/catalog-joins.md

@@ -0,0 +1,105 @@
+---
+title: ki_catalog Cross-Table Correlation Paths
+category: catalog-schema
+keywords:
+  [
+    ki_catalog,
+    joins,
+    correlation,
+    ki_objects,
+    ki_columns,
+    ki_partitions,
+    ki_query_history,
+    ki_tiered_objects,
+    oid,
+  ]
+---
+
+## Overview
+
+When investigating issues, evidence usually has to be joined across
+multiple `ki_catalog` tables. These are the standard correlation paths
+— prefer them over ad-hoc joins.
+
+## Table Metadata Chain
+
+Walk this chain to go from an object name to its on-disk footprint and
+schema:
+
+```
+ki_objects.oid
+  → ki_obj_stat.oid        (row counts, total sizes)
+  → ki_partitions.oid      (tier placement, compression)
+  → ki_columns.table_oid   (column schema)
+```
+
+## Column Type Resolution
+
+`ki_columns.column_type_oid` is a numeric OID, not a type name. Join
+it to `ki_datatypes.oid` to get the human-readable type:
+
+| OID  | Type       |
+| ---- | ---------- |
+| 20   | `long`     |
+| 1043 | `char256`  |
+| 1114 | `datetime` |
+| 2950 | `uuid`     |
+| 25   | `string`   |
+
+## Query Drill-Down
+
+To reconstruct a slow query's execution tree:
+
+```
+ki_query_history.query_id
+  → ki_query_span_metrics_all.query_id
+  → span tree via span_id / parent_span_id
+```
+
+## Active Query Workers
+
+For queries currently running:
+
+```
+ki_query_active_all.job_id
+  → ki_query_workers.job_id   (worker threads, elapsed time, blockers)
+```
+
+Use `ki_query_active_all.is_cancellable` to check whether a running
+query can be cancelled before suggesting that remediation.
+
+## Permission Audit
+
+```
+ki_object_permissions.role_oid   → ki_users_and_roles.oid
+ki_object_permissions.object_oid → ki_objects.oid
+```
+
+## Dependency Graph
+
+For impact analysis before proposing a DROP:
+
+```
+ki_depend.src_obj_oid → ki_objects.oid
+ki_depend.dep_obj_oid → ki_objects.oid
+```
+
+## Tier Object Lookup (WARNING — no OID join)
+
+`ki_tiered_objects.id` is a **string identifier** (e.g.,
+`@nyctaxi@365[col][0]`), NOT a numeric OID. Do NOT try to join it
+with `ki_objects.oid` — the types don't match and the values don't
+correspond.
+
+For per-table tier placement, prefer the dedicated tool:
+
+```
+kinetica_resource_objects  (with table_names filter)
+```
+
+For SQL-based analysis, filter with a string match:
+
+```sql
+SELECT * FROM ki_catalog.ki_tiered_objects
+WHERE id LIKE '%table_name%'
+```

package/knowledge/references/gpudb-conf.md

@@ -0,0 +1,93 @@
+---
+title: gpudb.conf Configuration Reference
+category: configuration
+keywords: [gpudb.conf, config, configuration, parameters, tuning, tiers, alerts]
+---
+
+## Overview
+
+`gpudb.conf` is the master Kinetica configuration file (INI format, all under `[gaia]` section).
+Default on-disk location: `/opt/gpudb/core/etc/gpudb.conf`.
+Retrieved via `kinetica_show_configuration` (host manager port 9300), modified via `kinetica_alter_configuration`.
+Runtime properties are a subset available via `kinetica_get_system_properties` / `kinetica_alter_system_properties`.
+
+## Section Index
+
+| Section             | Key Parameters                                                                       | Diagnostic Relevance        |
+| ------------------- | ------------------------------------------------------------------------------------ | --------------------------- |
+| Identification      | `ring_name`, `cluster_name`                                                          | Cluster identity            |
+| Hosts               | `host<#>.address`, `host<#>.ram_limit`, `host<#>.gpus`                               | Host topology, RAM caps     |
+| Ranks               | `rank<#>.host`                                                                       | Rank-to-host mapping        |
+| Network             | `head_port` (9191), `host_manager_http_port` (9300), `enable_worker_http_servers`    | Connectivity issues         |
+| Security            | `require_authentication`, `enable_authorization`                                     | Auth troubleshooting        |
+| Auditing            | `enable_audit`, `audit_body`, `lock_audit`                                           | Audit trail                 |
+| Licensing           | `license_key`                                                                        | License issues              |
+| Processes & Threads | `worker_endpoint_threads`, `tcs_per_tom`, `tps_per_tom`, `subtask_concurrency_limit` | Performance tuning          |
+| Hardware            | `rank<#>.taskcalc_gpu`, `rank<#>.numa_node`                                          | GPU/NUMA assignment         |
+| General             | `default_ttl`, `chunk_size`, `execution_mode`, `request_timeout`                     | Performance, data lifecycle |
+| Visualization       | `max_heatmap_size`, `enable_opengl_renderer`, `enable_vectortile_service`            | WMS/VTS issues              |
+| Text Search         | `enable_text_search`, `text_indices_per_tom`                                         | Text search issues          |
+| Persistence         | `persist_directory`, `wal.*`, `compression_codec`, `load_vectors_on_start`           | Data durability, startup    |
+| Monitoring          | `enable_stats_server`, `telm.persist_query_metrics`                                  | Observability               |
+| Graph Servers       | `enable_graph_server`, `graph.server<#>.host`                                        | Graph analytics             |
+| HA                  | `enable_ha`, `enable_ha_replay`                                                      | High availability           |
+| Alerts              | `alert_memory_percentage`, `alert_disk_percentage`, `heartbeat_*`                    | Alert config                |
+| Failover            | `np1.enable_worker_failover`, `np1.rank_restart_attempts`                            | Failover behavior           |
+| Postgres Proxy      | `enable_postgres_proxy`, `postgres_proxy.port` (5432)                                | Client connectivity         |
+| SQL Engine          | `sql.enable_planner`, `sql.planner.timeout`, `sql.plan_cache_size`                   | Query planning              |
+| Tiered Storage      | `tier.{vram,ram,disk,persist,cold}.*`                                                | Memory/storage management   |
+| Tier Strategy       | `tier_strategy.default`                                                              | Data placement policy       |
+| Resource Groups     | `resource_group.default.*`                                                           | Resource allocation         |
+
+## Performance-Critical Parameters
+
+**Thread Pools** (all accept `-1` for auto):
+
+- `worker_endpoint_threads` — HTTP request handling threads per worker rank
+- `tps_per_tom` — data processing threads (inserts, updates, deletes); multi-head ingest not affected
+- `tcs_per_tom` — calculation threads (aggregates, record retrieval)
+- `subtask_concurrency_limit` — query-level scheduler concurrency; lower = depth-first (fewer queries, faster completion), higher = breadth-first (more concurrency)
+
+**Chunk Settings:**
+
+- `chunk_size` — records per chunk (default 8M; 0 disables chunking)
+- `chunk_max_memory` — max total chunk data per table in bytes
+- `chunk_column_max_memory` — max per-column chunk data in memory (512MB)
+
+**Execution Mode:** `execution_mode` = `default` | `host` | `device` | `<rows>` — controls CPU vs GPU kernel execution. When set to `device` but no GPUs are available, falls back to CPU.
+
+## Tiered Storage Quick Reference
+
+Five tier types (data flows down when evicted):
+
+1. **VRAM** — GPU memory; limit/watermarks per rank per GPU
+2. **RAM** — main memory; rank0 gets ~10% of system RAM, workers split the rest
+3. **Disk** — temporary swap cache (fast SSD recommended); multiple disk tiers supported
+4. **Persist** — permanent storage; data survives restarts
+5. **Cold** — extended storage (disk, HDFS, S3, Azure, GCS); for infrequently accessed data
+
+**Watermark semantics:** `high_watermark` triggers background eviction; eviction continues until usage drops below `low_watermark`. Both are percentages (1-100). Set both to 100 to disable eviction. Watermarks are ignored when limit is -1.
+
+**Default tier strategy format:** `VRAM <priority>, RAM <priority>, DISK0 <priority>, PERSIST <priority>` — priority 1 (lowest, first evicted) to 9 (highest, last evicted), 10 = unevictable.
+
+## WAL (Write-Ahead Log)
+
+- `wal.sync_policy`: `none` (disabled) | `background` (periodic) | `flush` (per-operation, survives DB crash) | `fsync` (per-operation, survives OS crash)
+- `wal.checksum`: integrity protection on WAL entries
+- `wal.truncate_corrupt_tables_on_start`: auto-truncate corrupt tables on replay (vs. manual REPAIR TABLE)
+
+## Alert Thresholds
+
+- `alert_memory_percentage` — comma-separated thresholds (e.g., `1, 5, 10, 20`) for low-memory alerts
+- `alert_disk_percentage` — same for low-disk alerts
+- `heartbeat_interval` / `heartbeat_timeout` / `heartbeat_missed_limit` — host failure detection timing
+
+## Key Gotchas
+
+- **`-1` means different things:** For thread counts = auto-detect; for tier limits = no limit (ignore watermarks); for `default_ttl` = disabled
+- **`default_ttl`** is in MINUTES — non-protected tables are auto-deleted after this time. A value of 20 means tables without explicit TTL override vanish after 20 minutes.
+- **`load_vectors_on_start = on_demand`** means data loads lazily — first queries on cold data will be slower
+- **Rank 0** is the head/coordinator node with minimal RAM allocation (~10%); it does NOT hold data. Worker ranks (1+) hold all data.
+- **`execution_mode = device`** silently falls back to CPU when no GPUs are present — no error is raised
+- **7.2.x missing parameters:** `sm_omp_threads`, `kernel_omp_threads` do NOT exist — use `worker_endpoint_threads`, `subtask_concurrency_limit`, `tcs_per_tom` instead
+- **Config changes require restart** unless the parameter is also a runtime system property (check via `kinetica_get_system_properties`)

package/knowledge/references/mutation-safety.md

@@ -0,0 +1,89 @@
+---
+title: Mutation Safety Rules
+category: mutation-policy
+keywords:
+  [
+    mutation,
+    safety,
+    admin-rebalance,
+    alter-system-properties,
+    alter-configuration,
+    never-propose,
+    ai_api_key,
+    cache-clearing,
+    worker-restart,
+    aggressiveness,
+  ]
+---
+
+## Overview
+
+Safety contract the agent must follow before and during Round 4
+(Mutation Proposal) of the investigation protocol. These rules combine
+version-specific Kinetica 7.2.x facts with operational policy — every
+mutation tool call is subject to them.
+
+## Pre-Mutation Checklist
+
+BEFORE proposing any mutation:
+
+1. Always run `kinetica_health_check` first — do not mutate an unhealthy
+   cluster.
+2. For `kinetica_admin_rebalance`: check `kinetica_cluster_status` for
+   active rebalance/add/remove operations — never propose rebalance
+   when one is already running.
+3. For config changes: use `kinetica_get_system_properties` to read the
+   current value BEFORE proposing a change (so the report can show a
+   meaningful before/after diff).
+
+## NEVER Propose
+
+- `/clear/table` or `/clear/tablemonitor` as cache-clearing operations —
+  these DELETE DATA permanently in Kinetica. They are not caches.
+- Setting `ai_api_key` via `kinetica_alter_system_properties` — this is
+  a credential that would appear in audit logs.
+- Setting `external_files_directory` — filesystem path; potential path
+  traversal concern.
+- Setting `flush_to_disk` — can trigger an expensive I/O storm.
+- Worker restart — no REST API exists in Kinetica 7.2. Tell the
+  operator to run `gadmin restart rank <N>` manually instead.
+- Cache clearing — no safe API exists in Kinetica 7.2. Recommend
+  query-side solutions (rewriting the query, adding an index, bumping
+  resource group limits) instead of trying to clear caches.
+
+## For `kinetica_admin_rebalance`
+
+- Recommend aggressiveness 1–3 during production hours (reduces query
+  latency impact).
+- Recommend aggressiveness 4–5 during maintenance windows only.
+- Warn the operator: rebalance causes "delayed query responses" while
+  running.
+- Check `kinetica_cluster_status` for active jobs before proposing.
+- On single-worker-rank clusters (rank 0 + 1 worker), rebalance
+  returns "Database must be offline" — rebalance is only meaningful
+  with 2+ worker ranks.
+
+## For `kinetica_alter_system_properties`
+
+- The tool enforces an allow-list of 43 documented properties —
+  unsupported names are rejected before the API call.
+- Prefer changing `subtask_concurrency_limit`, `tcs_per_tom`, or
+  `tps_per_tom` for concurrency tuning.
+- NOTE: `sm_omp_threads` and `kernel_omp_threads` do NOT exist in
+  Kinetica 7.2.x (not in the allow-list).
+- Avoid `chunk_size` changes without DBA review — affects all query
+  performance.
+- `request_timeout` changes affect ALL endpoints system-wide.
+
+## For `kinetica_alter_configuration`
+
+- ALWAYS read the current config via `kinetica_show_configuration`
+  first.
+- Make targeted edits to specific lines — never compose a config from
+  scratch.
+- Submit the full modified `config_string` (the entire file is
+  replaced).
+- Changes require a service restart to take effect — inform the
+  operator.
+- This tool contacts the host manager (port 9300), not the DB engine
+  (port 9191).

package/knowledge/references/rank-architecture.md

@@ -0,0 +1,54 @@
+---
+title: Kinetica Rank Architecture
+category: cluster-topology
+keywords: [ranks, rank-0, head, coordinator, worker, shards, metrics-interpretation, asymmetry]
+---
+
+## Overview
+
+Kinetica uses a rank-based distributed architecture. A single host
+typically runs one head rank (rank 0) plus one or more worker ranks
+(rank 1, rank 2, …). Understanding the asymmetry between rank 0 and
+worker ranks is essential to correctly interpreting metrics and
+resource-group reports.
+
+## Rank 0 — Head / Coordinator
+
+- Stores only **metadata** (~4 MB RAM steady-state).
+- Has **no** `PERSIST` / `DISK` / `VRAM` tiers configured — data
+  tiers live on worker ranks.
+- Has **no** resource objects (nothing to place in tiers).
+- Has **no** `rank_usage` entry in resource groups.
+- Much lower RAM limit, typically ~750 MB.
+- Responsible for coordinating queries, query planning, and routing
+  requests to worker ranks.
+
+## Rank 1+ — Workers / Data Nodes
+
+- Hold the actual user data.
+- Have full tier configuration (RAM / PERSIST / DISK / VRAM as
+  configured in `gpudb.conf`).
+- All 16,384 shards map to worker ranks (rank 0 holds no shards).
+- RAM limits typically 5+ GB per rank.
+
+## Interpreting Metrics — Key Rule
+
+**Rank 0's low resource usage is normal — it is NOT a sign of
+imbalance or a failing node.**
+
+When reviewing `kinetica_get_metrics` or `kinetica_node_details`:
+
+- Compare worker ranks against each other — rank 1 vs rank 2 vs …
+- Do NOT compare rank 0 against worker ranks; the asymmetry will
+  always make rank 0 look "idle".
+- Do NOT propose rebalance because rank 0 has less data than workers
+  — that is the expected topology.
+
+Similarly, when a resource group report shows no `rank_usage` for
+rank 0, that is correct — nothing runs in resource groups on the head
+rank.
+
+## Single-Worker Clusters
+
+Rebalance requires 2+ worker ranks — see `version-quirks-7.2.md` for
+the exact `/admin/rebalance` precondition and error message.

package/knowledge/references/sql-alter-table.md

@@ -0,0 +1,78 @@
+---
+title: Kinetica ALTER TABLE — Column Property Syntax
+category: sql-syntax
+keywords:
+  [
+    alter-table,
+    alter-column,
+    modify-column,
+    dict,
+    text-search,
+    compress,
+    column-properties,
+    shard-key,
+    kinetica-alter-table-columns,
+  ]
+---
+
+## Overview
+
+Kinetica's `ALTER TABLE` syntax for column properties differs from
+standard SQL in two non-obvious ways:
+
+1. Column properties live INSIDE the type parentheses, not as trailing
+   clauses.
+2. There is no `SET`/`ADD`/`DROP` for individual properties — every
+   change requires repeating the FULL column definition.
+
+## Single-Column Changes
+
+```sql
+-- Add DICT encoding to an existing column (repeat full definition):
+ALTER TABLE [schema.]table_name
+  ALTER COLUMN column_name VARCHAR(size, DICT) [NOT NULL]
+
+-- Equivalent MODIFY syntax:
+ALTER TABLE [schema.]table_name
+  MODIFY COLUMN column_name VARCHAR(size, DICT) [NOT NULL]
+
+-- Remove DICT encoding (omit DICT from definition):
+ALTER TABLE [schema.]table_name
+  ALTER COLUMN column_name VARCHAR(size) [NOT NULL]
+```
+
+## Multiple Column Changes
+
+Multiple alterations on the same table can be bundled in a single
+statement:
+
+```sql
+ALTER TABLE [schema.]table_name
+  ALTER COLUMN col1 VARCHAR(50, DICT),
+  ALTER COLUMN col2 VARCHAR(100, TEXT_SEARCH) NOT NULL,
+  ALTER COLUMN col3 INT(DICT)
+```
+
+**For agent use:** when recommending 2+ column changes on one table,
+prefer the `kinetica_alter_table_columns` tool — it composes this
+bundled statement automatically and surfaces an interactive checklist
+for operator approval.
+
+## Key Rules
+
+- **Properties inside parentheses:** `VARCHAR(50, DICT)` —
+  NOT `VARCHAR(50) DICT`. Placing the property outside the parens is a
+  syntax error.
+- **Full definition required:** type, size, properties, nullability
+  must all be repeated. There is no `ALTER COLUMN col SET DICT` syntax.
+- **Available column properties:** `DICT`, `TEXT_SEARCH`,
+  `COMPRESS(type)`, `IPV4`, `NORMALIZE`, `INIT_WITH_NOW`,
+  `INIT_WITH_UUID`, `UPDATE_WITH_NOW`.
+- **Cascade behavior:** Dependent views, materialized views, and SQL
+  procedures are DROPPED when a referenced column is altered. Warn
+  operators before proposing ALTER COLUMN on a column with known
+  dependencies — check `ki_catalog.ki_depend` first.
+- **Shard keys are immutable** — check `is_shard_key` in
+  `ki_catalog.ki_columns` (or `properties` in `kinetica_show_table`)
+  before proposing ALTER COLUMN. See `version-quirks-7.2.md` for the
+  full rule.