Update the AI docs for the 45 tool MCP core

.mintlify/Assistant.md

@@ -91,8 +91,8 @@ These are the areas where answers go wrong most often. The facts are grouped by
 
 - **Volume Set `fileSystemType` AND `performanceClass` are both immutable** after creation. `general-purpose-ssd` requires min 10 GB; `high-throughput-ssd` requires **min 200 GB**.
 - **Snapshots, `shrinkVolume`, `deleteVolume`, `restoreVolume`, and custom encryption are NOT supported on `shared` filesystem** — only `ext4` and `xfs`.
-- **Volume shrink (`cpln volumeset shrink`) destroys data** — it provisions a new smaller volume and permanently deletes the old one. Only safe for distributed systems with data replication.
-- **Volumes can only be expanded once every 6 hours.**
+- **Volume shrink (`cpln volumeset shrink`) keeps the data**: it copies it to a new smaller volume and keeps the old one if the copy fails. It is refused below the volume set's `initialCapacity`, below the used bytes plus 5%, or when the volume has no current usage metric.
+- **A volume can be expanded at most 4 times in a rolling 24 hours.**
 
 ### Images
 
@@ -231,7 +231,7 @@ These are the areas where answers go wrong most often. The facts are grouped by
 | `shared` (auto-set when fileSystemType is shared) | 10 GB | 65,536 GB |
 
 - **Both `fileSystemType` AND `performanceClass` are immutable** after creation.
-- Volumes can only be expanded once every 6 hours.
+- A volume can be expanded at most 4 times in a rolling 24 hours.
 - Mount in workload via `cpln://volumeset/VOLUMESET_NAME` with `recoveryPolicy: retain` (default) or `recycle`.
 
 ## Resource scoping

AGENTS.md

@@ -234,6 +234,6 @@ These are the most common sources of documentation errors:
 10. **Images** must be `linux/amd64`
 11. **Orgs are immutable** — once created, an org cannot be deleted
 12. **`cpln workload log` does NOT exist** — use `cpln logs '{gvc="GVC", workload="WORKLOAD"}'` with LogQL syntax
-13. **Volume shrink destroys data** — `shrinkVolume` provisions a NEW smaller volume; existing data is NOT migrated. Only use for systems with data replication (Kafka, CockroachDB)
+13. **Volume shrink keeps the data**: `shrinkVolume` copies it to a NEW smaller volume and keeps the old one if the copy fails. It is refused below the volume set's `initialCapacity`, below the used bytes plus 5%, or when the volume has no current usage metric
 14. **Don't set `spec.identityLink` unless needed** — only assign an identity when the workload needs secret access, credential-free cloud access, or private network access (via agents)
 15. **Never use `docker.io/` prefix for external images** — use the exact image reference as-is (e.g., `nginx:latest`, not `docker.io/library/nginx:latest`). The registry hostname `<org>.registry.cpln.io` is only for `docker login`, never in workload specs

ai/chatgpt.mdx

