@selfhost.dev/mcp-server 0.9.0 → 0.10.0

package/dist/tools/instances.js

@@ -37,48 +37,54 @@ function validateStorageParams(type, iops, throughput) {
     return null;
 }
 // --- Engine reference data (mirrors the backend adapter registry + the console) ---
-const ENGINES = ["postgres", "mysql", "redis", "clickhouse"];
+const ENGINES = ["postgres", "mysql", "redis", "clickhouse", "opensearch"];
 /**
- * ClickHouse versions in the backend's own order (`ClickhouseAdapter.supported_versions`).
- * Order matters: the in-place upgrade path walks this list one step at a time.
+ * ClickHouse versions (`ClickhouseAdapter.supported_versions`). One rung: selfhost#2580 pinned
+ * the platform to the 26.8 LTS and deleted 26.5 once no live instance was left on it. The list
+ * stays an array because the next LTS lands here, not because the caller gets a choice today.
  */
-const CLICKHOUSE_VERSIONS = ["24.3", "24.8", "25.1", "26.5"];
+const CLICKHOUSE_VERSIONS = ["26.8"];
 /** Versions each engine's adapter accepts. Anything else is a 422 at create. */
 const ENGINE_VERSIONS = {
     postgres: ["18", "17", "16"],
     mysql: ["8.4", "8.0"],
     redis: ["7.2", "7.0"],
     clickhouse: CLICKHOUSE_VERSIONS,
+    opensearch: ["2.19", "2.16", "2.13"],
 };
 /**
  * Version sent when the caller passes none.
  *
  * This has to be explicit on every engine: the backend's fallback is
  * `supported_versions.first`, which is the OLDEST major each adapter still accepts
- * (postgres 14, redis 7.0, clickhouse 24.3), so omitting `db_version` silently
+ * (postgres 14, redis 7.0, opensearch 2.13), so omitting `db_version` silently
  * provisions a years-old release. These mirror the console's create-wizard defaults
  * (`CreateDatabaseOptions`) so both surfaces hand out the same database - newest for
- * postgres/redis, and the stable release rather than the newest for mysql (8.0 over 8.4)
- * and clickhouse (the 24.8 LTS over 25.1/26.5).
+ * postgres/redis/opensearch, and the stable release rather than the newest for mysql
+ * (8.0 over 8.4). ClickHouse has exactly one supported version, so its default is the list.
  */
 const ENGINE_DEFAULT_VERSION = {
     postgres: "18",
     mysql: "8.0",
     redis: "7.2",
-    clickhouse: "24.8",
+    clickhouse: "26.8",
+    opensearch: "2.19",
 };
 const CLICKHOUSE_DEFAULT_VERSION = ENGINE_DEFAULT_VERSION.clickhouse;
 /**
- * Hard RAM floor per engine - backend `InstancesController::MIN_RAM_GB`. ClickHouse below
- * 4 GiB fails its systemd Type=notify startup, so create is rejected outright.
+ * Hard RAM floor per engine, from the backend's capacity-ladder YAML (`RAM_TIERS`). ClickHouse
+ * below 4 GiB fails its systemd Type=notify startup; OpenSearch gives its JVM heap 50% of
+ * available memory, so below 4 GiB it cannot hold a usable heap. Create is rejected outright
+ * on both. 512 MiB and 1 GiB remain postgres/mysql-only territory and both are `not_supported`
+ * for these two at every tier.
  */
-const ENGINE_MIN_RAM_GIB = { clickhouse: 4 };
+const ENGINE_MIN_RAM_GIB = { clickhouse: 4, opensearch: 4 };
 /** Highest replica count offered with multi-AZ on. ClickHouse scales out; others keep Basic(1)/Enhanced(2). */
-const ENGINE_MAX_REPLICAS = { postgres: 2, mysql: 2, redis: 2, clickhouse: 5 };
+const ENGINE_MAX_REPLICAS = { postgres: 2, mysql: 2, redis: 2, clickhouse: 5, opensearch: 5 };
 /** Replica count used when multi_az is on and none was passed (ClickHouse wants an odd node count). */
-const ENGINE_DEFAULT_REPLICAS = { postgres: 1, mysql: 1, redis: 1, clickhouse: 2 };
+const ENGINE_DEFAULT_REPLICAS = { postgres: 1, mysql: 1, redis: 1, clickhouse: 2, opensearch: 1 };
 /** Default client port per engine. ClickHouse speaks HTTP on 8123; native TCP is 9000. */
-const ENGINE_DEFAULT_PORT = { postgres: 5432, mysql: 3306, redis: 6379, clickhouse: 8123 };
+const ENGINE_DEFAULT_PORT = { postgres: 5432, mysql: 3306, redis: 6379, clickhouse: 8123, opensearch: 9200 };
 /** ClickHouse native TCP port, alongside the HTTP port above. */
 const CLICKHOUSE_NATIVE_PORT = 9000;
 /** Distributed-query cluster name on multi-AZ ClickHouse, e.g. cluster('selfhost_cluster', system.one). */
@@ -96,6 +102,65 @@ const CLICKHOUSE_KEEPER_STORAGE_GB = 20;
 function needsClickhouseKeeper(engine, replicaCount) {
     return engine === "clickhouse" && replicaCount === 1;
 }