@@ -55,6 +55,10 @@ Control Plane is a listed plugin in the ChatGPT Plugin directory, so there is no
   The listing is fixed on the default **`core`** toolset profile and takes no query parameter of its own. For `mk8s` or `full`, register the MCP server directly in [Codex](/ai/codex) or another [MCP client](/ai/mcp). See [toolset profiles](/ai/mcp#toolset-profiles).
 </Note>
 
+<Note>
+  In ChatGPT the assistant works through the plugin's tools and never runs the `cpln` CLI. For the few steps only the CLI does, such as forwarding a port or opening a shell in a container, it gives you the command to run on your own machine.
+</Note>
+
 <Note>
   For the latest directory behavior, see OpenAI's [Plugins documentation](https://learn.chatgpt.com/docs/plugins).
 </Note>

ai/examples.mdx

@@ -219,7 +219,7 @@ and give the workload access to that secret.
 
 ### Restart, Roll Back, Promote, or Open a Workload
 
-Each of these is one call: the assistant makes the change, waits for the workload to be ready, and reports the result.
+Each of these is one call: the assistant makes the change, waits for the workload to be ready, and reports the result. Promoting needs the `full` profile.
 
 <CodeGroup>
 ```text Restart
@@ -242,7 +242,7 @@ Let workload "web" call workload "api-server" inside GVC "production", and tell
 
 ### Run a Cron Job Now or Replace a Stuck Replica
 
-Both have side effects in production, so the assistant confirms before running them.
+Both have side effects in production, so the assistant confirms before running them. Replacing a replica needs the `full` profile.
 
 <CodeGroup>
 ```text Run a Cron Job Now
@@ -313,6 +313,10 @@ Show logs for the "_accesslog" container of workload "web-frontend" in the last
 Get logs for workload "data-processor" from yesterday between 10:00 and 11:00 UTC.
 ```
 
+```text mk8s Cluster
+Show the kubelet logs of mk8s cluster "edge-cluster" from the last hour.
+```
+
 </CodeGroup>
 
 <Tip>
@@ -337,6 +341,10 @@ Find the slowest requests to "api-server" in the last hour and show me where
 the time went.
 ```
 
+```text mk8s Cluster
+Which nodes of mk8s cluster "edge-cluster" used the most CPU over the last day?
+```
+
 </CodeGroup>
 
 <Note>
@@ -345,6 +353,8 @@ the time went.
 
 ### Check the Audit Trail and Quotas
 
+The quota check needs the `full` or `readonly` profile.
+
 <CodeGroup>
 ```text Recent Changes
 Who changed workload "api-server" in GVC "production" in the last 24 hours, and when?
@@ -488,7 +498,7 @@ the link where I create its key.
 </CodeGroup>
 
 <Note>
-  A workload needs `reveal` to read a secret's values; `use` only attaches a secret to a GVC or workload. For a workload, `grant_workload_secret_access` sets the identity and the policy in one call. The service account key prompt needs the `full` profile, and the key is shown once, in the Console, never in the chat.
+  A workload needs `reveal` to read a secret's values; `use` only attaches a secret to a GVC or workload. For a workload, `grant_workload_secret_access` sets the identity and the policy in one call. The policy and service account prompts need the `full` profile, and the key is shown once, in the Console, never in the chat.
 </Note>
 
 ---
@@ -617,6 +627,8 @@ Deploy a complete application stack to Control Plane:
 
 ### Environment Promotion
 
+This needs the `full` profile.
+
 ```text
 Promote workloads "frontend" and "backend" from GVC "staging" to GVC
 "production". Show me what differs in production first, then promote them

ai/mcp.mdx

@@ -55,9 +55,9 @@ The full tool catalog is larger than most AI tools can hold in context at once 
 | Profile | What it includes |
 |---------|------------------|
 | `readonly` | Investigation only. Metrics, logs, traces, workload events, replicas and deployments, one-call workload diagnosis, quotas, the audit trail, configuration inventory, and Terraform export, plus a generic read tool that works on **every** resource kind. It advertises no tool that creates, updates, deletes or executes a command, so an assistant on this profile cannot change a live resource. |
-| `core` *(default)* | The everyday deploy-and-operate journey. [Job tools](/ai/tools#jobs) do a whole task in one call: deploy an app, add a database, create or rotate a secret without its value passing through the chat, and diagnose, restart, roll back, promote, or open a workload to other workloads. Around them: GVCs, workloads, deployments, logs, image builds (from a repository, or from app files the assistant writes itself, so a chat can take an app from the user's request to a running URL), custom domains, identities, policies, the template catalog, volume sets, Terraform export, metrics, traces, and the audit trail, plus a generic read/delete tool that works on **every** resource kind. |
+| `core` *(default)* | The everyday deploy-and-operate journey. [Job tools](/ai/tools#jobs) do a whole task in one call: deploy an app, add a database, create or rotate a secret without its value passing through the chat, and diagnose, restart, roll back, or open a workload to other workloads. Around them: GVCs, workloads, deployments, logs, image builds (from a repository, or from app files the assistant writes itself, so a chat can take an app from the user's request to a running URL), custom domains, the template catalog, volume sets with their snapshots and resizing, Terraform export, metrics, traces, the audit trail, and quota increase requests, plus a generic read/delete tool that works on **every** resource kind. |
 | `mk8s` | Everything in `core`, **plus** `create_mk8s` and `update_mk8s`, which create and update managed Kubernetes (mk8s) clusters on every supported provider. |
-| `full` | Everything in `mk8s`, **plus** the full administrative and fine-tuning surface: cloud-account registration (AWS, GCP, Azure, NATS), org IAM (users, groups, service accounts), network-bridge agents, identity network-resource bindings, IP sets, audit contexts, external logging, advanced workload tuning (load balancer, sidecar, rollout, security, retry), domain CORS, volume-set snapshots and shrinking, GVC location edits, and org settings. |
+| `full` | Everything in `mk8s`, **plus** the full administrative and fine-tuning surface: identities and policies, permission lookups, workload promotion, standalone volume set creation, quota and event reads, replica and command lists, replica stops, docs filesystem queries, cloud-account registration (AWS, GCP, Azure, NATS), org IAM (users, groups, service accounts), network-bridge agents, identity network-resource bindings, IP sets, audit contexts, external logging, advanced workload tuning (load balancer, sidecar, rollout, security, retry), and org settings. |
 
 ```text Examples
 https://mcp.cpln.io/mcp                    # core (default)

ai/plugin.mdx

@@ -41,15 +41,7 @@ keywords: ['claude code', 'codex', 'antigravity cli', 'cpln plugin', 'install pl
     Start Codex, open `/plugins`, navigate to **Control Plane**, then install the `cpln` plugin.
 
     <Tip>
-      **Enable plugin hooks (recommended).** Codex ships with `plugin_hooks` off by default. Enable it in `~/.codex/config.toml` so the plugin's `SessionStart` hook can load the Control Plane core rules at the start of each session:
-
-      ```toml
-      [features]
-      plugins = true
-      plugin_hooks = true
-      ```
-
-      After restart, `/plugins` → **Control Plane** → **Hooks** should show `SessionStart`.
+      **Trust the plugin's hook (recommended).** Codex runs a plugin's hooks only after you trust them. When Codex starts with a new or changed hook, it shows **Hooks need review**: choose **Review hooks** and trust the Control Plane `SessionStart` hook, or trust it later from `/hooks`. Once trusted, the hook loads the Control Plane core rules at the start of each session.
     </Tip>
 
     <Tip>