+/**
+ * OpenSearch cluster topology - `OpensearchTopology`. OpenSearch has no master/replica
+ * relationship; a cluster is a set of nodes carrying roles, and `replica_count` buys DATA
+ * nodes. The moment redundancy is asked for, cluster-manager duties move onto three dedicated
+ * nodes, because folding the manager role onto two all-in-one nodes leaves an even,
+ * split-brain-prone manager set:
+ *
+ *   replica_count 0 → 1 node   (one all-in-one [cluster_manager,data,ingest]; dev / non-HA)
+ *   replica_count 1 → 5 nodes  (3 manager-only + 2 data)   ← HA minimum
+ *   replica_count 2 → 6 nodes  (3 manager-only + 3 data)
+ *   replica_count N → N+4      (3 manager-only + N+1 data)
+ *
+ * THE THREE MANAGERS BILL LIKE ANY OTHER NODE, and the pricing endpoint knows nothing about
+ * them - the same trap as the ClickHouse Keeper, three times over. Going from 0 to 1 replica
+ * is a 1 → 5 node jump, not 1 → 2. Managers inherit the endpoint node's storage size and
+ * default to `t4g.medium`; `manager_instance_type` overrides that, subject to the same 4 GiB
+ * floor (a 2 GiB manager OOMs its JVM under quorum load and is rejected).
+ */
+const OPENSEARCH_MANAGER_COUNT = 3;
+const OPENSEARCH_DEFAULT_MANAGER_TYPE = "t4g.medium";
+const OPENSEARCH_MANAGER_RAM_FLOOR_GIB = 4;
+/** Total nodes provisioned for an OpenSearch `replica_count`, managers included. */
+function opensearchNodeCount(replicaCount) {
+    const dataNodes = Math.max(replicaCount, 0) + 1;
+    return dataNodes >= 2 ? dataNodes + OPENSEARCH_MANAGER_COUNT : dataNodes;
+}
+/** Whether this topology provisions the three dedicated cluster-manager nodes. */
+function needsOpensearchManagers(engine, replicaCount) {
+    return engine === "opensearch" && Math.max(replicaCount, 0) + 1 >= 2;
+}
+/**
+ * OpenSearch Dashboards - the opt-in UI, co-located on the endpoint node as a Node.js process
+ * competing with the JVM for memory. Hence its own RAM gate, above the engine's own floor.
+ * Never part of provisioning or readiness: the instance is ready when 9200 is, whatever
+ * Dashboards is doing.
+ */
+/**
+ * PostgreSQL HA durability (selfhost#2582) - how long a COMMIT waits for a standby to flush
+ * the WAL. Three modes, and the difference between them is what happens when no standby is
+ * healthy:
+ *
+ * - `async`    - the primary acks locally. Fastest, and RPO > 0: a commit can be lost if the
+ *                primary dies before a standby has it.
+ * - `preferred`- waits for healthy standbys, and DEGRADES to no-wait when none are healthy. It
+ *                never blocks writes, which is also why it cannot promise zero data loss.
+ * - `required` - RPO 0, and the honest version of that promise: dead standby names stay in the
+ *                wait set, so when the SLA cannot be held THE PRIMARY STOPS ACCEPTING WRITES
+ *                rather than quietly acking data no survivor holds. Only `required` while
+ *                `sla_held` is true may be described to a user as zero-data-loss.
+ *
+ * `sync_number` is how many standbys must ack (default 1) and cannot exceed the group's HA
+ * standby count. A 2-node `required` cluster has NO automated failover - promoting the single
+ * standby would be the thing that loses data - so it needs `no_auto_failover_ack`.
+ */
+const PG_DURABILITY_MODES = ["async", "preferred", "required"];
+const PG_DURABILITY_DEFAULT_SYNC_NUMBER = 1;
+const OPENSEARCH_DASHBOARDS_PORT = 5601;
+const DASHBOARDS_MIN_RAM_GIB = 4;
+const DASHBOARDS_RECOMMENDED_RAM_GIB = 8;
 /**
  * RAM of an instance type, from the same reference-data endpoint `get_instance_types_for_region`
  * serves (rate-limit exempt). Returns null when the type or the lookup is unavailable - callers
@@ -285,10 +350,13 @@ platform margin is folded into each line rather than billed separately, matching
 console and the website - so quote these numbers to the user as-is and never add a
 platform fee on top.
 
-Pass type_of_dbms whenever you know the engine. ClickHouse prices differently: with
-replica_count=1 the platform provisions a third, keeper-only node (${CLICKHOUSE_KEEPER_INSTANCE_TYPE} + ${CLICKHOUSE_KEEPER_STORAGE_GB} GB) to hold
-the Raft quorum, and this tool only includes it when it knows the engine. Leave the engine
-out for a ClickHouse cluster and the estimate understates the real bill.
+PASS type_of_dbms WHENEVER YOU KNOW THE ENGINE. Two engines provision nodes the pricing
+endpoint cannot see, and this tool only adds them when it knows the engine:
+- clickhouse with replica_count=1 gets a dedicated keeper-only node (${CLICKHOUSE_KEEPER_INSTANCE_TYPE} + ${CLICKHOUSE_KEEPER_STORAGE_GB} GB)
+  holding the Raft quorum. At 2+ replicas the quorum is embedded and there is no extra node.
+- opensearch with replica_count >= 1 gets ${OPENSEARCH_MANAGER_COUNT} dedicated cluster-manager nodes on top of the
+  data nodes, each inheriting the data nodes' storage size. replica_count=1 is ${opensearchNodeCount(1)} machines,
+  not 2, so leaving the engine out understates that cluster by three whole nodes.
 
 CLICKHOUSE ESTIMATES RUN LOW EVEN WITH THE ENGINE PASSED, and the keeper node is not the
 reason. The estimate endpoint applies ONE flat platform margin to every engine, while
@@ -308,7 +376,7 @@ different margin entirely. Use \`list_server_types\`, which returns real per-loc
         public_ipv4_count: z.number().int().min(0).optional().describe("Number of public IPv4 addresses (default: 0)"),
         iops: z.number().optional().describe("Provisioned IOPS (for gp3/io1/io2). Defaults to storage type baseline if omitted."),
         throughput_mbps: z.number().optional().describe("Throughput in MB/s (for gp3). Defaults to storage type baseline if omitted."),
-        type_of_dbms: z.enum(ENGINES).optional().describe("Engine being priced. Only changes the maths for clickhouse with replica_count=1, where the billed Keeper node is added to the estimate."),
+        type_of_dbms: z.enum(ENGINES).optional().describe("Engine being priced. PASS IT FOR CLICKHOUSE AND OPENSEARCH OR THE ESTIMATE IS WRONG: clickhouse at replica_count=1 adds a billed Keeper node, and opensearch at replica_count>=1 adds 3 billed cluster-manager nodes. Both are invisible to the pricing endpoint."),
     }, async ({ region, instance_type, storage_type, storage_size_gb, database_count, replica_count, public_ipv4_count, iops, throughput_mbps, type_of_dbms }) => {
         const estimate = (overrides) => {
             const body = {
@@ -341,6 +409,25 @@ different margin entirely. Use \`list_server_types\`, which returns real per-loc
         // The pricing endpoint is engine-agnostic, so the standalone ClickHouse Keeper node has
         // to be priced as its own unit and folded in: a t4g.small with a 20 GB volume that
         // inherits the primary's storage settings, and no public IPv4 of its own.
+        let managers = null;
+        let managerError = null;
+        if (needsOpensearchManagers(type_of_dbms ?? "", replica_count ?? 0)) {
+            // Managers inherit the data nodes' storage and carry no public IPv4 of their own.
+            // Priced as ONE node here and multiplied out below, so the per-node figure stays
+            // readable in the breakdown.
+            const managerResult = await estimate({
+                instance_type: OPENSEARCH_DEFAULT_MANAGER_TYPE,
+                database_count: 1,
+                replica_count: 0,
+                public_ipv4_count: 0,
+            });
+            if (managerResult.success) {
+                managers = managerResult.data;
+            }
+            else {
+                managerError = `Could not price the ${OPENSEARCH_MANAGER_COUNT} cluster-manager nodes (${managerResult.statusCode}): ${managerResult.message}`;
+            }
+        }
         let keeper = null;
         let keeperError = null;
         if (needsClickhouseKeeper(type_of_dbms ?? "", replica_count ?? 0)) {
@@ -378,14 +465,25 @@ different margin entirely. Use \`list_server_types\`, which returns real per-loc
             const keeperAllIn = foldMarkup(keeper);
             lines.push("", `ClickHouse Keeper node (${CLICKHOUSE_KEEPER_INSTANCE_TYPE} + ${CLICKHOUSE_KEEPER_STORAGE_GB} GiB ${keeper.storage_type}):`, `  Compute:     $${keeperAllIn.compute.toFixed(2)}`, `  Storage:     $${keeperAllIn.storage.toFixed(2)}`, `  Subtotal:    $${keeper.total_monthly.toFixed(2)}`, "  (Required third quorum member because replica_count=1. Two replicas instead run the", "   quorum embedded on the data nodes - no Keeper node and no third line item.)");
         }
-        const total = data.total_monthly + (keeper?.total_monthly ?? 0);
+        const managersMonthly = managers ? managers.total_monthly * OPENSEARCH_MANAGER_COUNT : 0;
+        if (managers) {
+            const managerAllIn = foldMarkup(managers);
+            lines.push("", `OpenSearch cluster managers (${OPENSEARCH_MANAGER_COUNT} x ${OPENSEARCH_DEFAULT_MANAGER_TYPE} + ${managers.storage_size_gb} GiB ${managers.storage_type}):`, `  Per node:    compute $${managerAllIn.compute.toFixed(2)} + storage $${managerAllIn.storage.toFixed(2)} = $${managers.total_monthly.toFixed(2)}`, `  Subtotal:    $${managersMonthly.toFixed(2)} (${OPENSEARCH_MANAGER_COUNT} nodes)`, `  (A quorum needs an odd number of managers, so HA starts at ${OPENSEARCH_MANAGER_COUNT} dedicated nodes rather than`, "   folding the role onto the data nodes. They carry no search load but bill in full.", `   Priced at the ${OPENSEARCH_DEFAULT_MANAGER_TYPE} default - pass manager_instance_type to create_instance to change it.)`);
+        }
+        const total = data.total_monthly + (keeper?.total_monthly ?? 0) + managersMonthly;
         lines.push("", `TOTAL:         $${total.toFixed(2)}/month`);
         if (keeper) {
             lines.push(`               (${data.replica_count + 1} data nodes $${data.total_monthly.toFixed(2)} + Keeper $${keeper.total_monthly.toFixed(2)})`);
         }
+        if (managers) {
+            lines.push(`               (${data.replica_count + 1} data nodes $${data.total_monthly.toFixed(2)} + ${OPENSEARCH_MANAGER_COUNT} managers $${managersMonthly.toFixed(2)} = ${opensearchNodeCount(replica_count ?? 0)} nodes total)`);
+        }
         if (keeperError) {
             lines.push("", `⚠️  ${keeperError}`, "This total EXCLUDES the Keeper node that a 1-replica ClickHouse cluster requires - the real bill will be higher.");
         }
+        if (managerError) {
+            lines.push("", `⚠️  ${managerError}`, `This total EXCLUDES the ${OPENSEARCH_MANAGER_COUNT} cluster-manager nodes an HA OpenSearch cluster requires - the real bill will be materially higher.`);
+        }
         lines.push("", `Pricing model: ${data.pricing_model}`, `Currency:      ${data.currency}`, "All-in: every line already includes the platform margin. Charged hourly against wallet credit.");
         return { content: [{ type: "text", text: lines.join("\n") }] };
     });
@@ -423,45 +521,94 @@ CLICKHOUSE SPECIFICS (they differ from the other engines - read before creating
 - Connect over HTTP on ${ENGINE_DEFAULT_PORT.clickhouse} (native TCP on ${CLICKHOUSE_NATIVE_PORT}) as user \`admin\`. Multi-AZ clusters
   expose the distributed cluster \`${CLICKHOUSE_CLUSTER_NAME}\`.
 - Use ${ENGINE_DEFAULT_PORT.clickhouse} as the port on allowed_cidr_ranges entries, not 5432/3306.
-- Versions: ${CLICKHOUSE_VERSIONS.join(", ")} (defaults to the ${CLICKHOUSE_DEFAULT_VERSION} LTS).
+- Version: ${CLICKHOUSE_DEFAULT_VERSION} LTS, the only one the platform supports. It is pinned at create and
+  CANNOT be changed later - moving versions means a new instance plus a restore or migration into it.
+
+OPENSEARCH SPECIFICS (a search/analytics engine, not a relational database - read before creating one):
+- Minimum 4 GiB RAM: the JVM heap takes 50% of available memory. Find eligible sizes with
+  get_instance_types_for_region using min_memory=4.
+- HA IS A CLUSTER TOPOLOGY, AND \`replica_count\` BUYS FAR MORE MACHINES THAN IT LOOKS:
+    replica_count=0 → 1 node (one all-in-one node; dev / non-HA only)
+    replica_count=1 → ${opensearchNodeCount(1)} NODES: 3 dedicated cluster-manager nodes + 2 data nodes  ← HA minimum
+    replica_count=2 → ${opensearchNodeCount(2)} nodes: 3 managers + 3 data
+    replica_count=N → N+4 nodes
+  Going from no HA to HA is a 1 → ${opensearchNodeCount(1)} node jump, not 1 → 2, because a quorum needs an odd
+  number of managers and two would be split-brain-prone. ALL of those nodes bill. Price it
+  with estimate_instance_cost using type_of_dbms="opensearch" and the real replica_count, and
+  quote that number before creating - this is the single most expensive surprise on the
+  platform if you skip it.
+- multi_az REQUIRES replica_count >= 1, and unlike every other engine it CANNOT BE TOGGLED
+  LATER in either direction. Enabling afterwards would build a 2-manager set with 0-replica
+  indices; disabling would terminate nodes with no shard drain. Decide HA at create or plan on
+  creating a new cluster and restoring into it.
+- manager_instance_type sets the three managers' size (default ${OPENSEARCH_DEFAULT_MANAGER_TYPE}). Same ${OPENSEARCH_MANAGER_RAM_FLOOR_GIB} GiB floor -
+  managers carry no indexing or search load, so they can be smaller than the data nodes, but
+  not smaller than that. They inherit the endpoint node's storage size.
+- ALWAYS HTTPS ON ${ENGINE_DEFAULT_PORT.opensearch}, never plaintext. Use ${ENGINE_DEFAULT_PORT.opensearch} on allowed_cidr_ranges entries. Transport
+  port 9300 is node-to-node only and is never customer-facing.
+- TLS CAVEAT WORTH STATING UP FRONT: certs are per-cluster and CA-signed, and the node cert's
+  SAN covers the private IP rather than the public DNS name - so strict hostname verification
+  against the endpoint fails even with the CA trusted. Tell users to trust the CA with relaxed
+  hostname checking, or connect from inside the VPC. \`curl -k\` for a quick start. The cluster
+  CA is not downloadable through the API yet.
+- No named databases (like redis) - do not ask for or display a database name.
+- Vector search is BUILT IN (the k-NN plugin ships with the engine), so an embeddings workload
+  needs no extension here - that is a postgres/pgvector concern.
+- dashboards_enabled turns on the OpenSearch Dashboards UI on port ${OPENSEARCH_DASHBOARDS_PORT}. It needs ${DASHBOARDS_MIN_RAM_GIB} GiB minimum
+  (${DASHBOARDS_RECOMMENDED_RAM_GIB} GiB recommended) because it runs alongside the JVM on the endpoint node, and it can be
+  turned on or off later with set_opensearch_dashboards. It never blocks readiness.
+- Version: ${ENGINE_DEFAULT_VERSION.opensearch} is sent by default. Do not omit db_version - the backend adapter has no
+  default override, so an omitted field resolves to ${ENGINE_VERSIONS.opensearch[ENGINE_VERSIONS.opensearch.length - 1]}, the oldest.
 
 ENGINE-SPECIFIC FOLLOW-UPS (route to the right tools per engine after creating):
-- Connection pooling: PgBouncer for postgres, ProxySQL for mysql, CHProxy for clickhouse, none for redis.
-- Performance tuning: the pg-config tools for postgres, the mysql-config tools for mysql; none for redis or clickhouse.
-- PITR applies to postgres and mysql only - not redis, not clickhouse.
-- database-users applies to postgres, mysql and clickhouse - not redis.
-- postgresql_config and the two extension flags are postgres-only.
-- db_version can be upgraded in place on clickhouse only (upgrade_clickhouse_version).
-
-POSTGRES EXTENSIONS (neither is a separate engine - both are postgres + a flag):
-- timescaledb_enabled → TimescaleDB (hypertables, continuous aggregates, compression) for
-  time-series workloads. Installing it at create costs nothing extra; enabling it later
-  restarts PostgreSQL once (enable_timescaledb).
-- vector_enabled → pgvector (the \`vector\` type + similarity search) for embeddings.
-- Both can be on at once here, and both are ENABLE-ONLY - the backend refuses to turn
-  either off afterwards, so ask the user before setting them.`, {
+- Connection pooling: PgBouncer for postgres, ProxySQL for mysql, CHProxy for clickhouse, none for redis or opensearch.
+- Performance tuning: the pg-config tools for postgres, the mysql-config tools for mysql; none for redis, clickhouse or opensearch.
+- PITR applies to postgres and mysql only - not redis, not clickhouse, not opensearch (there is no
+  WAL-G equivalent, so opensearch durability is EBS volume snapshots and whole-volume restores only).
+- database-users applies to postgres, mysql, clickhouse and opensearch - not redis.
+- postgresql_config and \`extensions\` are postgres-only.
+- db_version is fixed for the life of the instance on every engine. There is no in-place version
+  upgrade anywhere on the platform any more (selfhost#2580 withdrew the ClickHouse one).
+
+POSTGRES EXTENSIONS - pass \`extensions: [...]\` (an ARRAY of catalog names, not booleans):
+- TimescaleDB is \`timescaledb\`, pgvector is \`pgvector\` (or its SQL alias \`vector\`). The old
+  \`timescaledb_enabled\` / \`vector_enabled\` flags were REMOVED backend-side and are now
+  IGNORED rather than rejected - sending them provisions an instance with no extensions at all.
+- Call \`list_postgres_extension_catalog\` with the \`db_version\` you are about to use to see
+  what is on offer; compatibility is per entry (\`pg_textsearch\` needs PostgreSQL 17 or 18).
+  Do not work from a memorised list.
+- Extensions chosen here are installed during provisioning, so the ones that need a PostgreSQL
+  restart cost nothing extra at create - there is no restart to warn about on this path.
+- Readiness accounts for them: the instance is not marked ready while any requested extension
+  is missing. Any of them can be added later with \`enable_instance_extensions\`, but NONE can
+  ever be removed, so ask the user before adding to the list.`, {
         organization_id: z.string().optional().describe("Organization PID (defaults to active org)"),
         region: z.string().min(1, "AWS region is required (e.g. us-east-1)"),
         identifier: z.string().min(1, "Database instance name"),
         instance_type: z.string().min(1, "EC2 instance type (e.g. t3.micro, r6i.xlarge)"),
         type_of_dbms: z.enum(ENGINES).describe("Database engine"),
         storage: storageSchema,
-        db_version: z.string().optional().describe(`Database version. postgres: ${ENGINE_VERSIONS.postgres.join(", ")} (default ${ENGINE_DEFAULT_VERSION.postgres}). mysql: ${ENGINE_VERSIONS.mysql.join(", ")} (default ${ENGINE_DEFAULT_VERSION.mysql}, the stable release). redis: ${ENGINE_VERSIONS.redis.join(", ")} (default ${ENGINE_DEFAULT_VERSION.redis}). clickhouse: ${ENGINE_VERSIONS.clickhouse.join(", ")} (default ${ENGINE_DEFAULT_VERSION.clickhouse}, the LTS). Omitting this sends the default explicitly - the backend's own fallback is the oldest major it still supports.`),
-        username: z.string().regex(/^[a-z_][a-z0-9_-]{0,30}$/i).optional().describe("Database username (default: admin). Redis ignores this (auth is a single requirepass/password); it applies to postgres, mysql and clickhouse. On clickhouse the customer user is `admin` - the built-in `default` user is platform-internal and not usable."),
+        db_version: z.string().optional().describe(`Database version. postgres: ${ENGINE_VERSIONS.postgres.join(", ")} (default ${ENGINE_DEFAULT_VERSION.postgres}). mysql: ${ENGINE_VERSIONS.mysql.join(", ")} (default ${ENGINE_DEFAULT_VERSION.mysql}, the stable release). redis: ${ENGINE_VERSIONS.redis.join(", ")} (default ${ENGINE_DEFAULT_VERSION.redis}). clickhouse: ${ENGINE_VERSIONS.clickhouse.join(", ")} (default ${ENGINE_DEFAULT_VERSION.clickhouse}, the LTS and the only supported version). opensearch: ${ENGINE_VERSIONS.opensearch.join(", ")} (default ${ENGINE_DEFAULT_VERSION.opensearch}). Omitting this sends the default explicitly - the backend's own fallback is the oldest major it still supports.`),
+        username: z.string().regex(/^[a-z_][a-z0-9_-]{0,30}$/i).optional().describe("Database username (default: admin). Redis ignores this (auth is a single requirepass/password); it applies to postgres, mysql, clickhouse and opensearch. On clickhouse the customer user is `admin` - the built-in `default` user is platform-internal and not usable. On opensearch the customer user holds `all_access` and the internal `admin` superuser is never surfaced."),
         custom_password: z.string().min(8).max(128).optional().describe("Database password (8-128 printable ASCII chars). Auto-generated if omitted."),
         description: z.string().optional(),
         cloud_credential_id: z.string().optional().describe("Credential PID from list_credentials. Use is_platform_managed=true credential for SelfHost's cloud, or is_platform_managed=false for BYOC. Always ask the user which they prefer."),
         vpc_id: z.string().optional().describe("VPC ID - REQUIRED when using BYOC credentials (is_platform_managed=false). Use list_vpcs and only pick from the 'public' group. Not needed for platform-managed."),
-        multi_az: z.boolean().optional().describe("Enable multi-AZ replication (default: false). Required for any replica_count on clickhouse - its replicas only join the cluster when the Keeper quorum is configured, which happens on multi-AZ creates."),
-        replica_count: z.number().int().min(1).max(5).optional().describe("Replicas to provision alongside the primary when multi_az is on. postgres/mysql/redis: 1 or 2. clickhouse: 1-5, default 2 (1 adds a billed Keeper node - see the ClickHouse notes)."),
+        multi_az: z.boolean().optional().describe("Enable multi-AZ replication (default: false). Required for any replica_count on clickhouse and opensearch. On opensearch it is PERMANENT - the only engine where HA cannot be toggled after create."),
+        replica_count: z.number().int().min(1).max(5).optional().describe("Replicas to provision alongside the primary when multi_az is on. postgres/mysql/redis: 1 or 2. clickhouse: 1-5, default 2 (1 adds a billed Keeper node). opensearch: buys DATA nodes and silently adds 3 billed manager nodes on top - 1 means 5 machines. See the engine notes."),
+        manager_instance_type: z.string().optional().describe("opensearch only: size of the 3 dedicated cluster-manager nodes when replica_count >= 1 (default t4g.medium, 4 GiB floor). They carry no search load, so they can be smaller than the data nodes."),
+        dashboards_enabled: z.boolean().optional().describe("opensearch only: install the OpenSearch Dashboards UI on port 5601. Needs 4 GiB RAM minimum (8 recommended) since it shares the endpoint node with the JVM. Can be changed later with set_opensearch_dashboards."),
+        confirm_node_count: z.boolean().optional().describe("opensearch only: required acknowledgement that replica_count >= 1 provisions 3 extra billed cluster-manager nodes. Omit it first to be told the real machine count, then set true once the user has seen the price."),
+        data_durability: z.enum(PG_DURABILITY_MODES).optional().describe("postgres only: how long a COMMIT waits for a standby. `async` = local ack (RPO > 0). `preferred` = wait when standbys are healthy, degrade when not (never blocks). `required` = RPO 0, and BLOCKS WRITES when it cannot be held. Defaults to `preferred` with multi_az, `async` without."),
+        sync_number: z.number().int().min(1).optional().describe("postgres only: how many standbys must ack a commit (default 1). Cannot exceed replica_count."),
+        no_auto_failover_ack: z.boolean().optional().describe("postgres only: required when data_durability=`required` with exactly 1 replica - that topology has NO automated failover, and this is the explicit acceptance of it."),
         delete_protection: z.boolean().optional().describe("Prevent accidental deletion (default: true recommended)"),
         backup_enabled: z.boolean().optional().describe("Enable automated backups (default: true recommended)"),
         dlm_policy_config: dlmPolicySchema.optional().describe("Backup schedule config (required if backup_enabled)"),
         allowed_cidr_ranges: z.array(cidrRangeSchema).max(24).optional().describe("IP whitelist (max 24 CIDR ranges)"),
         tags: z.array(tagSchema).optional().describe("AWS resource tags"),
         snapshot_id: z.string().optional().describe("Restore from a backup snapshot ID"),
-        timescaledb_enabled: z.boolean().optional().describe("Install TimescaleDB for time-series data (postgres only). Enable-only - it cannot be turned off later, so confirm with the user first."),
-        vector_enabled: z.boolean().optional().describe("Install pgvector for embeddings / similarity search (postgres only). Enable-only - it cannot be turned off later, so confirm with the user first."),
+        extensions: z.array(z.string().min(1)).optional().describe("PostgreSQL extensions to install during provisioning, by catalog name, e.g. [\"pgvector\", \"pg_stat_statements\"]. postgres only. Read `list_postgres_extension_catalog` first - names are validated server-side and an incompatible one is a 422. None can be removed later."),
         postgresql_config: z.record(z.unknown()).optional().describe("PostgreSQL parameter overrides (use preview_pg_config to see available params)"),
         iam_role_arn: z.string().optional().describe("IAM role ARN for the EC2 instance"),
         db_port: z.number().int().min(0).max(65535).optional().describe(`Database port (default ${ENGINE_DEFAULT_PORT.postgres} postgres, ${ENGINE_DEFAULT_PORT.mysql} mysql, ${ENGINE_DEFAULT_PORT.redis} redis, ${ENGINE_DEFAULT_PORT.clickhouse} clickhouse HTTP)`),
@@ -484,19 +631,16 @@ POSTGRES EXTENSIONS (neither is a separate engine - both are postgres + a flag):
         if (params.db_version && !ENGINE_VERSIONS[engine].includes(params.db_version)) {
             return { content: [{ type: "text", text: `'${params.db_version}' is not a supported ${engine} version. Supported: ${ENGINE_VERSIONS[engine].join(", ")}.` }] };
         }
-        // Extension flags are postgres-only. The backend silently forces them false on other
-        // engines, which would look like a successful "TimescaleDB instance" that has none -
-        // so refuse instead of quietly dropping the request.
+        // `extensions` is postgres-only. The backend IGNORES the list on other engines, which
+        // would look like a successful "pgvector instance" that has none - so refuse instead of
+        // quietly dropping the request.
         if (engine !== "postgres") {
-            const requested = [
-                params.timescaledb_enabled ? "timescaledb_enabled" : null,
-                params.vector_enabled ? "vector_enabled" : null,
-            ].filter(Boolean);
+            const requested = params.extensions ?? [];
             if (requested.length > 0) {
                 return {
                     content: [{
                             type: "text",
-                            text: `${requested.join(" and ")} ${requested.length > 1 ? "are" : "is"} PostgreSQL-only and would be ignored on ${engine}. Create this as postgres to get ${requested.length > 1 ? "them" : "it"}, or drop the flag${requested.length > 1 ? "s" : ""}.${engine === "clickhouse" ? " (For analytics workloads ClickHouse is already columnar - it needs no extension.)" : ""}`,
+                            text: `extensions (${requested.join(", ")}) ${requested.length > 1 ? "are" : "is"} PostgreSQL-only and would be IGNORED on ${engine} - the instance would come up with none. Create this as postgres, or drop the list.${engine === "clickhouse" ? " (For analytics workloads ClickHouse is already columnar - it needs no extension.)" : ""}${engine === "opensearch" ? " (OpenSearch ships k-NN vector search in the engine - it needs no extension for embeddings.)" : ""}`,
                         }],
                 };
             }
@@ -520,6 +664,26 @@ POSTGRES EXTENSIONS (neither is a separate engine - both are postgres + a flag):
                     }],
             };
         }
+        else if (engine === "opensearch" && replicaCount !== undefined && replicaCount > 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `OpenSearch replicas require multi_az=true - the backend refuses any replica_count without it. Pass multi_az=true (replica_count defaults to ${ENGINE_DEFAULT_REPLICAS.opensearch}), or drop replica_count for a single all-in-one node.\n\nBefore you do: multi_az=true with replica_count=${ENGINE_DEFAULT_REPLICAS.opensearch} provisions ${opensearchNodeCount(ENGINE_DEFAULT_REPLICAS.opensearch)} BILLED NODES (3 cluster managers + 2 data), and it cannot be undone later. Price it with estimate_instance_cost first.`,
+                    }],
+            };
+        }
+        // The three cluster managers are as real as any other node on the bill, and nothing
+        // downstream says so: `replica_count` reads like "extra machines" everywhere else.
+        // Refuse to provision five machines for a caller who asked for two without being told.
+        if (needsOpensearchManagers(engine, replicaCount ?? 0) && params.confirm_node_count !== true) {
+            const total = opensearchNodeCount(replicaCount);
+            return {
+                content: [{
+                        type: "text",
+                        text: `replica_count=${replicaCount} on OpenSearch provisions ${total} NODES, not ${replicaCount + 1}: 3 dedicated cluster-manager nodes (${params.manager_instance_type ?? OPENSEARCH_DEFAULT_MANAGER_TYPE}) plus ${replicaCount + 1} data nodes (${params.instance_type}). Every one of them bills, and the managers inherit the data nodes' ${params.storage.size} GiB storage.\n\nThis topology is also PERMANENT - OpenSearch HA cannot be toggled off later.\n\nPrice it with estimate_instance_cost (type_of_dbms="opensearch", replica_count=${replicaCount}), show the user the total, then call again with confirm_node_count=true.`,
+                    }],
+            };
+        }
         // Hard RAM floor (backend MIN_RAM_GB). Best-effort pre-check so a doomed create fails
         // here with a useful message instead of after the provisioning call.
         const minRamGiB = ENGINE_MIN_RAM_GIB[engine];
@@ -534,6 +698,53 @@ POSTGRES EXTENSIONS (neither is a separate engine - both are postgres + a flag):
                 };
             }
         }
+        // PostgreSQL HA durability. Mirrors `validate_ha_durability_create_params!` so a doomed
+        // create explains itself instead of returning a bare 422, and so the write-blocking
+        // consequence of `required` is stated before any money is spent.
+        if (engine === "postgres") {
+            const mode = params.data_durability ?? (multiAz ? "preferred" : "async");
+            if (multiAz && mode !== "async") {
+                const syncNumber = params.sync_number ?? PG_DURABILITY_DEFAULT_SYNC_NUMBER;
+                const standbys = replicaCount ?? 0;
+                if (syncNumber > standbys) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `sync_number ${syncNumber} needs ${syncNumber} HA standbys but this create asks for ${standbys}. Raise replica_count to at least ${syncNumber}, or lower sync_number.`,
+                            }],
+                    };
+                }
+                if (mode === "required" && standbys === 1 && params.no_auto_failover_ack !== true) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: "A 2-node `required` cluster (1 replica) has NO AUTOMATED FAILOVER: promoting the only standby is exactly what would lose the data `required` exists to protect, so the platform will not do it by itself. If the primary fails, someone has to intervene.\n\nThat is a deliberate trade - RPO 0 at the cost of automatic recovery. Either raise replica_count to 2 so failover is safe, or confirm the user accepts manual failover and pass no_auto_failover_ack=true.",
+                            }],
+                    };
+                }
+            }
+        }
+        else if (params.data_durability || params.sync_number !== undefined || params.no_auto_failover_ack !== undefined) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `data_durability / sync_number / no_auto_failover_ack are PostgreSQL-only and would be ignored on ${engine}. Drop them, or create this as postgres.`,
+                    }],
+            };
+        }
+        // Managers have their own floor, checked separately because they are usually smaller
+        // than the data nodes - a 2 GiB manager OOMs its JVM under quorum load.
+        if (engine === "opensearch" && params.manager_instance_type && needsOpensearchManagers(engine, replicaCount ?? 0)) {
+            const managerRam = await lookupInstanceMemoryGiB(params.region, params.manager_instance_type);
+            if (managerRam !== null && managerRam < OPENSEARCH_MANAGER_RAM_FLOOR_GIB) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `manager_instance_type ${params.manager_instance_type} has ${managerRam} GiB RAM, below the ${OPENSEARCH_MANAGER_RAM_FLOOR_GIB} GiB floor for an OpenSearch cluster manager (the backend rejects it). ${OPENSEARCH_DEFAULT_MANAGER_TYPE} is the smallest production-eligible manager.`,
+                        }],
+                };
+            }
+        }
         // Build request body - only include defined fields
         const body = {
             organization_id: orgId,
@@ -568,6 +779,16 @@ POSTGRES EXTENSIONS (neither is a separate engine - both are postgres + a flag):
         // Resolved, not raw: multi-AZ ClickHouse without an explicit count would 422 otherwise.
         if (replicaCount !== undefined)
             body.replica_count = replicaCount;
+        if (params.manager_instance_type)
+            body.manager_instance_type = params.manager_instance_type;
+        if (params.dashboards_enabled !== undefined)
+            body.dashboards_enabled = params.dashboards_enabled;
+        if (params.data_durability)
+            body.data_durability = params.data_durability;
+        if (params.sync_number !== undefined)
+            body.sync_number = params.sync_number;
+        if (params.no_auto_failover_ack !== undefined)
+            body.no_auto_failover_ack = params.no_auto_failover_ack;
         if (params.delete_protection !== undefined)
             body.delete_protection = params.delete_protection;
         if (params.backup_enabled !== undefined)
@@ -580,10 +801,8 @@ POSTGRES EXTENSIONS (neither is a separate engine - both are postgres + a flag):
             body.tags = params.tags;
         if (params.snapshot_id)
             body.snapshot_id = params.snapshot_id;
-        if (params.timescaledb_enabled)
-            body.timescaledb_enabled = true;
-        if (params.vector_enabled)
-            body.vector_enabled = true;
+        if (params.extensions?.length)
+            body.extensions = params.extensions;
         if (params.postgresql_config)
             body.postgresql_config = params.postgresql_config;
         if (params.iam_role_arn)
@@ -615,19 +834,16 @@ POSTGRES EXTENSIONS (neither is a separate engine - both are postgres + a flag):
             `Group ID: ${data.group_id}`,
             `Organization: ${data.organization_id}`,
         ];
-        if (engine === "postgres" && (params.timescaledb_enabled || params.vector_enabled)) {
-            const extensions = [
-                params.timescaledb_enabled ? "TimescaleDB" : null,
-                params.vector_enabled ? "pgvector" : null,
-            ].filter(Boolean);
-            lines.push("", `${extensions.join(" + ")} ${extensions.length > 1 ? "are" : "is"} installed during provisioning (no restart needed at create).`);
-            if (params.timescaledb_enabled) {
-                lines.push("- Start with: CREATE TABLE ... then SELECT create_hypertable('your_table', 'time');", "- The timescaledb_* metrics (hypertable/chunk counts, compression ratio, total size) join this instance's `postgresql.database` alert set.");
+        if (engine === "postgres" && params.extensions?.length) {
+            const requested = params.extensions;
+            lines.push("", `Extensions installed during provisioning (no restart needed on this path): ${requested.join(", ")}.`, "- Each starts as a `pending` row and is only marked `enabled` once it is created AND its smoke test passes. The instance is not marked ready while any is missing, so check `list_instance_extensions` if readiness stalls.");
+            if (requested.includes("timescaledb")) {
+                lines.push("- TimescaleDB: start with CREATE TABLE ... then SELECT create_hypertable('your_table', 'time');", "- The timescaledb_* metrics (hypertable/chunk counts, compression ratio, total size) join this instance's `postgresql.database` alert set.");
             }
-            if (params.vector_enabled) {
-                lines.push("- The `vector` column type and similarity operators are ready to use.");
+            if (requested.includes("pgvector") || requested.includes("vector")) {
+                lines.push("- pgvector: the `vector` column type and similarity operators are ready to use.");
             }
-            lines.push(`- Neither extension can be disabled later.`);
+            lines.push("- None of them can be removed later - there is no disable path.");
         }
         if (engine === "clickhouse") {
             lines.push("", `ClickHouse ${dbVersion}`, `- Connect over HTTP on port ${ENGINE_DEFAULT_PORT.clickhouse} (native TCP on ${CLICKHOUSE_NATIVE_PORT}).`);
@@ -638,7 +854,21 @@ POSTGRES EXTENSIONS (neither is a separate engine - both are postgres + a flag):
                 }
                 lines.push("- Provisioning a ClickHouse cluster runs ~11 tasks and takes longer than Postgres/MySQL. Poll refresh_instance_group.");
             }
-            lines.push("- Follow-ups: enable_chproxy for connection pooling, database-users for SQL users, upgrade_clickhouse_version for version bumps. No PITR and no config tuning on this engine.");
+            lines.push("- Follow-ups: enable_chproxy for connection pooling, database-users for SQL users. No PITR, no config tuning and no version change on this engine.");
+        }
+        if (engine === "opensearch") {
+            lines.push("", `OpenSearch ${dbVersion}`, `- Connect over HTTPS on port ${ENGINE_DEFAULT_PORT.opensearch} - never plaintext. There is no database name to supply.`, "- Quick check once ready: curl -k -u \"<username>:<password>\" \"https://<dns_name>:" + ENGINE_DEFAULT_PORT.opensearch + "/_cluster/health?pretty\"", "- Use `dns_name`, not the public DNS: it is the endpoint node's CNAME and it survives failover and resize.", "- TLS: the cert's SAN covers the node's private IP, not the public endpoint, so strict hostname verification fails even with the cluster CA trusted. Use CA-trust with relaxed hostname checking, or connect from inside the VPC. `-k` is for quick starts only, and the CA is not downloadable through the API yet.");
+            if (multiAz) {
+                const dataNodes = replicaCount + 1;
+                lines.push(`- Cluster: ${dataNodes} data/ingest nodes + ${OPENSEARCH_MANAGER_COUNT} dedicated cluster managers = ${opensearchNodeCount(replicaCount)} NODES, all billed. The managers hold the leader-election quorum and carry no indexing or search load.`, "- This topology is PERMANENT. multi_az cannot be toggled on an OpenSearch cluster in either direction - changing it means creating a new cluster and restoring into it.", "- Poll `ha_ready` and `readiness_detail` rather than inferring health from `status`; `opensearch_node_role` tells you which node is which.");
+            }
+            else {
+                lines.push("- Single all-in-one node: no redundancy, so this is a dev / non-HA shape. HA cannot be added later - it needs a new cluster at replica_count >= 1 and a restore into it.");
+            }
+            if (params.dashboards_enabled) {
+                lines.push(`- Dashboards was requested and installs on port ${OPENSEARCH_DASHBOARDS_PORT} AFTER the instance is ready - it is never part of provisioning or readiness. Watch it with get_opensearch_dashboards; a \`failed\` or \`degraded\` state leaves the cluster itself perfectly healthy.`);
+            }
+            lines.push("- Follow-ups: database-users for security-plugin users, set_opensearch_dashboards for the UI. No pooling, no config tuning, no PITR and no version change on this engine.", "- Vector search (k-NN) is already in the engine - no extension needed.");
         }
         return { content: [{ type: "text", text: lines.join("\n") }] };
     });
@@ -673,6 +903,12 @@ READINESS IS ONE FIELD. \`ready\` is computed server-side and is the field to tr
 
 If an instance has been provisioning for more than about 15 minutes it is considered STUCK rather than slow - say so instead of advising the user to keep waiting.
 
+NOT EVERY NODE IN A GROUP IS A DATABASE. Two fields say which is which, and reading them avoids pointing a user at a node that cannot do what they asked:
+- \`clickhouse_node_role\` - \`keeper_only\` marks the Raft arbiter. It runs clickhouse-keeper, not clickhouse-server, so it holds no table data: no query stats, no data backup, no scaling policy. It is not a node to connect to, but it IS a node on the bill.
+- \`opensearch_node_role\` - which role this node carries in the cluster. Only the node with \`opensearch_endpoint: true\` is the client-facing 9200/DNS target; manager-only nodes serve no traffic and carry no data.
+
+A HOT STANDBY IS A READABLE REPLICA, NOT A WRITE TARGET, and it also cannot be scaled or reconfigured directly - those operations belong to its primary and the backend refuses them on a replica, naming the primary. When a user asks to change something on a node that turns out to be a replica, act on the primary instead of relaying a confusing refusal.
+
 \`deprecated_at\`, when set, marks the machine type as scheduled for retirement. Worth surfacing unprompted.`, {
         pid: z.string().optional().describe("Instance PID (e.g. awsinst_xxx)"),
         instance_id: z.string().optional().describe("AWS EC2 instance ID (alternative to pid)"),
@@ -708,7 +944,7 @@ Metric sets (same names alert rules use):
 - system: cpu_percent, memory_percent, disk_usage_percent, load_avg_1/5/15, swap_usage_percent, cpu_io_wait_percent
 - network: recv_bytes_per_sec, sent_bytes_per_sec
 - storage: disk_used_percent, disk_free_bytes, inodes_used_percent, read/write_io_per_second, ... reported PER MOUNT POINT and keyed \`storage[/mount]\` in the summary. Read the engine's data volume (e.g. \`storage[/selfhostdev/postgresql]\`), not \`storage[/]\` or \`storage[/boot]\` - a full /boot says nothing about database capacity.
-- <engine>.database: postgresql.database | mysql.database | redis.database | clickhouse.database - the engine's own counters. \`create_alert_rule\` carries the complete per-engine allow-list; these are the same names.
+- <engine>.database: postgresql.database | mysql.database | redis.database | clickhouse.database | opensearch.database - the engine's own counters. \`create_alert_rule\` carries the complete per-engine allow-list; these are the same names.
 - pgbouncer.stats appears once pooling is enabled. It is READABLE here but NOT alertable - the alert-rule catalog has no such metric_type, so a rule on it is rejected.
 
 On a replicated instance \`active_replica_count\` is the one to watch for a quietly-degraded cluster: it drops without the instance's own status changing. Ratio metrics (\`cache_hit_ratio\`, \`innodb_buffer_pool_hit_ratio\`, \`mark_cache_hit_ratio\`) are already on a 0-100 scale - do not multiply them by 100.
@@ -720,7 +956,7 @@ An empty result usually means the agent has not reported in that window (a stopp
             .describe("Inclusive start date, YYYY-MM-DD (default: yesterday). The window covers whole days."),
         end_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "YYYY-MM-DD").optional()
             .describe("Inclusive end date, YYYY-MM-DD (default: today)"),
-        metric_type: z.enum(["system", "network", "storage", "postgresql.database", "mysql.database", "redis.database", "clickhouse.database"]).optional()
+        metric_type: z.enum(["system", "network", "storage", "postgresql.database", "mysql.database", "redis.database", "clickhouse.database", "opensearch.database"]).optional()
             .describe("Only return this metric set. Cheaper than filtering client-side."),
         raw: z.boolean().optional().describe("Return every heartbeat frame instead of the summary. Verbose - use a narrow window and a single instance."),
     }, async ({ organization_id, instance_pid, start_date, end_date, metric_type, raw }) => {
@@ -776,12 +1012,12 @@ An empty result usually means the agent has not reported in that window (a stopp
     // history - activity counts, a `failover_completed` state, achievement badges - with no
     // button to trigger one. The endpoint is an operator escape hatch, so it stays out of an
     // LLM's reach: it drops every connection and the old master never returns as master.
-    server.tool("update_instance", "Update an instance's configuration. Some changes are synchronous (db_port, backup, CIDR ranges), others are async (instance_type, multi_az, storage). Cannot update replicas - update the master instead. Not handled here: enabling TimescaleDB or pgvector on postgres (enable_timescaledb / enable_pgvector - both irreversible) and ClickHouse version upgrades (upgrade_clickhouse_version).", {
+    server.tool("update_instance", "Update an instance's configuration. Some changes are synchronous (db_port, backup, CIDR ranges), others are async (instance_type, multi_az, storage). Cannot update replicas - update the master instead. Cannot change db_version on any engine: the platform withdrew the in-place ClickHouse upgrade in selfhost#2580, so a version change is now a new instance plus a restore or migration into it. Cannot toggle multi_az on OpenSearch - its HA is a cluster topology chosen at create. Not handled here either: enabling postgres extensions (see the extension tools) or the OpenSearch Dashboards UI (set_opensearch_dashboards).", {
         instance_id: z.string().min(1, "Instance PID is required"),
         identifier: z.string().optional().describe("New instance name"),
         delete_protection: z.boolean().optional(),
         instance_type: z.string().optional().describe("New EC2 instance type (triggers async resize)"),
-        multi_az: z.boolean().optional().describe("Enable/disable multi-AZ (triggers async operation)"),
+        multi_az: z.boolean().optional().describe("Enable/disable multi-AZ (triggers async operation). NOT AVAILABLE ON OPENSEARCH in either direction - its HA is a cluster topology fixed at create."),
         backup_enabled: z.boolean().optional(),
         db_port: z.number().int().min(0).max(65535).optional(),
         security_group_ids: z.array(z.string()).optional(),
@@ -819,40 +1055,139 @@ An empty result usually means the agent has not reported in that window (a stopp
             ],
         };
     });
-    server.tool("upgrade_clickhouse_version", `Upgrade a ClickHouse instance to a newer version in place (ClickHouse is the only engine with an in-place version upgrade - the backend rejects db_version changes on every other engine).
-
-Rules the backend enforces:
-- One version at a time, along the supported ladder: ${CLICKHOUSE_VERSIONS.join(" → ")}. Skipping a
-  step is rejected with the next allowed version named in the error.
-- The instance must have a registered agent.
-- Requesting the version it already runs is a no-op success.
-
-The upgrade restarts clickhouse-server on the node, so expect a brief interruption. Take a
-snapshot first (create_snapshot) - that is the rollback path if the upgrade goes wrong.`, {
-        instance_id: z.string().min(1, "Instance PID is required (e.g. awsinst_xxx)"),
-        db_version: z.enum(CLICKHOUSE_VERSIONS).describe("Target ClickHouse version - must be exactly one step above the current one"),
-        confirm: z.boolean().describe("Must be true to proceed. Ask the user to confirm, and recommend a snapshot first."),
-    }, async ({ instance_id, db_version, confirm }) => {
+    server.tool("set_postgres_durability", `Change a PostgreSQL group's HA durability mode - how long a COMMIT waits for a standby to flush the WAL before the primary acks it. This is the RPO dial.
+
+THE THREE MODES, and the only difference that matters is what happens when no standby is healthy:
+- \`async\` - the primary acks locally. Fastest, and RPO > 0: commits can be lost if the primary dies before a standby has them.
+- \`preferred\` - waits while standbys are healthy, and DEGRADES to no-wait when none are. It never blocks writes, which is exactly why it cannot be described as zero-data-loss.
+- \`required\` - RPO 0, honestly implemented: dead standby names stay in the wait set, so when the SLA cannot be held **THE PRIMARY STOPS ACCEPTING WRITES** rather than acking data no survivor holds. Availability is traded for durability, deliberately.
+
+ONLY \`required\` WHILE \`sla_held\` IS TRUE MAY BE CALLED ZERO DATA LOSS. Read \`sla_held\` and \`degraded\` from the response before telling a user their data is safe: \`required\` with \`sla_held: false\` means writes are being refused right now, and \`preferred\` with \`degraded: true\` means it is silently acking locally.
+
+RULES THE BACKEND ENFORCES:
+- PostgreSQL only, and on the MASTER only - replicas follow the group mode (a 422 names the primary).
+- THIS MUST BE SENT ALONE. Durability changes cannot ride along with any other instance update, so do not try to combine it with \`update_instance\`.
+- Moving TO \`preferred\` or \`required\` needs standbys actually streaming; without them the move is refused ("no streaming standbys to wait on"). Moving to \`async\` is always allowed - it is the honest escape hatch from a stalled \`required\` primary.
+- \`sync_number\` cannot exceed the group's HA standby count.
+- \`required\` with exactly one standby needs \`no_auto_failover_ack\` - see below.
+
+IF A PRIMARY IS STALLED because \`required\` cannot be held, the unwedge is moving to \`preferred\` (which starts shrinking the wait set) or \`async\` (which removes the wait). That is the answer to "my writes are hanging" on a \`required\` cluster, and it is worth offering immediately rather than diagnosing further.`, {
+        instance_id: z.string().min(1).describe("The MASTER instance's PID - not a replica"),
+        data_durability: z.enum(PG_DURABILITY_MODES).optional().describe("Target mode. Omit to keep the current one and change only sync_number."),
+        sync_number: z.number().int().min(1).optional().describe(`How many standbys must ack (default ${PG_DURABILITY_DEFAULT_SYNC_NUMBER}). Cannot exceed the group's HA standby count.`),
+        no_auto_failover_ack: z.boolean().optional().describe("Required for `required` with exactly 1 standby: that topology has no automated failover."),
+        confirm: z.boolean().describe("Must be true. Moving to `required` can block writes; moving to `async` gives up zero-data-loss."),
+    }, async ({ instance_id, data_durability, sync_number, no_auto_failover_ack, confirm }) => {
+        if (data_durability === undefined && sync_number === undefined && no_auto_failover_ack === undefined) {
+            return { content: [{ type: "text", text: "Nothing to change - pass at least one of data_durability / sync_number / no_auto_failover_ack." }] };
+        }
         if (!confirm) {
+            const consequence = data_durability === "required"
+                ? "`required` means the primary STOPS ACCEPTING WRITES whenever the synchronous standby set cannot be held. That is the point of it - RPO 0 - but it converts a standby failure into a write outage. With exactly one standby it also disables automated failover."
+                : data_durability === "async"
+                    ? "`async` removes the commit wait entirely: writes get faster and RPO becomes greater than zero, so commits can be lost if the primary dies. Any zero-data-loss claim stops being true."
+                    : data_durability === "preferred"
+                        ? "`preferred` waits while standbys are healthy and silently degrades to local acks when they are not, so it never blocks writes and never guarantees zero data loss."
+                        : "Changing sync_number changes how many standbys must ack each commit; raising it past the number of healthy standbys will stall writes in `required` mode.";
             return {
                 content: [{
                         type: "text",
-                        text: `About to upgrade ClickHouse on ${instance_id} to ${db_version}. This restarts clickhouse-server (brief interruption) and cannot be rolled back except by restoring a snapshot.\n\nTake a snapshot first with create_snapshot, then call again with confirm=true.`,
+                        text: `About to change durability on ${instance_id}${data_durability ? ` to \`${data_durability}\`` : ""}${sync_number !== undefined ? ` with sync_number ${sync_number}` : ""}.\n\n${consequence}\n\nCall again with confirm=true.`,
+                    }],
+            };
+        }
+        // The backend refuses a durability change that carries any other key, so this tool
+        // sends nothing else - same contract as set_postgres_tls.
+        const body = {};
+        if (data_durability)
+            body.data_durability = data_durability;
+        if (sync_number !== undefined)
+            body.sync_number = sync_number;
+        if (no_auto_failover_ack !== undefined)
+            body.no_auto_failover_ack = no_auto_failover_ack;
+        const result = await apiRequest(`/aws/v1/instances/${instance_id}`, { method: "PATCH", body, toolName: "set_postgres_durability", skipOrgInjection: true });
+        if (!result.success) {
+            return { content: [{ type: "text", text: `Failed to change durability (${result.statusCode}): ${result.message}` }] };
+        }
+        const d = result.data ?? {};
+        const notes = [`Durability is now \`${d.data_durability ?? data_durability}\`.`];
+        if (d.data_durability === "required") {
+            notes.push(d.sla_held
+                ? "`sla_held` is true, so this cluster is genuinely holding RPO 0 right now - it is the one state in which zero data loss is an accurate claim."
+                : "⚠️  `sla_held` is FALSE: the synchronous set is not being held, so the primary is refusing writes. Move to `preferred` or `async` to unwedge it, or bring a standby back.");
+            if (d.auto_failover_allowed === false) {
+                notes.push("Automated failover is OFF for this group - a primary failure needs manual intervention.");
+            }
+        }
+        else if (d.data_durability === "preferred" && d.degraded) {
+            notes.push("⚠️  `degraded` is true: no standby is healthy, so commits are being acked locally. Writes are flowing, but this is NOT zero data loss - do not describe it as such.");
+        }
+        else if (d.data_durability === "async") {
+            notes.push("Commits now ack locally. RPO is greater than zero: any zero-data-loss claim for this cluster is no longer true.");
+        }
+        return {
+            content: [
+                { type: "text", text: notes.join("\n\n") },
+                { type: "text", text: JSON.stringify(result.data, null, 2) },
+            ],
+        };
+    });
+    server.tool("get_opensearch_dashboards", `Read the OpenSearch Dashboards state for an instance - the opt-in Kibana-style UI on port ${OPENSEARCH_DASHBOARDS_PORT}.
+
+Returns \`dashboards_enabled\`, \`dashboards_status\` (\`disabled\` | \`installing\` | \`running\` | \`degraded\` | \`failed\`), \`dashboards_url\`, the instance's \`memory_gb\`, and two RAM verdicts: \`dashboards_supported\` (>= ${DASHBOARDS_MIN_RAM_GIB} GiB, the hard floor) and \`dashboards_recommended\` (>= ${DASHBOARDS_RECOMMENDED_RAM_GIB} GiB). Check \`dashboards_supported\` BEFORE offering to enable it - below the floor the enable is rejected outright.
+
+DASHBOARDS FAILING DOES NOT MEAN THE CLUSTER IS UNHEALTHY. It is co-located on the endpoint node as a Node.js process next to the JVM, and it is deliberately fail-soft and outside provisioning and readiness: the instance is ready when port ${ENGINE_DEFAULT_PORT.opensearch} is, whatever Dashboards is doing. Report a \`failed\` or \`degraded\` state as a separate, non-blocking fact, never as a broken database.
+
+422 on any non-OpenSearch instance.`, {
+        instance_id: z.string().min(1).describe("Instance PID (e.g. awsinst_xxx). Must be the cluster's endpoint node."),
+    }, async ({ instance_id }) => {
+        const result = await apiRequest(`/aws/v1/instances/${instance_id}/dashboards`, {
+            toolName: "get_opensearch_dashboards",
+            skipOrgInjection: true,
+        });
+        if (!result.success) {
+            return { content: [{ type: "text", text: `Failed to get Dashboards state (${result.statusCode}): ${result.message}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }] };
+    });
+    server.tool("set_opensearch_dashboards", `Turn the OpenSearch Dashboards UI on or off on an existing cluster (port ${OPENSEARCH_DASHBOARDS_PORT}). Unlike most of this engine's shape, this one IS a day-2 toggle in both directions.
+
+Call \`get_opensearch_dashboards\` first and check \`dashboards_supported\`: the endpoint node needs ${DASHBOARDS_MIN_RAM_GIB} GiB RAM to enable at all (${DASHBOARDS_RECOMMENDED_RAM_GIB} GiB recommended, since Dashboards is a Node.js process sharing the box with the OpenSearch JVM). Below the floor this is a 422.
+
+Other requirements the backend enforces: OpenSearch only, the cluster's ENDPOINT node only (not a manager or a non-endpoint data node), status \`running\` or \`provisioned\`, and a registered agent to enable.
+
+Enabling also opens ${OPENSEARCH_DASHBOARDS_PORT} on the security group. Poll \`get_opensearch_dashboards\` for \`installing\` → \`running\`; a \`failed\` outcome leaves the cluster itself healthy and serving on ${ENGINE_DEFAULT_PORT.opensearch}.`, {
+        instance_id: z.string().min(1).describe("Instance PID of the cluster's endpoint node"),
+        enabled: z.boolean().describe("true installs and starts Dashboards; false stops it and closes the port."),
+        confirm: z.boolean().describe("Must be true. Enabling adds a process competing with the JVM for memory on the endpoint node and opens another port; disabling takes the UI away from anyone using it."),
+    }, async ({ instance_id, enabled, confirm }) => {
+        if (!confirm) {
+            return {
+                content: [{
+                        type: "text",
+                        text: enabled
+                            ? `About to enable OpenSearch Dashboards on ${instance_id}. It runs on the endpoint node alongside the OpenSearch JVM (so it competes for memory) and opens port ${OPENSEARCH_DASHBOARDS_PORT}. Check \`dashboards_supported\` via get_opensearch_dashboards first.\n\nCall again with confirm=true.`
+                            : `About to disable OpenSearch Dashboards on ${instance_id}. The UI stops and port ${OPENSEARCH_DASHBOARDS_PORT} closes; the cluster keeps serving on ${ENGINE_DEFAULT_PORT.opensearch}.\n\nCall again with confirm=true.`,
                     }],
             };
         }
         const result = await apiRequest(`/aws/v1/instances/${instance_id}`, {
             method: "PATCH",
-            body: { db_version },
-            toolName: "upgrade_clickhouse_version",
+            body: { dashboards_enabled: enabled },
+            toolName: "set_opensearch_dashboards",
             skipOrgInjection: true,
         });
         if (!result.success) {
-            return { content: [{ type: "text", text: `Failed to upgrade ClickHouse version (${result.statusCode}): ${result.message}` }] };
+            return { content: [{ type: "text", text: `Failed to ${enabled ? "enable" : "disable"} Dashboards (${result.statusCode}): ${result.message}` }] };
         }
         return {
             content: [
-                { type: "text", text: `ClickHouse upgrade to ${db_version} requested. Poll get_instance to watch the version and status, then verify with SELECT version().` },
+                {
+                    type: "text",
+                    text: enabled
+                        ? `Dashboards enablement requested. Poll get_opensearch_dashboards until dashboards_status reaches \`running\`, then open dashboards_url. A \`failed\` state is a Dashboards problem only - the cluster stays healthy on ${ENGINE_DEFAULT_PORT.opensearch}.`
+                        : "Dashboards disabled. The port is closed and the cluster is unaffected.",
+                },
                 { type: "text", text: JSON.stringify(result.data, null, 2) },
             ],
         };